aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorJason Wessel <jason.wessel@windriver.com>2008-04-01 17:55:26 -0400
committerIngo Molnar <mingo@elte.hu>2008-04-17 14:05:43 -0400
commit225a4424ade24e913c081d5a4c4bd71a0fe2e0ac (patch)
tree88706b695c592e877e5e22f53f88875c11b91898 /Documentation
parent974460c5bfd9f6c38aa3dda189a63f9fc351035f (diff)
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>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/DocBook/kgdb.tmpl104
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 @@
152 <para> 152 <para>
153 The kgdboc driver was originally an abbreviation meant to stand for 153 The kgdboc driver was originally an abbreviation meant to stand for
154 "kgdb over console". Kgdboc is designed to work with a single 154 "kgdb over console". Kgdboc is designed to work with a single
155 serial port as example, and it was meant to cover the circumstance 155 serial port. It was meant to cover the circumstance
156 where you wanted to use a serial console as your primary console as 156 where you wanted to use a serial console as your primary console as
157 well as using it to perform kernel debugging. 157 well as using it to perform kernel debugging. Of course you can
158 also use kgdboc without assigning a console to the same port.
158 </para> 159 </para>
159 <sect2 id="UsingKgdboc"> 160 <sect2 id="UsingKgdboc">
160 <title>Using kgdboc</title> 161 <title>Using kgdboc</title>
@@ -195,37 +196,6 @@
195 unmodified gdb to do the debugging. 196 unmodified gdb to do the debugging.
196 </para> 197 </para>
197 </sect2> 198 </sect2>
198 <sect2 id="kgdbocDesign">
199 <title>kgdboc internals</title>
200 <para>
201 The kgdboc driver is actually a very thin driver that relies on the
202 underlying low level to the hardware driver having "polling hooks"
203 which the to which the tty driver is attached. In the initial
204 implementation of kgdboc it the serial_core was changed to expose a
205 low level uart hook for doing polled mode reading and writing of a
206 single character while in an atomic context. When kgdb makes an I/O
207 request to the debugger, kgdboc invokes a call back in the serial
208 core which in turn uses the call back in the uart driver. It is
209 certainly possible to extend kgdboc to work with non-uart based
210 consoles in the future.
211 </para>
212 <para>
213 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>
214#ifdef CONFIG_CONSOLE_POLL
215 .poll_get_char = serial8250_get_poll_char,
216 .poll_put_char = serial8250_put_poll_char,
217#endif
218 </programlisting>
219 Any implementation specifics around creating a polling driver use the
220 <constant>#ifdef CONFIG_CONSOLE_POLL</constant>, as shown above.
221 Keep in mind that polling hooks have to be implemented in such a way
222 that they can be called from an atomic context and have to restore
223 the state of the uart chip on return such that the system can return
224 to normal when the debugger detaches. You need to be very careful
225 with any kind of lock you consider, because failing here is most
226 going to mean pressing the reset button.
227 </para>
228 </sect2>
229 </sect1> 199 </sect1>
230 <sect1 id="kgdbcon"> 200 <sect1 id="kgdbcon">
231 <title>Kernel parameter: kgdbcon</title> 201 <title>Kernel parameter: kgdbcon</title>
@@ -327,6 +297,8 @@
327 </para> 297 </para>
328 </chapter> 298 </chapter>
329 <chapter id="CommonBackEndReq"> 299 <chapter id="CommonBackEndReq">
300 <title>KGDB Internals</title>
301 <sect1 id="kgdbArchitecture">
330 <title>Architecture Specifics</title> 302 <title>Architecture Specifics</title>
331 <para> 303 <para>
332 Kgdb is organized into three basic components: 304 Kgdb is organized into three basic components:
@@ -365,18 +337,23 @@
365 </listitem> 337 </listitem>
366 <listitem><para>kgdb I/O driver</para> 338 <listitem><para>kgdb I/O driver</para>
367 <para> 339 <para>
368 Each kgdb I/O driver has to provide an configuration 340 Each kgdb I/O driver has to provide an implemenation for the following:
369 initialization, and cleanup handler for when it 341 <itemizedlist>
370 unloads/unconfigures. Any given kgdb I/O driver has to operate 342 <listitem><para>configuration via builtin or module</para></listitem>
371 very closely with the hardware and must do it in such a way that 343 <listitem><para>dynamic configuration and kgdb hook registration calls</para></listitem>
372 does not enable interrupts or change other parts of the system 344 <listitem><para>read and write character interface</para></listitem>
373 context without completely restoring them. Every kgdb I/O 345 <listitem><para>A cleanup handler for unconfiguring from the kgdb core</para></listitem>
374 driver must provide a read and write character interface. The 346 <listitem><para>(optional) Early debug methodology</para></listitem>
375 kgdb core will repeatedly "poll" a kgdb I/O driver for characters 347 </itemizedlist>
376 when it needs input. The I/O driver is expected to return 348 Any given kgdb I/O driver has to operate very closely with the
377 immediately if there is no data available. Doing so allows for 349 hardware and must do it in such a way that does not enable
378 the future possibility to touch watch dog hardware in such a way 350 interrupts or change other parts of the system context without
379 as to have a target system not reset when these are enabled. 351 completely restoring them. The kgdb core will repeatedly "poll"
352 a kgdb I/O driver for characters when it needs input. The I/O
353 driver is expected to return immediately if there is no data
354 available. Doing so allows for the future possibility to touch
355 watch dog hardware in such a way as to have a target system not
356 reset when these are enabled.
380 </para> 357 </para>
381 </listitem> 358 </listitem>
382 </orderedlist> 359 </orderedlist>
@@ -419,6 +396,38 @@
419 does not need to provide a specific implementation. 396 does not need to provide a specific implementation.
420 </para> 397 </para>
421!Iinclude/linux/kgdb.h 398!Iinclude/linux/kgdb.h
399 </sect1>
400 <sect1 id="kgdbocDesign">
401 <title>kgdboc internals</title>
402 <para>
403 The kgdboc driver is actually a very thin driver that relies on the
404 underlying low level to the hardware driver having "polling hooks"
405 which the to which the tty driver is attached. In the initial
406 implementation of kgdboc it the serial_core was changed to expose a
407 low level uart hook for doing polled mode reading and writing of a
408 single character while in an atomic context. When kgdb makes an I/O
409 request to the debugger, kgdboc invokes a call back in the serial
410 core which in turn uses the call back in the uart driver. It is
411 certainly possible to extend kgdboc to work with non-uart based
412 consoles in the future.
413 </para>
414 <para>
415 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>
416#ifdef CONFIG_CONSOLE_POLL
417 .poll_get_char = serial8250_get_poll_char,
418 .poll_put_char = serial8250_put_poll_char,
419#endif
420 </programlisting>
421 Any implementation specifics around creating a polling driver use the
422 <constant>#ifdef CONFIG_CONSOLE_POLL</constant>, as shown above.
423 Keep in mind that polling hooks have to be implemented in such a way
424 that they can be called from an atomic context and have to restore
425 the state of the uart chip on return such that the system can return
426 to normal when the debugger detaches. You need to be very careful
427 with any kind of lock you consider, because failing here is most
428 going to mean pressing the reset button.
429 </para>
430 </sect1>
422 </chapter> 431 </chapter>
423 <chapter id="credits"> 432 <chapter id="credits">
424 <title>Credits</title> 433 <title>Credits</title>
@@ -427,8 +436,11 @@
427 <orderedlist> 436 <orderedlist>
428 <listitem><para>Amit Kale<email>amitkale@linsyssoft.com</email></para></listitem> 437 <listitem><para>Amit Kale<email>amitkale@linsyssoft.com</email></para></listitem>
429 <listitem><para>Tom Rini<email>trini@kernel.crashing.org</email></para></listitem> 438 <listitem><para>Tom Rini<email>trini@kernel.crashing.org</email></para></listitem>
430 <listitem><para>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem>
431 </orderedlist> 439 </orderedlist>
440 In March 2008 this document was completely rewritten by:
441 <itemizedlist>
442 <listitem><para>Jason Wessel<email>jason.wessel@windriver.com</email></para></listitem>
443 </itemizedlist>
432 </para> 444 </para>
433 </chapter> 445 </chapter>
434</book> 446</book>