NetBSD/sys/ipkdb

$NetBSD: README.port,v 1.2 1997/06/26 07:21:44 thorpej Exp $

What to Look for when Porting the IPKDB Interface
===============================================

Try to avoid calling any routine from the rest of the kernel.
(It's OK to call these routines during initialization).
You wouldn't be able to set breakpoints within these routines
during debugging, since this would hang the debugging interface.


Interface between IPKDB and Ethernet Board (sys/dev/yy/if_xx.c)
--------------------------------------------------------------

General Considerations


There is a problem when the debugger uses the same ethernet board as
does the rest of the kernel.  For one thing there might arrive packets
destined for the kernel during debugging sessions.  Since the debugger
receives all available packets for the time being it has to deliver
back to the driver those packets it has no use for.  This implies that
the debugging driver must leave the interrupt pending conditions alone
so that the kernel driver gets the interrupt at the next time its
interrupt is enabled (whether this is when the debugger is left or
later with an spl*()).  The same holds for the transmit interrupt
pending, at least when ipkdbinit determines that there is some packet
on its way out.


Configuration Files


The interface that is used for debugging has to have a unique
attribute with the option "disable", and must allow the attachment
of a ipkdbif.  The relevant part of the "files" file for interface
"xx" would look like this:

	define	ipkdbxx { [ disable = 0 ] }
	device	xx: ether, ifnet, ipkdbxx
	attach	xx at yy
	file	dev/zz/if_xx.c		xx | ipkdb_xx needs-flag
	attach	ipkdbif at ipkdbxx with ipkdb_xx

with proper values for yy and zz.  The file dev/zz/if_xx.c contains
both the code of the kernel driver and the IPKDB driver for this
interface.  You might want to #include "xx.h" in there and
conditionalize the compilation of the IPKDB driver with
#if NIPKDB_XX > 0.

The appropriate part of the machine configuration would read like
this:

	xx*		at yy
	ipkdbif0	at xx?

Note that the unit for ipkdbif in the configuration file must be
given explicitly!  It's used to distinguish the interface used
for debugging from the one you want to debug a new interface
driver for (see below).

Driver Code


The interface is "probed" by calling the parent probe routine with
a first argument of NULL.  The last argument to the probe routine
is a struct ipkdb_if pointer that needs to be (partly) initialized by
the probe code.  Fields to be set by the probe routine are:

	myenetaddr	fill this with the own ethernet address of
			the device/machine.
	flags		mark at least IPKDB_MYHW here.
	name		Name of the device, only used for a message.
	port		Port number, only used for a message by
			machine/device independent code.
	start		routine called everytime IPKDB is entered.
	leave		routine called everytime IPKDB is left.
	receive		routine called to receive a packet.
	send		routine called to send a packet.

Additional fields that may be set are:

	myinetaddr	fill this with the own internet address,
			and mark IPKDB_MYIP in flags.
	unit		These remaining fields are solely for
	speed		use by the driver.
	fill
	drvflags

The routine should check for existance of the ethernet board.
This routine should also try to find the system driver for the
same board and note its unit and device structure for later use.

The routine should return 0 on success and -1 on failure.

The remainder of the routines are called via function pointers
in the ipkdb_if structure.  The probe routine needs to fill in
these function pointers with proper values.

void start(struct ipkdb_if *kip)

This routine gets called every time the debugger is entered.
kip is a pointer to the ipkdb_if structure used for debugging.

It should initialize the hardware and software interface.

This routine should also note the current state of the ethernet board
(as far as it can) so a later call to leave can reinstantiate this
state.

void leave(struct ipkdb_if *kip)

This routine is called whenever the debugger is left.  It should
restore the ethernet hardware to the state prior to the last call to
start.

int receive(struct ipkdb_if *kip, u_char *buf, int poll)

This routine should return an ethernet packet to the buffer pointed to
by buf and return its length.  The packet should be complete with the
ethernet header, i.e. it starts with the recipient address, but does not
contain the ethernet checksum.

If poll is set, it should return immediately, if no packet is available.
Otherwise it should wait for the next packet.

This routine should return the number of bytes transferred to buf.

void send(struct ipkdb_if *kip, u_char *buf, int l)

This routine should send an ethernet packet out of the debugging
interface.  The packet is already complete with the ethernet header,
but does not contain the ethernet checksum.


Debugging


If you have a working IPKDB, you can test new interface code for a
different interface by supplying "option IPKDBTEST" and attaching
a ipkdbif1 to the new interface in your configuration file.  When
you boot the resulting kernel with the "-d" option, this will
initialize the new interface right after starting IPKDB on the
working one.  Thereafter, the code will continue to send and
receive packets on the new interface until you set the variable
"ipkdb_test" to 0.

Note that during debugging interface code this way you are using
most of the code that comprises the debugger code itself.  So you
have to be extremely careful with setting breakpoints and the like.


Interface between IPKDB and Machine (sys/arch/xxx/xxx/ipkdb_glue.c)
-----------------------------------------------------------------


void ipkdbcopy(s,d,n) void *s, *d; int n;
void ipkdbzero(d,n) void *d; int n;
void ipkdbcmp(s,d,n) char *s, *d; int n;

These routines are the same as bcopy, bzero and bcmp resp.  They are
here with other names to allow setting breakpoints into the normal
routines during debugging.  This implies that you shouldn't use
things like structure assignement in the code that gets used by
the debugger.

void ipkdbinit(void)

This routine gets called when the debugger should be entered for the
first time.

int ipkdb_poll(void)

This routine gets called after a panic to check for a keypress by the user.
If implemented it allows the user to press any key on the console to do
the automatic reboot after a panic.  Otherwise the debugging interface
will wait forever for some remote debugger to attach in case of a panic.

int ipkdbcmds(void)

There should be call to this routine from somewhere in locore when the
trap mechanism determines that the debugger should be entered, i.e. on
a single step or breakpoint interrupt from kernel code.  The trapping
mechanism should already have stored the registers into the global area
ipkdbregs.  The layout of this area must be the same as that expected
by GDB.  The return value of this routine is 0, if the user wants to
continue, 1 if the user wants to do single stepping, and 2 if the user
has detached from debugging.

int ipkdbfbyte(u_char *p)

This routine should fetch a byte from address p. It must not enter any
trap handling code, but instead return -1 on inability to access the data.

void ipkdbsbyte(u_char *p,u_char c)

This routine should set the byte pointed to by p to the value given as c.
The routine must not enter any trap handling code.  Furthermore it should
reset the modification bit in the relevant page table entry to the value
before the store.


sys/arch/xxx/include/ipkdb.h


Machine dependent definitions and protoypes should be in
sys/arch/xxx/include/ipkdb.h, i.e. in <machine/ipkdb.h>.  This includes
the size of the array ipkdbregs, that holds the contents of the registers
of the debuggee at the time IPKDB is entered.