Documentation/sh/kgdb.txt

   1
   2 This file describes the configuration and behavior of KGDB for the SH
   3 kernel. Based on a description from Henry Bell <henry.bell@st.com>, it
   4 has been modified to account for quirks in the current implementation.
   5
   6 Version
   7 =======
   8
   9 This version of KGDB was written for 2.4.xx kernels for the SH architecture.
  10 Further documentation is available from the linux-sh project website.
  11
  12
  13 Debugging Setup: Host
  14 ======================
  15
  16 The two machines will be connected together via a serial line - this
  17 should be a null modem cable i.e. with a twist.
  18
  19 On your DEVELOPMENT machine, go to your kernel source directory and
  20 build the kernel, enabling KGDB support in the "kernel hacking" section.
  21 This includes the KGDB code, and also makes the kernel be compiled with
  22 the "-g" option set -- necessary for debugging.
  23
  24 To install this new kernel, use the following installation procedure.
  25
  26 Decide on which tty port you want the machines to communicate, then
  27 cable them up back-to-back using the null modem.  On the DEVELOPMENT
  28 machine, you may wish to create an initialization file called .gdbinit
  29 (in the kernel source directory or in your home directory) to execute
  30 commonly-used commands at startup.
  31
  32 A minimal .gdbinit might look like this:
  33
  34   file vmlinux
  35   set remotebaud 115200
  36   target remote /dev/ttyS0
  37
  38 Change the "target" definition so that it specifies the tty port that
  39 you intend to use.  Change the "remotebaud" definition to match the
  40 data rate that you are going to use for the com line (115200 is the
  41 default).
  42
  43 Debugging Setup: Target
  44 ========================
  45
  46 By default, the KGDB stub will communicate with the host GDB using
  47 ttySC1 at 115200 baud, 8 databits, no parity; these defaults can be
  48 changed in the kernel configuration. As the kernel starts up, KGDB will
  49 initialize so that breakpoints, kernel segfaults, and so forth will
  50 generally enter the debugger.
  51
  52 This behavior can be modified by including the "kgdb" option in the
  53 kernel command line; this option has the general form:
  54
  55   kgdb=<ttyspec>,<action>
  56
  57 The <ttyspec> indicates the port to use, and can optionally specify
  58 baud, parity and databits -- e.g. "ttySC0,9600N8" or "ttySC1,19200".
  59
  60 The <action> can be "halt" or "disabled".  The "halt" action enters the
  61 debugger via a breakpoint as soon as kgdb is initialized; the "disabled"
  62 action causes kgdb to ignore kernel segfaults and such until explicitly
  63 entered by a breakpoint in the code or by external action (sysrq or NMI).
  64
  65 (Both <ttyspec> and <action> can appear alone, w/o the separating comma.)
  66
  67 For example, if you wish to debug early in kernel startup code, you
  68 might specify the halt option:
  69
  70   kgdb=halt
  71
  72 Boot the TARGET machine, which will appear to hang.
  73
  74 On your DEVELOPMENT machine, cd to the source directory and run the gdb
  75 program.  (This is likely to be a cross GDB which runs on your host but
  76 is built for an SH target.) If everything is working correctly you
  77 should see gdb print out a few lines indicating that a breakpoint has
  78 been taken.  It will actually show a line of code in the target kernel
  79 inside the gdbstub activation code.
  80
  81 NOTE: BE SURE TO TERMINATE OR SUSPEND any other host application which
  82 may be using the same serial port (for example, a terminal emulator you
  83 have been using to connect to the target boot code.)  Otherwise, data
  84 from the target may not all get to GDB!
  85
  86 You can now use whatever gdb commands you like to set breakpoints.
  87 Enter "continue" to start your target machine executing again.  At this
  88 point the target system will run at full speed until it encounters
  89 your breakpoint or gets a segment violation in the kernel, or whatever.
  90
  91 Serial Ports: KGDB, Console
  92 ============================
  93
  94 This version of KGDB may not gracefully handle conflict with other
  95 drivers in the kernel using the same port. If KGDB is configured on the
  96 same port (and with the same parameters) as the kernel console, or if
  97 CONFIG_SH_KGDB_CONSOLE is configured, things should be fine (though in
  98 some cases console messages may appear twice through GDB).  But if the
  99 KGDB port is not the kernel console and used by another serial driver
 100 which assumes different serial parameters (e.g. baud rate) KGDB may not
 101 recover.
 102
 103 Also, when KGDB is entered via sysrq-g (requires CONFIG_KGDB_SYSRQ) and
 104 the kgdb port uses the same port as the console, detaching GDB will not
 105 restore the console to working order without the port being re-opened.
 106
 107 Another serious consequence of this is that GDB currently CANNOT break
 108 into KGDB externally (e.g. via ^C or <BREAK>); unless a breakpoint or
 109 error is encountered, the only way to enter KGDB after the initial halt
 110 (see above) is via NMI (CONFIG_KGDB_NMI) or sysrq-g (CONFIG_KGDB_SYSRQ).
 111
 112 Code is included for the basic Hitachi Solution Engine boards to allow
 113 the use of ttyS0 for KGDB if desired; this is less robust, but may be
 114 useful in some cases.  (This cannot be selected using the config file,
 115 but only through the kernel command line, e.g. "kgdb=ttyS0", though the
 116 configured defaults for baud rate etc. still apply if not overridden.)
 117
 118 If gdbstub Does Not Work
 119 ========================
 120
 121 If it doesn't work, you will have to troubleshoot it.  Do the easy
 122 things first like double checking your cabling and data rates.  You
 123 might try some non-kernel based programs to see if the back-to-back
 124 connection works properly.  Just something simple like cat /etc/hosts
 125 /dev/ttyS0 on one machine and cat /dev/ttyS0 on the other will tell you
 126 if you can send data from one machine to the other.  There is no point
 127 in tearing out your hair in the kernel if the line doesn't work.
 128
 129 If you need to debug the GDB/KGDB communication itself, the gdb commands
 130 "set debug remote 1" and "set debug serial 1" may be useful, but be
 131 warned: they produce a lot of output.
 132
 133 Threads
 134 =======
 135
 136 Each process in a target machine is seen as a gdb thread. gdb thread related
 137 commands (info threads, thread n) can be used. CONFIG_KGDB_THREAD must
 138 be defined for this to work.
 139
 140 In this version, kgdb reports PID_MAX (32768) as the process ID for the
 141 idle process (pid 0), since GDB does not accept 0 as an ID.
 142
 143 Detaching (exiting KGDB)
 144 =========================
 145
 146 There are two ways to resume full-speed target execution: "continue" and
 147 "detach". With "continue", GDB inserts any specified breakpoints in the
 148 target code and resumes execution; the target is still in "gdb mode".
 149 If a breakpoint or other debug event (e.g. NMI) happens, the target
 150 halts and communicates with GDB again, which is waiting for it.
 151
 152 With "detach", GDB does *not* insert any breakpoints; target execution
 153 is resumed and GDB stops communicating (does not wait for the target).
 154 In this case, the target is no longer in "gdb mode" -- for example,
 155 console messages no longer get sent separately to the KGDB port, or
 156 encapsulated for GDB.  If a debug event (e.g. NMI) occurs, the target
 157 will re-enter "gdb mode" and will display this fact on the console; you
 158 must give a new "target remote" command to gdb.
 159
 160 NOTE: TO AVOID LOSSING CONSOLE MESSAGES IN CASE THE KERNEL CONSOLE AND
 161 KGDB USING THE SAME PORT, THE TARGET WAITS FOR ANY INPUT CHARACTER ON
 162 THE KGDB PORT AFTER A DETACH COMMAND.  For example, after the detach you
 163 could start a terminal emulator on the same host port and enter a <cr>;
 164 however, this program must then be terminated or suspended in order to
 165 use GBD again if KGDB is re-entered.
 166
 167
 168 Acknowledgements
 169 ================
 170
 171 This code was mostly generated by Henry Bell <henry.bell@st.com>;
 172 largely from KGDB by Amit S. Kale <akale@veritas.com> - extracts from
 173 code by Glenn Engel, Jim Kingdon, David Grothe <dave@gcom.com>, Tigran
 174 Aivazian <tigran@sco.com>, William Gatliff <bgat@open-widgets.com>, Ben
 175 Lee, Steve Chamberlain and Benoit Miller <fulg@iname.com> are also
 176 included.
 177
 178 Jeremy Siegel
 179 <jsiegel@mvista.com>