aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/kgdb.tmpl
diff options
context:
space:
mode:
authorJason Wessel <jason.wessel@windriver.com>2010-08-05 10:22:33 -0400
committerJason Wessel <jason.wessel@windriver.com>2010-08-05 11:53:11 -0400
commit65b5ac1479840a3e87f086d68e5ef91f3002e8e2 (patch)
treef42c6e29a4f8a7796e6dd59b67136ddbeb957acd /Documentation/DocBook/kgdb.tmpl
parentf90ebd9e98f366c41773ad8d0482dade668f5103 (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.tmpl108
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=&lt;tty-device&gt;,[baud]</constant></para> 237 <para>Use the command: <constant>modprobe kgdboc kgdboc=&lt;tty-device&gt;,[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>
848static 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>
860static 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">