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.
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.
14 ======================
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.
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.
24 To install this new kernel, use the following installation procedure.
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.
32 A minimal .gdbinit might look like this:
36 target remote /dev/ttyS0
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
43 Debugging Setup: Target
44 ========================
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.
52 This behavior can be modified by including the "kgdb" option in the
53 kernel command line; this option has the general form:
55 kgdb=<ttyspec>,<action>
57 The <ttyspec> indicates the port to use, and can optionally specify
58 baud, parity and databits -- e.g. "ttySC0,9600N8" or "ttySC1,19200".
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).
65 (Both <ttyspec> and <action> can appear alone, w/o the separating comma.)
67 For example, if you wish to debug early in kernel startup code, you
68 might specify the halt option:
72 Boot the TARGET machine, which will appear to hang.
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.
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!
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.
91 Serial Ports: KGDB, Console
92 ============================
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
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.
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).
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.)
118 If gdbstub Does Not Work
119 ========================
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.
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.
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.
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.
143 Detaching (exiting KGDB)
144 =========================
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.
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.
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.
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
projects / linux-2.6 / blob