Document all options and general usage.

Implement the -a option to bump the annotation_level.  This improves
the Emacs gud behaviour.  You can now supply the following function

(defun gud-gdb-massage-args (file args) (cons "-a" args))

(e.g. by evaluating it from the *scratch* buffer) and get the normal
jump to the source window when browsing the stack.

We should probably eventually supply our own kgdb submode to gud.el.

1 files changed, 67 insertions, 0 deletions

diff --git a/gnu/usr.bin/gdb/kgdb/kgdb.1 b/gnu/usr.bin/gdb/kgdb/kgdb.1
index 7b2b482..ff1a9c9 100644
--- a/gnu/usr.bin/gdb/kgdb/kgdb.1
+++ b/gnu/usr.bin/gdb/kgdb/kgdb.1
@@ -31,6 +31,7 @@
 .Nd The kernel debugger
 .Sh SYNOPSIS
 .Nm
+.Op Fl a
 .Op Fl v
 .Op Fl d Ar crashdir
 .Op Fl c Ar core | Fl n Ar dumpnr | Fl r Ar device
@@ -41,6 +42,72 @@ The
 utility is a debugger based on
 .Xr gdb 1
 that allows debugging of kernel core files.
+.Pp
+The options are as follows:
+.Bl -tag -width ".Fl d Ar crashdir"
+.It Fl a
+Increase the annotation level.
+An annotation level of 1 features the historical
+.Fl fullname
+option of
+.Xr gdb 1 .
+This is useful when running
+.Nm
+in Emacs.
+.Fl v
+Increase verbosity.
+.It Fl d Ar crashdir
+Use
+.Ar crashdir
+instead of the default,
+.Pa /var/crash
+to locate kernel core dump files in.
+The name
+.Pa vmcore.
+plus the dump number will be appended to determine
+the actual dump file name.
+.It Fl c Ar core
+Explicitly use
+.Ar core
+as the core dump file.
+.It Fl n Ar dumpnr
+Use the kernel core dump file numbered
+.Ar dumpnr
+for debugging.
+.It Fl r Ar device
+Use
+.Ar device
+to connect
+.Nm
+to for a remote debugging session.
+.El
+.Pp
+The
+.Fl c ,
+.Fl n ,
+and
+.Fl r
+options are mutually exclusive.
+.Pp
+Optionally, the name of the kernel symbol file and
+the name of the core dump file can be supplied on the
+command-line as positional arguments.
+If no kernel symbol file name has been given, the
+symbol file of the currently running kernel will be
+used.
+If no core dump file has been specified through either
+of the options or the last command-line argument,
+.Pa /dev/mem
+will be opened to allow debugging the currenlty running
+kernel.
+.Sh FILES
+.Bl -tag -width "Pa /var/crash"
+.It Pa /dev/mem
+Default memory image to open if no core dump file
+has been specified.
+.It Pa /var/crash
+Default directory to locate kernel core dump files.
+.El
 .Sh SEE ALSO
 .Xr gdb 1
 .Sh HISTORY