+++ /dev/null
-
-This file describes the configuration and behavior of KGDB for the SH
-kernel. Based on a description from Henry Bell <henry.bell@st.com>, 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=<ttyspec>,<action>
-
-The <ttyspec> indicates the port to use, and can optionally specify
-baud, parity and databits -- e.g. "ttySC0,9600N8" or "ttySC1,19200".
-
-The <action> 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 <ttyspec> and <action> 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 machine, 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 <BREAK>); 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 <cr>;
-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 <henry.bell@st.com>;
-largely from KGDB by Amit S. Kale <akale@veritas.com> - extracts from
-code by Glenn Engel, Jim Kingdon, David Grothe <dave@gcom.com>, Tigran
-Aivazian <tigran@sco.com>, William Gatliff <bgat@open-widgets.com>, Ben
-Lee, Steve Chamberlain and Benoit Miller <fulg@iname.com> are also
-included.
-
-Jeremy Siegel
-<jsiegel@mvista.com>
git://ftp.safe.ca / safe / jmp / linux-2.6 / commitdiff