kgdbeth.txt

KGDB over ethernet
==================

Authors
-------

Robert Walsh <rjwalsh@durables.org>  (2.6 port)
wangdi <wangdi@clusterfs.com>        (2.6 port)
San Mehat                            (original 2.4 code)


Introduction
------------

KGDB supports debugging over ethernet.  Only a limited set of ethernet
devices are supported right now, but adding support for new devices
should not be too complicated.  See "New Devices" below for details.


Terminology
-----------

This document uses the following terms:

  TARGET: the machine being debugged.
  HOST:   the machine running gdb.


Usage
-----

You need to use the following command-line options on the TARGET kernel:

  gdbeth=DEVICENUM
  gdbeth_remoteip=HOSTIPADDR
  gdbeth_remotemac=REMOTEMAC
  gdbeth_localmac=LOCALMAC

kgdbeth=DEVICENUM sets the ethernet device number to listen on for
debugging packets.  e.g. kgdbeth=0 listens on eth0.

kgdbeth_remoteip=HOSTIPADDR sets the IP address of the HOST machine.
Only packets originating from this IP address will be accepted by the
debugger.  e.g. kgdbeth_remoteip=192.168.2.2

kgdbeth_remotemac=REMOTEMAC sets the ethernet address of the HOST machine.
e.g. kgdbeth_remotemac=00:07:70:12:4E:F5

kgdbeth_localmac=LOCALMAC sets the ethernet address of the TARGET machine.
e.g. kgdbeth_localmac=00:10:9F:18:21:3C

You can also set the following command-line option on the TARGET kernel:

  kgdbeth_listenport=PORT

kgdbeth_listenport sets the UDP port to listen on for gdb debugging
packets.  The default value is "6443".  e.g. kgdbeth_listenport=7654
causes the kernel to listen on UDP port 7654 for debugging packets.

On the HOST side, run gdb as normal and use a remote UDP host as the
target:

   % gdb ./vmlinux
   GNU gdb Red Hat Linux (5.3post-0.20021129.18rh)
   Copyright 2003 Free Software Foundation, Inc.
   GDB is free software, covered by the GNU General Public License, and you are
   welcome to change it and/or distribute copies of it under certain conditions.
   Type "show copying" to see the conditions.
   There is absolutely no warranty for GDB.  Type "show warranty" for details.
   This GDB was configured as "i386-redhat-linux-gnu"...
   (gdb) target remote udp:HOSTNAME:6443

You can now continue as if you were debugging over a serial line.

Observations
------------

I've used this with NFS and various other network applications (ssh,
etc.) and it's doesn't appear to interfere with their operation in
any way.  It doesn't seem to effect the NIC it uses - i.e. you don't
need a dedicated NIC for this.

Limitations
-----------

In the inital release of this code you _must_ break into the system with the
debugger by hand, early after boot, as described above.

Otherwise, the first time the kernel tries to enter the debugger (say, via an
oops or a BUG), the kgdb stub will doublefault and die because things aren't
fully set up yet.

Supported devices
-----------------

Right now, the following drivers are supported:

  e100 driver (drivers/net/e100/*)
  3c59x driver (drivers/net/3c59x.c)


New devices
-----------

Supporting a new device is straightforward.  Just add a "poll" routine to
the driver and hook it into the poll_controller field in the netdevice
structure.  For an example, look in drivers/net/3c59x.c and search
for CONFIG_KGDB (two places.)

The poll routine is usually quite simple - it's usually enough to just
disable interrupts, call the device's interrupt routine and re-enable
interrupts again.


Bug reports
-----------

Send bug reports to Robert Walsh <rjwalsh@durables.org>.