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

Authors
-------

Robert Walsh <rjwalsh@durables.org>  (2.6 port)
wangdi <wangdi@clusterfs.com>        (2.6 port)
Matt Mackall <mpm@selenic.com>       (netpoll api)
San Mehat                            (original 2.4 code)


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

KGDB supports debugging over ethernet (kgdboe) via polling of a given
network interface. Most cards should be supported automatically.
Debugging facilities are available as soon as the network driver and
kgdboe have initialized. Unfortunately, this is too late in the boot
process for debugging some issues, but works quite well for many
others. This should not interfere with normal network usage and
doesn't require a dedicated NIC.

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 option on the TARGET kernel:

  kgdboe=[tgt-port]@<tgt-ip>/[dev],[host-port]@<host-ip>/[host-macaddr]

    where
        tgt-port      source for UDP packets (defaults to 6443)
        tgt-ip        source IP to use (interface address)
        dev           network interface (eth0)
        host-port     HOST UDP port (6442) (not really used)
        host-ip       IP address for HOST machine
        host-macaddr  ethernet MAC address for HOST (ff:ff:ff:ff:ff:ff)

  examples:

    kgdboe=7000@192.168.0.1/eth1,7001@192.168.0.2/00:05:3C:04:47:5D
        this machine is 192.168.0.1 on eth1
        remote machine is 192.168.0.2 with MAC address 00:05:3C:04:47:5D
        listen for gdb packets on port 7000
        send unsolicited gdb packets to port 7001

    kgdboe=@192.168.0.1/,@192.168.0.2/
        this machine is 192.168.0.1 on default interface eth0
        remote machine is 192.168.0.2, use default broadcast MAC address
        listen for gdb packets on default port 6443
        send unsolicited gdb packets to port 6442

Only packets originating from the configured HOST IP address will be
accepted by the debugger.

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.

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

The current release of this code is exclusive of using kgdb on a
serial interface, so you must boot without the kgdboe option to use
serial debugging. Trying to debug the network driver while using it
will prove interesting.

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

Send bug reports to Robert Walsh <rjwalsh@durables.org> and Matt
Mackall <mpm@selenic.com>.
