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>

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>
Jason Wessel
1 parent f90ebd9e98
Showing 2 changed files with 106 additions and 11 deletions Side-by-side Diff
Documentation/DocBook/kgdb.tmpl
Documentation/kernel-parameters.txt
@@ -199,10 +199,33 @@
    may be configured as a kernel built-in or a kernel loadable module.
    You can only make use of <constant>kgdbwait</constant> and early
    debugging if you build kgdboc into the kernel as a built-in.
+   <para>Optionally you can elect to activate kms (Kernel Mode
+   Setting) integration.  When you use kms with kgdboc and you have a
+   video driver that has atomic mode setting hooks, it is possible to
+   enter the debugger on the graphics console.  When the kernel
+   execution is resumed, the previous graphics mode will be restored.
+   This integration can serve as a useful tool to aid in diagnosing
+   crashes or doing analysis of memory with kdb while allowing the
+   full graphics console applications to run.
    </para>
+   </para>
    <sect2 id="kgdbocArgs">
    <title>kgdboc arguments</title>
-   <para>Usage: <constant>kgdboc=[kbd][[,]serial_device][,baud]</constant></para>
+   <para>Usage: <constant>kgdboc=[kms][[,]kbd][[,]serial_device][,baud]</constant></para>
+   <para>The order listed above must be observed if you use any of the
+   optional configurations together.
+   </para>
+   <para>Abbreviations:
+   <itemizedlist>
+   <listitem><para>kms = Kernel Mode Setting</para></listitem>
+   <listitem><para>kbd = Keyboard</para></listitem>
+   </itemizedlist>
+   </para>
+   <para>You can configure kgdboc to use the keyboard, and or a serial
+   device depending on if you are using kdb and or kgdb, in one of the
+   following scenarios.  The order listed above must be observed if
+   you use any of the optional configurations together.  Using kms +
+   only gdb is generally not a useful combination.</para>
    <sect3 id="kgdbocArgs1">
    <title>Using loadable module or built-in</title>
    <para>
@@ -212,7 +235,7 @@
    <listitem>
    <para>As a kernel loadable module:</para>
    <para>Use the command: <constant>modprobe kgdboc kgdboc=&lt;tty-device&gt;,[baud]</constant></para>
-   <para>Here are two examples of how you might formate the kgdboc
+   <para>Here are two examples of how you might format the kgdboc
    string. The first is for an x86 target using the first serial port.
    The second example is for the ARM Versatile AB using the second
    serial port.
@@ -240,6 +263,9 @@
    </sect3>
    <sect3 id="kgdbocArgs3">
    <title>More examples</title>
+   <para>You can configure kgdboc to use the keyboard, and or a serial
+   device depending on if you are using kdb and or kgdb, in one of the
+   following scenarios.</para>
    <para>You can configure kgdboc to use the keyboard, and or a serial device
    depending on if you are using kdb and or kgdb, in one of the
    following scenarios.
@@ -255,6 +281,12 @@
    <listitem><para>kdb with a keyboard</para>
    <para><constant>kgdboc=kbd</constant></para>
    </listitem>
+   <listitem><para>kdb with kernel mode setting</para>
+   <para><constant>kgdboc=kms,kbd</constant></para>
+   </listitem>
+   <listitem><para>kdb with kernel mode setting and kgdb over a serial port</para>
+   <para><constant>kgdboc=kms,kbd,ttyS0,115200</constant></para>
+   </listitem>
    </orderedlist>
    </para>
    </sect3>
@@ -637,6 +669,8 @@
       <listitem><para>The logic to perform safe memory reads and writes to memory while using the debugger</para></listitem>
       <listitem><para>A full implementation for software breakpoints unless overridden by the arch</para></listitem>
       <listitem><para>The API to invoke either the kdb or kgdb frontend to the debug core.</para></listitem>
+      <listitem><para>The structures and callback API for atomic kernel mode setting.</para>
+      <para>NOTE: kgdboc is where the kms callbacks are invoked.</para></listitem>
       </itemizedlist>
       </para>
       </listitem>
