kgdb: documentation fixes

Minor cleanups to kgdb docs.

Signed-off-by: Jason Wessel <jason.wessel@windriver.com>
Signed-off-by: Ingo Molnar <mingo@elte.hu>

1 files changed, 58 insertions, 46 deletions

diff --git a/Documentation/DocBook/kgdb.tmpl b/Documentation/DocBook/kgdb.tmpl
index 95e5f84cbf5..97618bed4d6 100644
--- a/Documentation/DocBook/kgdb.tmpl
+++ b/Documentation/DocBook/kgdb.tmpl
@@ -152,9 +152,10 @@
   <para>
   The kgdboc driver was originally an abbreviation meant to stand for
   "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
-  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>
   <sect2 id="UsingKgdboc">
   <title>Using kgdboc</title>
@@ -195,37 +196,6 @@
   unmodified gdb to do the debugging.
   </para>
   </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 id="kgdbcon">
   <title>Kernel parameter: kgdbcon</title>
@@ -327,6 +297,8 @@
     </para>
   </chapter>
   <chapter id="CommonBackEndReq">
+  <title>KGDB Internals</title>
+  <sect1 id="kgdbArchitecture">
     <title>Architecture Specifics</title>
       <para>
       Kgdb is organized into three basic components:
@@ -365,18 +337,23 @@
       </listitem>
       <listitem><para>kgdb I/O driver</para>
       <para>
-      Each kgdb I/O driver has to provide an configuration
-      initialization, and cleanup handler for when it
-      unloads/unconfigures.  Any given kgdb I/O driver has to operate
-      very closely with the hardware and must do it in such a way that
-      does not enable interrupts or change other parts of the system
-      context without completely restoring them.  Every kgdb I/O
-      driver must provide a read and write character interface.  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.
+      Each kgdb I/O driver has to provide an implemenation for the following:
+      <itemizedlist>
+      <listitem><para>configuration via builtin or module</para></listitem>
+      <listitem><para>dynamic configuration and kgdb hook registration calls</para></listitem>
+      <listitem><para>read and write character interface</para></listitem>
+      <listitem><para>A cleanup handler for unconfiguring from the kgdb core</para></listitem>
+      <listitem><para>(optional) Early debug methodology</para></listitem>
+      </itemizedlist>
+      Any given kgdb I/O driver has to operate very closely with the
+      hardware and must do it in such a way that does not enable
+      interrupts or change other parts of the system context without
+      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>
       </listitem>
       </orderedlist>
@@ -419,6 +396,38 @@
       does not need to provide a specific implementation.
       </para>
 !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 id="credits">
      <title>Credits</title>
@@ -427,8 +436,11 @@
                 <orderedlist>
                         <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>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem>
                 </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>
   </chapter>
 </book>