184 lines
5.7 KiB
Groff
184 lines
5.7 KiB
Groff
.\" $NetBSD: ipkdb.9,v 1.6 2003/04/16 13:35:29 wiz 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.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" 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 May 23, 2002
|
|
.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 boothowto, then
|
|
.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
|