Commit | Line | Data |
---|---|---|
1da177e4 LT |
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 machinem, 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> |