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 @@ 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 +