@@ -747,6 +781,8 @@
   </sect1>
   <sect1 id="kgdbocDesign">
   <title>kgdboc internals</title>
+  <sect2>
+  <title>kgdboc and uarts</title>
   <para>
   The kgdboc driver is actually a very thin driver that relies on the
   underlying low level to the hardware driver having "polling hooks"
@@ -754,11 +790,8 @@
   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.
-  </para>
+  request to the debugger, kgdboc invokes a callback in the serial
+  core which in turn uses the callback in the UART driver.</para>
   <para>
   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>
 #ifdef CONFIG_CONSOLE_POLL
  
@@ -772,9 +805,68 @@
   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
+  with any kind of lock you consider, because failing here is most likely
   going to mean pressing the reset button.
   </para>
+  </sect2>
+  <sect2 id="kgdbocKbd">
+  <title>kgdboc and keyboards</title>
+  <para>The kgdboc driver contains logic to configure communications
+  with an attached keyboard.  The keyboard infrastructure is only
+  compiled into the kernel when CONFIG_KDB_KEYBOARD=y is set in the
+  kernel configuration.</para>
+  <para>The core polled keyboard driver driver for PS/2 type keyboards
+  is in drivers/char/kdb_keyboard.c.  This driver is hooked into the
+  debug core when kgdboc populates the callback in the array
+  called <constant>kdb_poll_funcs[]</constant>.  The
+  kdb_get_kbd_char() is the top-level function which polls hardware
+  for single character input.
+  </para>
+  </sect2>
+  <sect2 id="kgdbocKms">
+  <title>kgdboc and kms</title>
+  <para>The kgdboc driver contains logic to request the graphics
+  display to switch to a text context when you are using
+  "kgdboc=kms,kbd", provided that you have a video driver which has a
+  frame buffer console and atomic kernel mode setting support.</para>
+  <para>
+  Every time the kernel
+  debugger is entered it calls kgdboc_pre_exp_handler() which in turn
+  calls con_debug_enter() in the virtual console layer.  On resuming kernel
+  execution, the kernel debugger calls kgdboc_post_exp_handler() which
+  in turn calls con_debug_leave().</para>
+  <para>Any video driver that wants to be compatible with the kernel
+  debugger and the atomic kms callbacks must implement the
+  mode_set_base_atomic, fb_debug_enter and fb_debug_leave operations.
+  For the fb_debug_enter and fb_debug_leave the option exists to use
+  the generic drm fb helper functions or implement something custom for
+  the hardware.  The following example shows the initialization of the
+  .mode_set_base_atomic operation in
+  drivers/gpu/drm/i915/intel_display.c:
+  <informalexample>
+  <programlisting>
+static const struct drm_crtc_helper_funcs intel_helper_funcs = {
+[...]
+        .mode_set_base_atomic = intel_pipe_set_base_atomic,
+[...]
+};
+  </programlisting>
+  </informalexample>
+  </para>
+  <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
+  drivers/gpu/drm/i915/intel_fb.c:
+  <informalexample>
+  <programlisting>
+static struct fb_ops intelfb_ops = {
+[...]
+       .fb_debug_enter = drm_fb_helper_debug_enter,
+       .fb_debug_leave = drm_fb_helper_debug_leave,
+[...]
+};
+  </programlisting>
+  </informalexample>
+  </para>
+  </sect2>
   </sect1>
   </chapter>
   <chapter id="credits">
@@ -1143,9 +1143,12 @@
 	kgdboc=		[KGDB,HW] kgdb over consoles.
 			Requires a tty driver that supports console polling,
 			or a supported polling keyboard driver (non-usb).
-			Serial only format: <serial_device>[,baud]
-			keyboard only format: kbd
-			keyboard and serial format: kbd,<serial_device>[,baud]
+			 Serial only format: <serial_device>[,baud]
+			 keyboard only format: kbd
+			 keyboard and serial format: kbd,<serial_device>[,baud]
+			Optional Kernel mode setting:
+			 kms, kbd format: kms,kbd
+			 kms, kbd and serial format: kms,kbd,<ser_dev>[,baud]
  
 	kgdbwait	[KGDB] Stop kernel execution and enter the
 			kernel debugger at the earliest opportunity.
