A surprising number of people have complained about the absence

of a kgdb manpage, so add one.

1 files changed, 78 insertions, 0 deletions

diff --git a/share/man/man7/kgdb.7 b/share/man/man7/kgdb.7
new file mode 100644
index 00000000000..1e221d263cc
--- /dev/null
+++ b/share/man/man7/kgdb.7
@@ -0,0 +1,78 @@
+.\"     $OpenBSD: kgdb.7,v 1.1 2001/08/24 11:09:47 hugh Exp $
+.\"
+.\" Copyright (c) 2001 Hugh Graham
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
+.\" WARRANTIES, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd August 23, 2001
+.Dt KGDB 7
+.Os
+.Sh NAME
+.Nm kgdb
+.Nd remote kernel debugging with gdb
+.Sh DESCRIPTION
+Should a programmer be dissatisfied with the
+.Ox
+kernel's internal debugger
+.Xr ddb 4 ,
+and have appropriate hardware available, he may instead build a kernel with
+.Cm option KGDB
+to effect remote debugging with gdb.
+.Sh EXAMPLE
+To prepare for debugging over serial line one would:
+.Bl -bullet -offset 3n -compact
+.It
+Obtain a second system and a crossover serial cable.
+.It
+Connect the systems and test the cable.
+.It
+Build a kernel with
+.Cm option KGDB
+and
+.Cm makeoptions DEBUG="-g" .
+.It
+Copy the resultant
+.Sq bsd.gdb
+to the control system, and boot the corresponding
+.Sq bsd
+on the target system.
+.It
+On the control system, run gdb on the kernel just copied.
+.It
+Issue the command "target remote /dev/<serial port>" within gdb.
+The target system should enter kgdb at this point.
+.It
+Debug as normal, with the understanding that the remote connection
+will introduce certain latencies a local debugger would not see.
+.El
+.Sh SEE ALSO
+.Xr gdb 1 ,
+.Xr ddb 4 ,
+.Xr options 4
+.Pp
+gdb info documents and online documentation.
+.Sh HISTORY
+The
+.Nm
+manual page was begrudgingly written by Hugh Graham.
+.Sh CAVEAT
+Not available on all architectures.