| blob | dabbcf5cef5379d609e899f8d48b5c8db5dd9571 |
1 .\" $NetBSD: ipkdb.9,v 1.8 2008/04/30 13:10:58 martin Exp $
2 .\"
3 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Gregory McGarry.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd September 4, 2009
31 .Dt IPKDB 9
32 .Os
33 .Sh NAME
34 .Nm ipkdb
35 .Nd machine-dependent interface to ipkdb
36 .Sh SYNOPSIS
37 .In ipkdb/ipkdb.h
38 .Ft void
39 .Fn ipkdb_init "void"
40 .Ft void
41 .Fn ipkdb_connect "int when"
42 .Ft int
43 .Fn ipkdbcmds "void"
44 .Ft void
45 .Fn ipkdbinit "void"
46 .Ft void
47 .Fn ipkdb_trap "void"
48 .Ft int
49 .Fn ipkdb_poll "void"
50 .Ft int
51 .Fn ipkdbif_init "struct ipkdb_if *kip"
52 .Ft int
53 .Fn ipkdbfbyte "u_char *c"
54 .Ft int
55 .Fn ipkdbsbyte "u_char *c" "int i"
56 .Sh DESCRIPTION
57 The machine-dependent code must support this interface for operation with
58 .Xr ipkdb 4 .
59 .Pp
60 During system bootstrap, machine-dependent code must invoke
61 .Fn ipkdb_init .
62 If the kernel is booted with
63 .Dv RB_KDB
64 set in
65 .Va boothowto
66 (see
67 .Xr boothowto 9 ) ,
68 .Xr ipkdb 4
69 is enabled by invoking
70 .Fn ipkdb_connect ,
71 setting the
72 .Fa when
73 argument to 0.
74 .Pp
75 .Fn ipkdbcmds
76 is invoked by machine-dependent code when the trap mechanism
77 determines that the debugger should be entered, i.e., on a single step
78 or breakpoint interrupt from kernel code.
79 The trapping mechanism should already have stored the registers into
80 the global area ipkdbregs.
81 The layout of this area must be the same as that expected by
82 .Xr gdb 1 .
83 Valid return values are:
84 .Pp
85 .Bl -tag -offset indent -width IPKDB_CMD_EXITXX -compact
86 .It Dv IPKDB_CMD_RUN
87 user wants to continue
88 .It Dv IPKDB_CMD_STEP
89 user wants to do single stepping
90 .It Dv IPKDB_CMD_EXIT
91 user has detached from debugging
92 .El
93 .Sh FUNCTIONS
94 The machine-dependent code must provide the following functions for
95 the machine-independent code.
96 .Bl -tag -width ipkdbif_initXXXXXXX -compact
97 .It Fn ipkdbinit ""
98 This routine gets called when the debugger should be entered for the
99 first time.
100 .It Fn ipkdb_trap ""
101 This routine is part of the trap handler.
102 Whenever a trap happens (e.g., when hitting a breakpoint during debugging),
103 .Fn ipkdb_trap
104 decides if the Debugger needs to be called.
105 If there are other ways to decide that, it's not necessary to provide an
106 .Fn ipkdb_trap
107 implementation.
108 .It Fn ipkdb_poll ""
109 This routine gets called after a panic to check for a key press by the
110 user.
111 If implemented it allows the user to press any key on the
112 console to do the automatic reboot after a panic.
113 Otherwise the debugging interface will wait forever for some remote
114 debugger to attach in case of a panic.
115 .It Fn ipkdbif_init "kip"
116 In order to be able to find the debugging interface, the network
117 driver must invoke
118 .Fn ipkdbif_init
119 with
120 .Fa kip
121 specifying a
122 .Fa struct ipkdb_if
123 plus some additional parameters that allow it to access the devices
124 registers, hopefully using
125 .Xr bus_space 9
126 methods.
127 In the
128 .Fa ipkdb_if
129 structure, the attach routine must initialize the following fields:
130 .Pp
131 .Bl -tag -offset indent -width myenetaddr -compact
132 .It myenetaddr
133 fill this with the own ethernet address of the device/machine
134 .It flags
135 mark at least
136 .Dv IPKDB_MYHW
137 here
138 .It name
139 name of the device, only used for a message
140 .It start
141 routine called every time
142 .Nm
143 is entered
144 .It leave
145 routine called every time
146 .Nm
147 is left
148 .It receive
149 routine called to receive a packet
150 .It send
151 routine called to send a packet
152 .El
153 .Pp
154 Additional fields that may be set are:
155 .Pp
156 .Bl -tag -offset indent -width myinetaddr -compact
157 .It myinetaddr
158 fill this with the own internet address, and mark
159 .Dv IPKDB_MYIP
160 in flags
161 .It port
162 may be used as a pointer to some device
163 .El
164 .It Fn ipkdbfbyte "c"
165 This routine should fetch a byte from address
166 .Fa c .
167 It must not enter any
168 trap handling code, but instead return \-1 on inability to access the data.
169 .It Fn ipkdbsbyte "c" "i"
170 This routine should set the byte pointed to by
171 .Fa c
172 to the value given as
173 .Fa i .
174 The routine must not enter any trap handling code.
175 Furthermore it should reset the modification bit in the relevant page
176 table entry to the value before the store.
177 .El
178 .Sh SEE ALSO
179 .Xr ipkdb 4 ,
180 .Xr boothowto 9