.\"     $NetBSD: ipkdb.9,v 1.9 2009/09/04 23:29:03 apb Exp $
.\"
.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Gregory McGarry.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd September 4, 2009
.Dt IPKDB 9
.Os
.Sh NAME
.Nm ipkdb
.Nd machine-dependent interface to ipkdb
.Sh SYNOPSIS
.In ipkdb/ipkdb.h
.Ft void
.Fn ipkdb_init "void"
.Ft void
.Fn ipkdb_connect "int when"
.Ft int
.Fn ipkdbcmds "void"
.Ft void
.Fn ipkdbinit "void"
.Ft void
.Fn ipkdb_trap "void"
.Ft int
.Fn ipkdb_poll "void"
.Ft int
.Fn ipkdbif_init "struct ipkdb_if *kip"
.Ft int
.Fn ipkdbfbyte "u_char *c"
.Ft int
.Fn ipkdbsbyte "u_char *c" "int i"
.Sh DESCRIPTION
The machine-dependent code must support this interface for operation with
.Xr ipkdb 4 .
.Pp
During system bootstrap, machine-dependent code must invoke
.Fn ipkdb_init .
If the kernel is booted with
.Dv RB_KDB
set in
.Va boothowto
(see
.Xr boothowto 9 ) ,
.Xr ipkdb 4
is enabled by invoking
.Fn ipkdb_connect ,
setting the
.Fa when
argument to 0.
.Pp
.Fn 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
.Xr gdb 1 .
Valid return values are:
.Pp
.Bl -tag -offset indent -width IPKDB_CMD_EXITXX -compact
.It Dv IPKDB_CMD_RUN
user wants to continue
.It Dv IPKDB_CMD_STEP
user wants to do single stepping
.It Dv IPKDB_CMD_EXIT
user has detached from debugging
.El
.Sh FUNCTIONS
The machine-dependent code must provide the following functions for
the machine-independent code.
.Bl -tag -width ipkdbif_initXXXXXXX -compact
.It Fn ipkdbinit ""
This routine gets called when the debugger should be entered for the
first time.
.It Fn ipkdb_trap ""
This routine is part of the trap handler.
Whenever a trap happens (e.g., when hitting a breakpoint during debugging),
.Fn 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
.Fn ipkdb_trap
implementation.
.It Fn 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.
.It Fn ipkdbif_init "kip"
In order to be able to find the debugging interface, the network
driver must invoke
.Fn ipkdbif_init
with
.Fa kip
specifying a
.Fa struct ipkdb_if
plus some additional parameters that allow it to access the devices
registers, hopefully using
.Xr bus_space 9
methods.
In the
.Fa ipkdb_if
structure, the attach routine must initialize the following fields:
.Pp
.Bl -tag -offset indent -width myenetaddr -compact
.It myenetaddr
fill this with the own ethernet address of the device/machine
.It flags
mark at least
.Dv IPKDB_MYHW
here
.It name
name of the device, only used for a message
.It start
routine called every time
.Nm
is entered
.It leave
routine called every time
.Nm
is left
.It receive
routine called to receive a packet
.It send
routine called to send a packet
.El
.Pp
Additional fields that may be set are:
.Pp
.Bl -tag -offset indent -width myinetaddr -compact
.It myinetaddr
fill this with the own internet address, and mark
.Dv IPKDB_MYIP
in flags
.It port
may be used as a pointer to some device
.El
.It Fn ipkdbfbyte "c"
This routine should fetch a byte from address
.Fa c .
It must not enter any
trap handling code, but instead return \-1 on inability to access the data.
.It Fn ipkdbsbyte "c" "i"
This routine should set the byte pointed to by
.Fa c
to the value given as
.Fa 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.
.El
.Sh SEE ALSO
.Xr ipkdb 4 ,
.Xr boothowto 9