Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 225a4424 authored by Jason Wessel's avatar Jason Wessel Committed by Ingo Molnar
Browse files

kgdb: documentation fixes 



Minor cleanups to kgdb docs.

Signed-off-by: default avatarJason Wessel <jason.wessel@windriver.com>
Signed-off-by: default avatarIngo Molnar <mingo@elte.hu>
parent 974460c5

Documentation/DocBook/kgdb.tmpl

+58 −46
Original line number Original line Diff line number Diff line
@@ -152,9 +152,10 @@ 
  <para>

  <para>

  The kgdboc driver was originally an abbreviation meant to stand for

  The kgdboc driver was originally an abbreviation meant to stand for

  "kgdb over console".  Kgdboc is designed to work with a single

  "kgdb over console".  Kgdboc is designed to work with a single

  serial port as example, and it was meant to cover the circumstance

  serial port. It was meant to cover the circumstance

  where you wanted to use a serial console as your primary console as

  where you wanted to use a serial console as your primary console as

  well as using it to perform kernel debugging.

  well as using it to perform kernel debugging.  Of course you can

  also use kgdboc without assigning a console to the same port.

  </para>

  </para>

  <sect2 id="UsingKgdboc">

  <sect2 id="UsingKgdboc">

  <title>Using kgdboc</title>

  <title>Using kgdboc</title>
@@ -195,37 +196,6 @@ 
  unmodified gdb to do the debugging.

  unmodified gdb to do the debugging.

  </para>

  </para>

  </sect2>

  </sect2>

  <sect2 id="kgdbocDesign">

  <title>kgdboc internals</title>

  <para>

  The kgdboc driver is actually a very thin driver that relies on the

  underlying low level to the hardware driver having "polling hooks"

  which the to which the tty driver is attached.  In the initial

  implementation of kgdboc it the serial_core was changed to expose a

  low level uart hook for doing polled mode reading and writing of a

  single character while in an atomic context.  When kgdb makes an I/O

  request to the debugger, kgdboc invokes a call back in the serial

  core which in turn uses the call back in the uart driver.  It is

  certainly possible to extend kgdboc to work with non-uart based

  consoles in the future.

  </para>

  <para>

  When using kgdboc with a uart, the uart driver must implement two callbacks in the <constant>struct uart_ops</constant>. Example from drivers/8250.c:<programlisting>

#ifdef CONFIG_CONSOLE_POLL

	.poll_get_char = serial8250_get_poll_char,

	.poll_put_char = serial8250_put_poll_char,

#endif

  </programlisting>

  Any implementation specifics around creating a polling driver use the

  <constant>#ifdef CONFIG_CONSOLE_POLL</constant>, as shown above.

  Keep in mind that polling hooks have to be implemented in such a way

  that they can be called from an atomic context and have to restore

  the state of the uart chip on return such that the system can return

  to normal when the debugger detaches.  You need to be very careful

  with any kind of lock you consider, because failing here is most

  going to mean pressing the reset button.

  </para>

  </sect2>

  </sect1>

  </sect1>

  <sect1 id="kgdbcon">

  <sect1 id="kgdbcon">

  <title>Kernel parameter: kgdbcon</title>

  <title>Kernel parameter: kgdbcon</title>
@@ -327,6 +297,8 @@ 
    </para>

    </para>

  </chapter>

  </chapter>

  <chapter id="CommonBackEndReq">

  <chapter id="CommonBackEndReq">

  <title>KGDB Internals</title>

  <sect1 id="kgdbArchitecture">

    <title>Architecture Specifics</title>

    <title>Architecture Specifics</title>

      <para>

      <para>

      Kgdb is organized into three basic components:

      Kgdb is organized into three basic components:
