May 23, 2002 IPKDB 9

### NAME

ipkdb - machine-dependent interface to ipkdb

### SYNOPSIS

```void` ipkdb_init(```void`)
```void` ipkdb_connect(```int when`)
```int` ipkdbcmds(```void`)
```void` ipkdbinit(```void`)
```void` ipkdb_trap(```void`)
```int` ipkdb_poll(```void`)
```int` ipkdbif_init(```struct ipkdb_if *kip`)
```int` ipkdbfbyte(```u_char *c`)
```int` ipkdbsbyte(```u_char *c``, int i`)

### DESCRIPTION

The machine-dependent code must support this interface for operation with ipkdb(4).

During system bootstrap, machine-dependent code must invoke ipkdb_init(``). If the kernel is booted with ```RB_KDB` set in boothowto, then ipkdb(4) is enabled by invoking ipkdb_connect(``), setting the ```when` argument to 0.

ipkdbcmds(``) is invoked by machine-dependent code 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(1). Valid return values are:

```IPKDB_CMD_RUN`
  user wants to continue
```IPKDB_CMD_STEP`
  user wants to do single stepping
```IPKDB_CMD_EXIT`
  user has detached from debugging

### FUNCTIONS

The machine-dependent code must provide the following functions for the machine-independent code.

ipkdbinit(````)
  This routine gets called when the debugger should be entered for the first time.
ipkdb_trap(````)
  This routine is part of the trap handler. Whenever a trap happens (e.g., when hitting a breakpoint during debugging), ipkdb_trap(``) decides if the Debugger needs to be called. If there are other ways to decide that, it's not necessary to provide an ipkdb_trap(``) implementation.
ipkdb_poll(````)
  This routine gets called after a panic to check for a key press 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.
ipkdbif_init(```kip`)
  In order to be able to find the debugging interface, the network driver must invoke ipkdbif_init(``) with ```kip` specifying a ```struct` `ipkdb_if` plus some additional parameters that allow it to access the devices registers, hopefully using bus_space(9) methods. In the ```ipkdb_if` structure, the attach routine must initialize the following fields:

  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
  start
    routine called every time ipkdb is entered
  leave
    routine called every time 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
  port
    may be used as a pointer to some device
ipkdbfbyte(```c`)
  This routine should fetch a byte from address ```c`. It must not enter any trap handling code, but instead return -1 on inability to access the data.
ipkdbsbyte(```c``, i`)
  This routine should set the byte pointed to by ```c` to the value given as ```i`. 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.

### SEE ALSO

ipkdb(4)