diff options
author | Jason Wessel <jason.wessel@windriver.com> | 2010-08-05 10:22:33 -0400 |
---|---|---|
committer | Jason Wessel <jason.wessel@windriver.com> | 2010-08-05 11:53:11 -0400 |
commit | 65b5ac1479840a3e87f086d68e5ef91f3002e8e2 (patch) | |
tree | f42c6e29a4f8a7796e6dd59b67136ddbeb957acd /Documentation/DocBook/kgdb.tmpl | |
parent | f90ebd9e98f366c41773ad8d0482dade668f5103 (diff) |
kgdb,docs: Update the kgdb docs to include kms
Update the kgdb docs to include information about kernel mode setting support.
[Randy Dunlap <rdunlap@xenotime.net>: grammatical corrections]
CC: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Jason Wessel <jason.wessel@windriver.com>
Diffstat (limited to 'Documentation/DocBook/kgdb.tmpl')
-rw-r--r-- | Documentation/DocBook/kgdb.tmpl | 108 |
1 files changed, 100 insertions, 8 deletions
diff --git a/Documentation/DocBook/kgdb.tmpl b/Documentation/DocBook/kgdb.tmpl index 55f12ac37acd..490d862c5f0d 100644 --- a/Documentation/DocBook/kgdb.tmpl +++ b/Documentation/DocBook/kgdb.tmpl | |||
@@ -199,10 +199,33 @@ | |||
199 | may be configured as a kernel built-in or a kernel loadable module. | 199 | may be configured as a kernel built-in or a kernel loadable module. |
200 | You can only make use of <constant>kgdbwait</constant> and early | 200 | You can only make use of <constant>kgdbwait</constant> and early |
201 | debugging if you build kgdboc into the kernel as a built-in. | 201 | debugging if you build kgdboc into the kernel as a built-in. |
202 | <para>Optionally you can elect to activate kms (Kernel Mode | ||
203 | Setting) integration. When you use kms with kgdboc and you have a | ||
204 | video driver that has atomic mode setting hooks, it is possible to | ||
205 | enter the debugger on the graphics console. When the kernel | ||
206 | execution is resumed, the previous graphics mode will be restored. | ||
207 | This integration can serve as a useful tool to aid in diagnosing | ||
208 | crashes or doing analysis of memory with kdb while allowing the | ||
209 | full graphics console applications to run. | ||
210 | </para> | ||
202 | </para> | 211 | </para> |
203 | <sect2 id="kgdbocArgs"> | 212 | <sect2 id="kgdbocArgs"> |
204 | <title>kgdboc arguments</title> | 213 | <title>kgdboc arguments</title> |
205 | <para>Usage: <constant>kgdboc=[kbd][[,]serial_device][,baud]</constant></para> | 214 | <para>Usage: <constant>kgdboc=[kms][[,]kbd][[,]serial_device][,baud]</constant></para> |
215 | <para>The order listed above must be observed if you use any of the | ||
216 | optional configurations together. | ||
217 | </para> | ||
218 | <para>Abbreviations: | ||
219 | <itemizedlist> | ||
220 | <listitem><para>kms = Kernel Mode Setting</para></listitem> | ||
221 | <listitem><para>kbd = Keyboard</para></listitem> | ||
222 | </itemizedlist> | ||
223 | </para> | ||
224 | <para>You can configure kgdboc to use the keyboard, and or a serial | ||
225 | device depending on if you are using kdb and or kgdb, in one of the | ||
226 | following scenarios. The order listed above must be observed if | ||
227 | you use any of the optional configurations together. Using kms + | ||
228 | only gdb is generally not a useful combination.</para> | ||
206 | <sect3 id="kgdbocArgs1"> | 229 | <sect3 id="kgdbocArgs1"> |
207 | <title>Using loadable module or built-in</title> | 230 | <title>Using loadable module or built-in</title> |
208 | <para> | 231 | <para> |
@@ -212,7 +235,7 @@ | |||
212 | <listitem> | 235 | <listitem> |
213 | <para>As a kernel loadable module:</para> | 236 | <para>As a kernel loadable module:</para> |
214 | <para>Use the command: <constant>modprobe kgdboc kgdboc=<tty-device>,[baud]</constant></para> | 237 | <para>Use the command: <constant>modprobe kgdboc kgdboc=<tty-device>,[baud]</constant></para> |
215 | <para>Here are two examples of how you might formate the kgdboc | 238 | <para>Here are two examples of how you might format the kgdboc |
216 | string. The first is for an x86 target using the first serial port. | 239 | string. The first is for an x86 target using the first serial port. |
217 | The second example is for the ARM Versatile AB using the second | 240 | The second example is for the ARM Versatile AB using the second |
218 | serial port. | 241 | serial port. |
@@ -240,6 +263,9 @@ | |||
240 | </sect3> | 263 | </sect3> |
241 | <sect3 id="kgdbocArgs3"> | 264 | <sect3 id="kgdbocArgs3"> |
242 | <title>More examples</title> | 265 | <title>More examples</title> |
266 | <para>You can configure kgdboc to use the keyboard, and or a serial | ||
267 | device depending on if you are using kdb and or kgdb, in one of the | ||
268 | following scenarios.</para> | ||
243 | <para>You can configure kgdboc to use the keyboard, and or a serial device | 269 | <para>You can configure kgdboc to use the keyboard, and or a serial device |
244 | depending on if you are using kdb and or kgdb, in one of the | 270 | depending on if you are using kdb and or kgdb, in one of the |
245 | following scenarios. | 271 | following scenarios. |
@@ -255,6 +281,12 @@ | |||
255 | <listitem><para>kdb with a keyboard</para> | 281 | <listitem><para>kdb with a keyboard</para> |
256 | <para><constant>kgdboc=kbd</constant></para> | 282 | <para><constant>kgdboc=kbd</constant></para> |
257 | </listitem> | 283 | </listitem> |
284 | <listitem><para>kdb with kernel mode setting</para> | ||
285 | <para><constant>kgdboc=kms,kbd</constant></para> | ||
286 | </listitem> | ||
287 | <listitem><para>kdb with kernel mode setting and kgdb over a serial port</para> | ||
288 | <para><constant>kgdboc=kms,kbd,ttyS0,115200</constant></para> | ||
289 | </listitem> | ||
258 | </orderedlist> | 290 | </orderedlist> |
259 | </para> | 291 | </para> |
260 | </sect3> | 292 | </sect3> |
@@ -637,6 +669,8 @@ Task Addr Pid Parent [*] cpu State Thread Command | |||
637 | <listitem><para>The logic to perform safe memory reads and writes to memory while using the debugger</para></listitem> | 669 | <listitem><para>The logic to perform safe memory reads and writes to memory while using the debugger</para></listitem> |
638 | <listitem><para>A full implementation for software breakpoints unless overridden by the arch</para></listitem> | 670 | <listitem><para>A full implementation for software breakpoints unless overridden by the arch</para></listitem> |
639 | <listitem><para>The API to invoke either the kdb or kgdb frontend to the debug core.</para></listitem> | 671 | <listitem><para>The API to invoke either the kdb or kgdb frontend to the debug core.</para></listitem> |
672 | <listitem><para>The structures and callback API for atomic kernel mode setting.</para> | ||
673 | <para>NOTE: kgdboc is where the kms callbacks are invoked.</para></listitem> | ||
640 | </itemizedlist> | 674 | </itemizedlist> |
641 | </para> | 675 | </para> |
642 | </listitem> | 676 | </listitem> |
@@ -747,6 +781,8 @@ Task Addr Pid Parent [*] cpu State Thread Command | |||
747 | </sect1> | 781 | </sect1> |
748 | <sect1 id="kgdbocDesign"> | 782 | <sect1 id="kgdbocDesign"> |
749 | <title>kgdboc internals</title> | 783 | <title>kgdboc internals</title> |
784 | <sect2> | ||
785 | <title>kgdboc and uarts</title> | ||
750 | <para> | 786 | <para> |
751 | The kgdboc driver is actually a very thin driver that relies on the | 787 | The kgdboc driver is actually a very thin driver that relies on the |
752 | underlying low level to the hardware driver having "polling hooks" | 788 | underlying low level to the hardware driver having "polling hooks" |
@@ -754,11 +790,8 @@ Task Addr Pid Parent [*] cpu State Thread Command | |||
754 | implementation of kgdboc it the serial_core was changed to expose a | 790 | implementation of kgdboc it the serial_core was changed to expose a |
755 | low level UART hook for doing polled mode reading and writing of a | 791 | low level UART hook for doing polled mode reading and writing of a |
756 | single character while in an atomic context. When kgdb makes an I/O | 792 | single character while in an atomic context. When kgdb makes an I/O |
757 | request to the debugger, kgdboc invokes a call back in the serial | 793 | request to the debugger, kgdboc invokes a callback in the serial |
758 | core which in turn uses the call back in the UART driver. It is | 794 | core which in turn uses the callback in the UART driver.</para> |
759 | certainly possible to extend kgdboc to work with non-UART based | ||
760 | consoles in the future. | ||
761 | </para> | ||
762 | <para> | 795 | <para> |
763 | 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> | 796 | 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> |
764 | #ifdef CONFIG_CONSOLE_POLL | 797 | #ifdef CONFIG_CONSOLE_POLL |
@@ -772,9 +805,68 @@ Task Addr Pid Parent [*] cpu State Thread Command | |||
772 | that they can be called from an atomic context and have to restore | 805 | that they can be called from an atomic context and have to restore |
773 | the state of the UART chip on return such that the system can return | 806 | the state of the UART chip on return such that the system can return |
774 | to normal when the debugger detaches. You need to be very careful | 807 | to normal when the debugger detaches. You need to be very careful |
775 | with any kind of lock you consider, because failing here is most | 808 | with any kind of lock you consider, because failing here is most likely |
776 | going to mean pressing the reset button. | 809 | going to mean pressing the reset button. |
777 | </para> | 810 | </para> |
811 | </sect2> | ||
812 | <sect2 id="kgdbocKbd"> | ||
813 | <title>kgdboc and keyboards</title> | ||
814 | <para>The kgdboc driver contains logic to configure communications | ||
815 | with an attached keyboard. The keyboard infrastructure is only | ||
816 | compiled into the kernel when CONFIG_KDB_KEYBOARD=y is set in the | ||
817 | kernel configuration.</para> | ||
818 | <para>The core polled keyboard driver driver for PS/2 type keyboards | ||
819 | is in drivers/char/kdb_keyboard.c. This driver is hooked into the | ||
820 | debug core when kgdboc populates the callback in the array | ||
821 | called <constant>kdb_poll_funcs[]</constant>. The | ||
822 | kdb_get_kbd_char() is the top-level function which polls hardware | ||
823 | for single character input. | ||
824 | </para> | ||
825 | </sect2> | ||
826 | <sect2 id="kgdbocKms"> | ||
827 | <title>kgdboc and kms</title> | ||
828 | <para>The kgdboc driver contains logic to request the graphics | ||
829 | display to switch to a text context when you are using | ||
830 | "kgdboc=kms,kbd", provided that you have a video driver which has a | ||
831 | frame buffer console and atomic kernel mode setting support.</para> | ||
832 | <para> | ||
833 | Every time the kernel | ||
834 | debugger is entered it calls kgdboc_pre_exp_handler() which in turn | ||
835 | calls con_debug_enter() in the virtual console layer. On resuming kernel | ||
836 | execution, the kernel debugger calls kgdboc_post_exp_handler() which | ||
837 | in turn calls con_debug_leave().</para> | ||
838 | <para>Any video driver that wants to be compatible with the kernel | ||
839 | debugger and the atomic kms callbacks must implement the | ||
840 | mode_set_base_atomic, fb_debug_enter and fb_debug_leave operations. | ||
841 | For the fb_debug_enter and fb_debug_leave the option exists to use | ||
842 | the generic drm fb helper functions or implement something custom for | ||
843 | the hardware. The following example shows the initialization of the | ||
844 | .mode_set_base_atomic operation in | ||
845 | drivers/gpu/drm/i915/intel_display.c: | ||
846 | <informalexample> | ||
847 | <programlisting> | ||
848 | static const struct drm_crtc_helper_funcs intel_helper_funcs = { | ||
849 | [...] | ||
850 | .mode_set_base_atomic = intel_pipe_set_base_atomic, | ||
851 | [...] | ||
852 | }; | ||
853 | </programlisting> | ||
854 | </informalexample> | ||
855 | </para> | ||
856 | <para>Here is an example of how the i915 driver initializes the fb_debug_enter and fb_debug_leave functions to use the generic drm helpers in | ||
857 | drivers/gpu/drm/i915/intel_fb.c: | ||
858 | <informalexample> | ||
859 | <programlisting> | ||
860 | static struct fb_ops intelfb_ops = { | ||
861 | [...] | ||
862 | .fb_debug_enter = drm_fb_helper_debug_enter, | ||
863 | .fb_debug_leave = drm_fb_helper_debug_leave, | ||
864 | [...] | ||
865 | }; | ||
866 | </programlisting> | ||
867 | </informalexample> | ||
868 | </para> | ||
869 | </sect2> | ||
778 | </sect1> | 870 | </sect1> |
779 | </chapter> | 871 | </chapter> |
780 | <chapter id="credits"> | 872 | <chapter id="credits"> |