diff options
| -rw-r--r-- | Documentation/DocBook/kgdb.tmpl | 104 |
1 files changed, 58 insertions, 46 deletions
diff --git a/Documentation/DocBook/kgdb.tmpl b/Documentation/DocBook/kgdb.tmpl index 95e5f84cbf56..97618bed4d65 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> |