This file describes the configuration and behavior of KGDB for the SH kernel. Based on a description from Henry Bell , it has been modified to account for quirks in the current implementation. Version ======= This version of KGDB was written for 2.4.xx kernels for the SH architecture. Further documentation is available from the linux-sh project website. Debugging Setup: Host ====================== The two machines will be connected together via a serial line - this should be a null modem cable i.e. with a twist. On your DEVELOPMENT machine, go to your kernel source directory and build the kernel, enabling KGDB support in the "kernel hacking" section. This includes the KGDB code, and also makes the kernel be compiled with the "-g" option set -- necessary for debugging. To install this new kernel, use the following installation procedure. Decide on which tty port you want the machines to communicate, then cable them up back-to-back using the null modem. On the DEVELOPMENT machine, you may wish to create an initialization file called .gdbinit (in the kernel source directory or in your home directory) to execute commonly-used commands at startup. A minimal .gdbinit might look like this: file vmlinux set remotebaud 115200 target remote /dev/ttyS0 Change the "target" definition so that it specifies the tty port that you intend to use. Change the "remotebaud" definition to match the data rate that you are going to use for the com line (115200 is the default). Debugging Setup: Target ======================== By default, the KGDB stub will communicate with the host GDB using ttySC1 at 115200 baud, 8 databits, no parity; these defaults can be changed in the kernel configuration. As the kernel starts up, KGDB will initialize so that breakpoints, kernel segfaults, and so forth will generally enter the debugger. This behavior can be modified by including the "kgdb" option in the kernel command line; this option has the general form: kgdb=, The indicates the port to use, and can optionally specify baud, parity and databits -- e.g. "ttySC0,9600N8" or "ttySC1,19200". The can be "halt" or "disabled". The "halt" action enters the debugger via a breakpoint as soon as kgdb is initialized; the "disabled" action causes kgdb to ignore kernel segfaults and such until explicitly entered by a breakpoint in the code or by external action (sysrq or NMI). (Both and can appear alone, w/o the separating comma.) For example, if you wish to debug early in kernel startup code, you might specify the halt option: kgdb=halt Boot the TARGET machinem, which will appear to hang. On your DEVELOPMENT machine, cd to the source directory and run the gdb program. (This is likely to be a cross GDB which runs on your host but is built for an SH target.) If everything is working correctly you should see gdb print out a few lines indicating that a breakpoint has been taken. It will actually show a line of code in the target kernel inside the gdbstub activation code. NOTE: BE SURE TO TERMINATE OR SUSPEND any other host application which may be using the same serial port (for example, a terminal emulator you have been using to connect to the target boot code.) Otherwise, data from the target may not all get to GDB! You can now use whatever gdb commands you like to set breakpoints. Enter "continue" to start your target machine executing again. At this point the target system will run at full speed until it encounters your breakpoint or gets a segment violation in the kernel, or whatever. Serial Ports: KGDB, Console ============================ This version of KGDB may not gracefully handle conflict with other drivers in the kernel using the same port. If KGDB is configured on the same port (and with the same parameters) as the kernel console, or if CONFIG_SH_KGDB_CONSOLE is configured, things should be fine (though in some cases console messages may appear twice through GDB). But if the KGDB port is not the kernel console and used by another serial driver which assumes different serial parameters (e.g. baud rate) KGDB may not recover. Also, when KGDB is entered via sysrq-g (requires CONFIG_KGDB_SYSRQ) and the kgdb port uses the same port as the console, detaching GDB will not restore the console to working order without the port being re-opened. Another serious consequence of this is that GDB currently CANNOT break into KGDB externally (e.g. via ^C or ); unless a breakpoint or error is encountered, the only way to enter KGDB after the initial halt (see above) is via NMI (CONFIG_KGDB_NMI) or sysrq-g (CONFIG_KGDB_SYSRQ). Code is included for the basic Hitachi Solution Engine boards to allow the use of ttyS0 for KGDB if desired; this is less robust, but may be useful in some cases. (This cannot be selected using the config file, but only through the kernel command line, e.g. "kgdb=ttyS0", though the configured defaults for baud rate etc. still apply if not overridden.) If gdbstub Does Not Work ======================== If it doesn't work, you will have to troubleshoot it. Do the easy things first like double checking your cabling and data rates. You might try some non-kernel based programs to see if the back-to-back connection works properly. Just something simple like cat /etc/hosts /dev/ttyS0 on one machine and cat /dev/ttyS0 on the other will tell you if you can send data from one machine to the other. There is no point in tearing out your hair in the kernel if the line doesn't work. If you need to debug the GDB/KGDB communication itself, the gdb commands "set debug remote 1" and "set debug serial 1" may be useful, but be warned: they produce a lot of output. Threads ======= Each process in a target machine is seen as a gdb thread. gdb thread related commands (info threads, thread n) can be used. CONFIG_KGDB_THREAD must be defined for this to work. In this version, kgdb reports PID_MAX (32768) as the process ID for the idle process (pid 0), since GDB does not accept 0 as an ID. Detaching (exiting KGDB) ========================= There are two ways to resume full-speed target execution: "continue" and "detach". With "continue", GDB inserts any specified breakpoints in the target code and resumes execution; the target is still in "gdb mode". If a breakpoint or other debug event (e.g. NMI) happens, the target halts and communicates with GDB again, which is waiting for it. With "detach", GDB does *not* insert any breakpoints; target execution is resumed and GDB stops communicating (does not wait for the target). In this case, the target is no longer in "gdb mode" -- for example, console messages no longer get sent separately to the KGDB port, or encapsulated for GDB. If a debug event (e.g. NMI) occurs, the target will re-enter "gdb mode" and will display this fact on the console; you must give a new "target remote" command to gdb. NOTE: TO AVOID LOSSING CONSOLE MESSAGES IN CASE THE KERNEL CONSOLE AND KGDB USING THE SAME PORT, THE TARGET WAITS FOR ANY INPUT CHARACTER ON THE KGDB PORT AFTER A DETACH COMMAND. For example, after the detach you could start a terminal emulator on the same host port and enter a ; however, this program must then be terminated or suspended in order to use GBD again if KGDB is re-entered. Acknowledgements ================ This code was mostly generated by Henry Bell ; largely from KGDB by Amit S. Kale - extracts from code by Glenn Engel, Jim Kingdon, David Grothe , Tigran Aivazian , William Gatliff , Ben Lee, Steve Chamberlain and Benoit Miller are also included. Jeremy Siegel