Subversion Repositories test_project

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 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 ); 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