diff options
author | Paul Mundt <lethal@linux-sh.org> | 2008-12-11 05:15:14 -0500 |
---|---|---|
committer | Paul Mundt <lethal@linux-sh.org> | 2008-12-22 04:44:05 -0500 |
commit | 776d6c298aad42c2b8f191fa9ad826075e4d588c (patch) | |
tree | 058b8590d98312ebe65bcd7b51765f5c83cc62dc /Documentation | |
parent | 07d2a1a1cd8d609a4bc320a492670de57ec6bde1 (diff) |
sh: Kill off remaining CONFIG_SH_KGDB bits.
Now that we use the generic stub, kill off all of the left over
references.
Signed-off-by: Paul Mundt <lethal@linux-sh.org>
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/sh/kgdb.txt | 179 |
1 files changed, 0 insertions, 179 deletions
diff --git a/Documentation/sh/kgdb.txt b/Documentation/sh/kgdb.txt deleted file mode 100644 index 05b4ba89d28c..000000000000 --- a/Documentation/sh/kgdb.txt +++ /dev/null | |||
@@ -1,179 +0,0 @@ | |||
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> | ||