diff --git a/Documentation/DocBook/kgdb.tmpl b/Documentation/DocBook/kgdb.tmpl
index 95e5f84cbf56bb7422b393b066394cc5bf2fd417..97618bed4d657538201b4073e159147b3cfbf115 100644
--- a/Documentation/DocBook/kgdb.tmpl
+++ b/Documentation/DocBook/kgdb.tmpl
@@ -152,9 +152,10 @@
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.
Using kgdboc
@@ -195,37 +196,6 @@
unmodified gdb to do the debugging.
-
- kgdboc internals
-
- 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.
-
-
- When using kgdboc with a uart, the uart driver must implement two callbacks in the struct uart_ops. Example from drivers/8250.c:
-#ifdef CONFIG_CONSOLE_POLL
- .poll_get_char = serial8250_get_poll_char,
- .poll_put_char = serial8250_put_poll_char,
-#endif
-
- Any implementation specifics around creating a polling driver use the
- #ifdef CONFIG_CONSOLE_POLL, 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.
-
-
Kernel parameter: kgdbcon
@@ -327,6 +297,8 @@
+ KGDB Internals
+
Architecture Specifics
Kgdb is organized into three basic components:
@@ -365,18 +337,23 @@
kgdb I/O driver
- 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:
+
+ configuration via builtin or module
+ dynamic configuration and kgdb hook registration calls
+ read and write character interface
+ A cleanup handler for unconfiguring from the kgdb core
+ (optional) Early debug methodology
+
+ 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.
@@ -419,6 +396,38 @@
does not need to provide a specific implementation.
!Iinclude/linux/kgdb.h
+
+
+ kgdboc internals
+
+ 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.
+
+
+ When using kgdboc with a uart, the uart driver must implement two callbacks in the struct uart_ops. Example from drivers/8250.c:
+#ifdef CONFIG_CONSOLE_POLL
+ .poll_get_char = serial8250_get_poll_char,
+ .poll_put_char = serial8250_put_poll_char,
+#endif
+
+ Any implementation specifics around creating a polling driver use the
+ #ifdef CONFIG_CONSOLE_POLL, 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.
+
+
Credits
@@ -427,8 +436,11 @@
Amit Kaleamitkale@linsyssoft.com
Tom Rinitrini@kernel.crashing.org
- Jason Wesseljason.wessel@windriver.com
+ In March 2008 this document was completely rewritten by:
+
+ Jason Wesseljason.wessel@windriver.com
+