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>