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