Re: [PATCH] BSD libkvm documentation

[Mark Kettenis <kettenis@chello.nl>]

   Date: Sun, 04 Jul 2004 22:14:24 +0200
   From: "Eli Zaretskii" <eliz@gnu.org>

   > Date: Sun, 4 Jul 2004 09:03:04 +0200 (CEST)
   > From: Mark Kettenis <kettenis@chello.nl>
   > 
   >    There's no reason to have 2 index entries both starting with "kvm"
   >    and both pointing to the same page; it just bloats the index.  Please
   >    leave only the first @kindex entry and make it say just "@kindex kvm".
   > 
   > There may be more "kvm" commands in the future, such that the section
   > doesn't fit on a single page anymore.

   That doesn't really matter, since they all are described one after
   the other.

   > Also it seems that current practice is to give every command a
   > @kindex entry.

   We should fix all such entries.

Fair enough.  Thanks for the explanation.  I committed the attached.

Mark


Index: doc/ChangeLog
from  Mark Kettenis  <kettenis@gnu.org>

	* gdb.texinfo (BSD libkvm Interface): New node (section)
	(Native): Add it to the menu.

Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.207
diff -u -p -r1.207 gdb.texinfo
--- doc/gdb.texinfo 19 Jun 2004 17:33:44 -0000 1.207
+++ doc/gdb.texinfo 5 Jul 2004 15:27:48 -0000
@@ -11412,6 +11412,7 @@ configurations.
 
 @menu
 * HP-UX::                       HP-UX
+* BSD libkvm Interface::	Debugging BSD kernel memory images
 * SVR4 Process Information::    SVR4 process information
 * DJGPP Native::                Features specific to the DJGPP port
 * Cygwin Native::		Features specific to the Cygwin port
@@ -11424,6 +11425,46 @@ On HP-UX systems, if you refer to a func
 begins with a dollar sign, @value{GDBN} searches for a user or system
 name first, before it searches for a convenience variable.
 
+@node BSD libkvm Interface
+@subsection BSD libkvm Interface
+
+@cindex libkvm
+@cindex kernel memory image
+@cindex kernel crash dump
+
+BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory
+interface that provides a uniform interface for accessing kernel virtual
+memory images, including live systems and crash dumps.  @value{GDBN}
+uses this interface to allow you to debug live kernels and kernel crash
+dumps on many native BSD configurations.  This is implemented as a
+special @code{kvm} debugging target.  For debugging a live system, load
+the currently running kernel into @value{GDBN} and connect to the
+@code{kvm} target:
+
+@smallexample
+(@value{GDBP}) @b{target kvm}
+@end smallexample
+
+For debugging crash dumps, provide the file name of the crash dump as an
+argument:
+
+@smallexample
+(@value{GDBP}) @b{target kvm /var/crash/bsd.0}
+@end smallexample
+
+Once connected to the @code{kvm} target, the following commands are
+available:
+
+@table @code
+@kindex kvm
+@item kvm pcb
+Set current context from pcb address.
+
+@item kvm proc
+Set current context from proc address.  This command isn't available on
+modern FreeBSD systems.
+@end table
+
 @node SVR4 Process Information
 @subsection SVR4 process information