@@ -365,18 +337,23 @@ 
      </listitem>

      </listitem>

      <listitem><para>kgdb I/O driver</para>

      <listitem><para>kgdb I/O driver</para>

      <para>

      <para>

      Each kgdb I/O driver has to provide an configuration

      Each kgdb I/O driver has to provide an implemenation for the following:

      initialization, and cleanup handler for when it

      <itemizedlist>

      unloads/unconfigures.  Any given kgdb I/O driver has to operate

      <listitem><para>configuration via builtin or module</para></listitem>

      very closely with the hardware and must do it in such a way that

      <listitem><para>dynamic configuration and kgdb hook registration calls</para></listitem>

      does not enable interrupts or change other parts of the system

      <listitem><para>read and write character interface</para></listitem>

      context without completely restoring them.  Every kgdb I/O

      <listitem><para>A cleanup handler for unconfiguring from the kgdb core</para></listitem>

      driver must provide a read and write character interface.  The

      <listitem><para>(optional) Early debug methodology</para></listitem>

      kgdb core will repeatedly "poll" a kgdb I/O driver for characters

      </itemizedlist>

      when it needs input.  The I/O driver is expected to return

      Any given kgdb I/O driver has to operate very closely with the

      immediately if there is no data available.  Doing so allows for

      hardware and must do it in such a way that does not enable

      the future possibility to touch watch dog hardware in such a way

      interrupts or change other parts of the system context without

      as to have a target system not reset when these are enabled.

      completely restoring them. The kgdb core will repeatedly "poll"

      a kgdb I/O driver for characters when it needs input.  The I/O

      driver is expected to return immediately if there is no data

      available.  Doing so allows for the future possibility to touch

      watch dog hardware in such a way as to have a target system not

      reset when these are enabled.

      </para>

      </para>

      </listitem>

      </listitem>

      </orderedlist>

      </orderedlist>
@@ -419,6 +396,38 @@ 
      does not need to provide a specific implementation.

      does not need to provide a specific implementation.

      </para>

      </para>

!Iinclude/linux/kgdb.h

!Iinclude/linux/kgdb.h

  </sect1>

  <sect1 id="kgdbocDesign">

  <title>kgdboc internals</title>

  <para>

  The kgdboc driver is actually a very thin driver that relies on the

  underlying low level to the hardware driver having "polling hooks"

  which the to which the tty driver is attached.  In the initial

  implementation of kgdboc it the serial_core was changed to expose a

  low level uart hook for doing polled mode reading and writing of a

  single character while in an atomic context.  When kgdb makes an I/O

  request to the debugger, kgdboc invokes a call back in the serial

  core which in turn uses the call back in the uart driver.  It is

  certainly possible to extend kgdboc to work with non-uart based

  consoles in the future.

  </para>

  <para>

  When using kgdboc with a uart, the uart driver must implement two callbacks in the <constant>struct uart_ops</constant>. Example from drivers/8250.c:<programlisting>

#ifdef CONFIG_CONSOLE_POLL

	.poll_get_char = serial8250_get_poll_char,

	.poll_put_char = serial8250_put_poll_char,

#endif

  </programlisting>

  Any implementation specifics around creating a polling driver use the

  <constant>#ifdef CONFIG_CONSOLE_POLL</constant>, as shown above.

  Keep in mind that polling hooks have to be implemented in such a way

  that they can be called from an atomic context and have to restore

  the state of the uart chip on return such that the system can return

  to normal when the debugger detaches.  You need to be very careful

  with any kind of lock you consider, because failing here is most

  going to mean pressing the reset button.

  </para>

  </sect1>

  </chapter>

  </chapter>

  <chapter id="credits">

  <chapter id="credits">

     <title>Credits</title>

     <title>Credits</title>
@@ -427,8 +436,11 @@ 
		<orderedlist>

		<orderedlist>

			<listitem><para>Amit Kale<email>amitkale@linsyssoft.com</email></para></listitem>

			<listitem><para>Amit Kale<email>amitkale@linsyssoft.com</email></para></listitem>

			<listitem><para>Tom Rini<email>trini@kernel.crashing.org</email></para></listitem>

			<listitem><para>Tom Rini<email>trini@kernel.crashing.org</email></para></listitem>

			<listitem><para>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem>

		</orderedlist>

		</orderedlist>

                In March 2008 this document was completely rewritten by:

		<itemizedlist>

		<listitem><para>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem>

		</itemizedlist>

	</para>

	</para>

  </chapter>

  </chapter>

</book>

</book>