share/man/man7/kgdb.7

   1 .\"     $OpenBSD: kgdb.7,v 1.7 2007/05/31 19:19:58 jmc Exp $
   2 .\"
   3 .\" Copyright (c) 2001 Hugh Graham
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
  15 .\" WARRANTIES, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
  16 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  17 .\" IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  18 .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  19 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  20 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  22 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  23 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  24 .\" POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .Dd $Mdocdate: May 31 2007 $
  27 .Dt KGDB 7
  28 .Os
  29 .Sh NAME
  30 .Nm kgdb
  31 .Nd remote kernel debugging with gdb
  32 .Sh DESCRIPTION
  33 Should a programmer be dissatisfied with the
  34 .Ox
  35 kernel's internal debugger
  36 .Xr ddb 4 ,
  37 and have appropriate hardware available, a kernel with
  38 .Cm option KGDB
  39 may be built to effect remote debugging with
  40 .Xr gdb 1
  41 instead.
  42 .Pp
  43 To prepare for debugging over serial line one would:
  44 .Pp
  45 .Bl -bullet -offset 3n -compact
  46 .It
  47 Obtain a second system and a crossover serial cable.
  48 .It
  49 Connect the systems and test the cable.
  50 .It
  51 Build a kernel with
  52 .Cm option KGDB
  53 and
  54 .Cm makeoptions DEBUG="-g" .
  55 .It
  56 Copy the resultant
  57 .Pa bsd.gdb
  58 to the control system, and boot the corresponding
  59 .Pa bsd
  60 on the target system.
  61 .It
  62 On the control system, run gdb on the kernel just copied.
  63 .It
  64 Issue the command "target remote /dev/<serial port>" within gdb.
  65 The target system should enter
  66 .Nm
  67 at this point.
  68 .It
  69 Debug as normal and detach when done, the target should resume normal operation.
  70 .El
  71 .Sh SEE ALSO
  72 .Xr gdb 1 ,
  73 .Xr ddb 4 ,
  74 .Xr options 4
  75 .Pp
  76 gdb info documents and online documentation.
  77 .Sh CAVEATS
  78 The remote connection will introduce certain latencies a local debugger
  79 would not see.
  80 .Pp
  81 Not available on all architectures.