...	...	@@ -199,10 +199,33 @@
199	199	may be configured as a kernel built-in or a kernel loadable module.
200	200	You can only make use of <constant>kgdbwait</constant> and early
201	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.
202	210	</para>
	211	+ </para>
203	212	<sect2 id="kgdbocArgs">
204	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	229	<sect3 id="kgdbocArgs1">
207	230	<title>Using loadable module or built-in</title>
208	231	<para>
...	...	@@ -212,7 +235,7 @@
212	235	<listitem>
213	236	<para>As a kernel loadable module:</para>
214	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	239	string. The first is for an x86 target using the first serial port.
217	240	The second example is for the ARM Versatile AB using the second
218	241	serial port.
...	...	@@ -240,6 +263,9 @@
240	263	</sect3>
241	264	<sect3 id="kgdbocArgs3">
242	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	269	<para>You can configure kgdboc to use the keyboard, and or a serial device
244	270	depending on if you are using kdb and or kgdb, in one of the
245	271	following scenarios.
...	...	@@ -255,6 +281,12 @@
255	281	<listitem><para>kdb with a keyboard</para>
256	282	<para><constant>kgdboc=kbd</constant></para>
257	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	290	</orderedlist>
259	291	</para>
260	292	</sect3>
...	...	@@ -637,6 +669,8 @@
637	669	<listitem><para>The logic to perform safe memory reads and writes to memory while using the debugger</para></listitem>
638	670	<listitem><para>A full implementation for software breakpoints unless overridden by the arch</para></listitem>
639	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	674	</itemizedlist>
641	675	</para>
642	676	</listitem>
...	...	@@ -747,6 +781,8 @@
747	781	</sect1>
748	782	<sect1 id="kgdbocDesign">
749	783	<title>kgdboc internals</title>
	784	+ <sect2>
	785	+ <title>kgdboc and uarts</title>
750	786	<para>
751	787	The kgdboc driver is actually a very thin driver that relies on the
752	788	underlying low level to the hardware driver having "polling hooks"
...	...	@@ -754,11 +790,8 @@
754	790	implementation of kgdboc it the serial_core was changed to expose a
755	791	low level UART hook for doing polled mode reading and writing of a
756	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
758		- core which in turn uses the call back in the UART driver. It is
759		- certainly possible to extend kgdboc to work with non-UART based
760		- consoles in the future.
761		- </para>
	793	+ request to the debugger, kgdboc invokes a callback in the serial
	794	+ core which in turn uses the callback in the UART driver.</para>
762	795	<para>
763	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	797	#ifdef CONFIG_CONSOLE_POLL
765	798
...	...	@@ -772,9 +805,68 @@
772	805	that they can be called from an atomic context and have to restore
773	806	the state of the UART chip on return such that the system can return
774	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	809	going to mean pressing the reset button.
777	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	870	</sect1>
779	871	</chapter>
780	872	<chapter id="credits">
...	...	@@ -1143,9 +1143,12 @@
1143	1143	kgdboc= [KGDB,HW] kgdb over consoles.
1144	1144	Requires a tty driver that supports console polling,
1145	1145	or a supported polling keyboard driver (non-usb).
1146		- Serial only format: <serial_device>[,baud]
1147		- keyboard only format: kbd
1148		- keyboard and serial format: kbd,<serial_device>[,baud]
	1146	+ Serial only format: <serial_device>[,baud]
	1147	+ keyboard only format: kbd
	1148	+ keyboard and serial format: kbd,<serial_device>[,baud]
	1149	+ Optional Kernel mode setting:
	1150	+ kms, kbd format: kms,kbd
	1151	+ kms, kbd and serial format: kms,kbd,<ser_dev>[,baud]
1149	1152
1150	1153	kgdbwait [KGDB] Stop kernel execution and enter the
1151	1154	kernel debugger at the earliest opportunity.