From 1da177e4c3f41524e886b7f1b8a0c1fc7321cac2 Mon Sep 17 00:00:00 2001 From: Linus Torvalds Date: Sat, 16 Apr 2005 15:20:36 -0700 Subject: Linux-2.6.12-rc2 Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip! --- Documentation/sh/kgdb.txt | 179 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 Documentation/sh/kgdb.txt (limited to 'Documentation/sh/kgdb.txt') diff --git a/Documentation/sh/kgdb.txt b/Documentation/sh/kgdb.txt new file mode 100644 index 000000000000..5b04f7f306fc --- /dev/null +++ b/Documentation/sh/kgdb.txt @@ -0,0 +1,179 @@ + +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 + -- cgit v1.2.3