Based on kernel version 2.6.27. Page generated on 2008-10-13 09:54 EST.
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[AT]st[DOT]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[AT]st[DOT]com>; 172 largely from KGDB by Amit S. Kale <akale[AT]veritas[DOT]com> - extracts from 173 code by Glenn Engel, Jim Kingdon, David Grothe <dave[AT]gcom[DOT]com>, Tigran 174 Aivazian <tigran[AT]sco.com>, William Gatliff <bgat@open-widgets[DOT]com>, Ben 175 Lee, Steve Chamberlain and Benoit Miller <fulg[AT]iname[DOT]com> are also 176 included. 177 178 Jeremy Siegel 179 <jsiegel[AT]mvista[DOT]com>