MFp4: Bring the kernel debugging section up to reality.

Requested by:	rwatson

en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.sgml

@@ -483,7 +483,7 @@
   <sect1 id="kerneldebug-online-ddb">
     <title>On-Line Kernel Debugging Using DDB</title>
 
-    <para>While <command>gdb <option>-k</option></command> as an off-line debugger provides a very
+    <para>While <command>kgdb</command> as an off-line debugger provides a very
       high level of user interface, there are some things it cannot do.  The
       most important ones being breakpointing and single-stepping kernel
       code.</para>
@@ -498,6 +498,7 @@
     <para>To configure your kernel to include DDB, add the option line
 
       <programlisting>options DDB</programlisting>
+      <programlisting>options KDB</programlisting>
 
       to your config file, and rebuild.  (See <ulink
 	url="&url.books.handbook;/index.html">The FreeBSD Handbook</ulink> for details on
@@ -513,14 +514,16 @@
       DDB.  The first, and earliest way is to type the boot flag
       <option>-d</option> right at the boot prompt.  The kernel will start up
       in debug mode and enter DDB prior to any device probing.  Hence you can
-      even debug the device probe/attach functions.</para>
+      even debug the device probe/attach functions.  Users of &os.current;
+      will need to use the boot menu option, six, to escape to a command
+      prompt.</para>
 
     <para>The second scenario is to drop to the debugger once the
       system has booted.  There are two simple ways to accomplish
       this.  If you would like to break to the debugger from the
       command prompt, simply type the command:</para>
 
-    <screen>&prompt.root; <userinput>sysctl debug.enter_debugger=ddb</userinput></screen>
+    <screen>&prompt.root; <userinput>sysctl debug.debugger_on_panic=1</userinput></screen>
 
     <para>Alternatively, if you are at the system console, you may use
       a hot-key on the keyboard.  The default break-to-debugger
@@ -539,12 +542,17 @@
       kernel is configured to use it.  For this reason, it is not wise to
       configure a kernel with DDB for a machine running unattended.</para>
 
+    <para>To obtain the unattended funcationality, add:</para>
+
+    <programlisting>options	KDB_UNATTENDED</programlisting>
+
+    <para>to the kernel configuration file and rebuild/reinstall.</para>
+
     <para>The DDB commands roughly resemble some <command>gdb</command>
       commands.  The first thing you probably need to do is to set a
       breakpoint:</para>
 
-    <screen><userinput>b function-name</userinput>
-<userinput>b address</userinput></screen>
+    <screen><userinput>break function-name address</userinput></screen>
 
     <para>Numbers are taken hexadecimal by default, but to make them distinct
       from symbol names; hexadecimal numbers starting with the letters
@@ -552,10 +560,16 @@
       (this is optional for other numbers).  Simple expressions are allowed,
       for example: <literal>function-name + 0x103</literal>.</para>
 
-    <para>To continue the operation of an interrupted kernel, simply
+    <para>To continue the dump of an interrupted kernel into memory,
       type:</para>
 
-    <screen><userinput>c</userinput></screen>
+    <screen><userinput>continue</userinput></screen>
+
+    <warning>
+      <para>This will cause the machine to dump core and reboot without
+	syncing data to the disk.  Upon re-initialization of the system,
+	a &man.fsck.8; will be required.</para>
+    </warning>
 
     <para>To get a stack trace, use:</para>
 
@@ -569,7 +583,6 @@
 
     <para>If you want to remove a breakpoint, use</para>
 
-
     <screen><userinput>del</userinput>
 <userinput>del address-expression</userinput></screen>
 
@@ -580,6 +593,10 @@
 
     <screen><userinput>show b</userinput></screen>
 
+    <para>or:</para>
+
+    <screen><userinput>show break</userinput></screen>
+
     <para>To single-step the kernel, try:</para>
 
     <screen><userinput>s</userinput></screen>
@@ -592,7 +609,8 @@
     <note>
       <para>This is different from <command>gdb</command>'s
 	<command>next</command> statement; it is like <command>gdb</command>'s
-	<command>finish</command>.</para>
+	<command>finish</command>.  Pressing <keycap>n</keycap> more than once
+        will cause a continue.</para>
     </note>
 
     <para>To examine data from memory, use (for example):
@@ -659,16 +677,18 @@
     <screen><userinput>panic</userinput></screen>
 
     <para>This will cause your kernel to dump core and reboot, so you can
-      later analyze the core on a higher level with <command>gdb</command>.  This command
+      later analyze the core on a higher level with <command>gdb</command>.
+      This command
       usually must be followed by another <command>continue</command>
       statement.</para>
 
     <screen><userinput>call boot(0)</userinput></screen>
 
-    <para>Which might be a good way to cleanly shut down the running system,
-      <function>sync()</function> all disks, and finally reboot.  As long as
+    <para>Might be a good way to cleanly shut down the running system,
+      <function>sync()</function> all disks, and finally, in some cases,
+      reboot.  As long as
       the disk and filesystem interfaces of the kernel are not damaged, this
-      might be a good way for an almost clean shutdown.</para>
+      could be a good way for an almost clean shutdown.</para>
 
     <screen><userinput>call cpu_reset()</userinput></screen>
 
@@ -679,7 +699,7 @@
 
     <screen><userinput>help</userinput></screen>
 
-    <para>However, it is highly recommended to have a printed copy of the
+    <para>It is highly recommended to have a printed copy of the
 	&man.ddb.4; manual page ready for a debugging
       session.  Remember that it is hard to read the on-line manual while
       single-stepping the kernel.</para>
@@ -711,7 +731,7 @@
       Now, on the debugging machine, go to the compile directory of the target
       kernel, and start <command>gdb</command>:</para>
 
-    <screen>&prompt.user; <userinput>gdb -k kernel</userinput>
+    <screen>&prompt.user; <userinput>kgdb kernel</userinput>
 GDB is free software and you are welcome to distribute copies of it
  under certain conditions; type "show copying" to see the conditions.
 There is absolutely no warranty for GDB; type "show warranty" for details.
@@ -865,4 +885,3 @@ Reading symbols from /sys/modules/linux/linux.ko...done.
      sgml-parent-document: ("../book.sgml" "part" "chapter")
      End:
 -->
-