sys/ipkdb/README.port

   1 $NetBSD: README.port,v 1.3 2000/03/22 20:58:29 ws Exp $
   2
   3 What to Look for when Porting the IPKDB Interface
   4 ===============================================
   5
   6 Try to avoid calling any routine from the rest of the kernel.
   7 (It's OK to call these routines during initialization).
   8 You wouldn't be able to set breakpoints within these routines
   9 during debugging, since this would hang the debugging interface.
  10
  11
  12 Interface between IPKDB and Ethernet Board (sys/dev/yy/if_xx.c)
  13 --------------------------------------------------------------
  14
  15 General Considerations
  16
  17
  18 There is a problem when the debugger uses the same ethernet board as
  19 does the rest of the kernel.  For one thing there might arrive packets
  20 destined for the kernel during debugging sessions.  These packets
  21 are currently lost.  For packets on their way out the driver has
  22 to leave the interrupt pending condition alone, so the interrupt
  23 handler gets a chance to send more packets via the interface.
  24
  25
  26 Configuration Files
  27
  28
  29 For any interface that may be used for debugging there should be
  30 an option, put into opt_ipkdb.h, that is enabled if the kernel
  31 shall actually use this interface.  The relevant part of the
  32 "files" file for interface "xx" would look like this:
  33
  34         defopt  opt_ipkdb.h     IPKDB_XX        : IPKDB
  35         device  xx: ether, ifnet, arp
  36         file    dev/zz/if_xx.c          xx | ipkdb_xx
  37
  38 The file dev/zz/if_xx.c contains both the code of the kernel
  39 driver and the IPKDB driver for this interface.  You should
  40 #include "opt_ipkdb.h" in there and conditionalize the
  41 compilation of the IPKDB driver with
  42 #ifdef IPKDB_XX
  43
  44 The appropriate part of the machine configuration would read like
  45 this:
  46
  47         options         IPKDBKEY="\"IPKDB key for remote debugging\""
  48         options         IPKDB_XX
  49
  50
  51 Driver Code
  52
  53
  54 In order to be able to find the debugging interface, the driver
  55 has to provide an attach routine that the machine dependent code
  56 can call at an appropriate time (see below).  The attach routine
  57 should take as its first argument a pointer to a struct ipkdb_if
  58 plus some additional parameters that allow it to access the
  59 devices registers, hopefully using bus_space_* methods.
  60 In the ipkdb_if structure, the attach routine must initialize
  61 the following fields:
  62
  63         myenetaddr      fill this with the own ethernet address of
  64                         the device/machine.
  65         flags           mark at least IPKDB_MYHW here.
  66         name            Name of the device, only used for a message.
  67         start           routine called everytime IPKDB is entered.
  68         leave           routine called everytime IPKDB is left.
  69         receive         routine called to receive a packet.
  70         send            routine called to send a packet.
  71
  72 Additional fields that may be set are:
  73
  74         myinetaddr      fill this with the own internet address,
  75                         and mark IPKDB_MYIP in flags.
  76         port            may be used as a pointer to some device
  77                         dependent data.  Unused by other code.
  78
  79 The routine should check for existence of the ethernet board.
  80 This routine should also note enough information so it is able
  81 to later find the system driver instance for the same board in
  82 order to coordinate its action with the system driver.
  83
  84 The routine should return 0 on success and -1 on failure.
  85
  86 The remainder of the routines are called via function pointers
  87 in the ipkdb_if structure.  The probe routine needs to fill in
  88 these function pointers with proper values.
  89
  90 void start(struct ipkdb_if *kip)
  91
  92 This routine gets called every time the debugger is entered.
  93 kip is a pointer to the ipkdb_if structure used for debugging.
  94
  95 It should initialize the hardware and software interface.
  96
  97 This routine should also note the current state of the board
  98 (as far as it can) so a later call to leave can reinstantiate
  99 this state.
 100
 101 void leave(struct ipkdb_if *kip)
 102
 103 This routine is called whenever the debugger is left.  It should
 104 restore the ethernet hardware to the state prior to the last call to
 105 start.
 106
 107 int receive(struct ipkdb_if *kip, u_char *buf, int poll)
 108
 109 This routine should return an ethernet packet to the buffer pointed to
 110 by buf and return its length.  The packet should be complete with the
 111 ethernet header, i.e. it starts with the recipient address, but does not
 112 contain the ethernet checksum.
 113
 114 If poll is set, it should return immediately, if no packet is available.
 115 Otherwise it should wait for the next packet.
 116
 117 This routine shall return the number of bytes transferred to buf.
 118
 119 void send(struct ipkdb_if *kip, u_char *buf, int l)
 120
 121 This routine should send an ethernet packet out of the debugging
 122 interface.  The packet is already complete with the ethernet header,
 123 but does not contain the ethernet checksum.
 124
 125
 126 Interface between IPKDB and Machine (sys/arch/xxx/xxx/ipkdb_glue.c)
 127 -----------------------------------------------------------------
 128
 129
 130 void ipkdbinit(void)
 131
 132 This routine gets called when the debugger should be entered for the
 133 first time.
 134
 135 int ipkdb_poll(void)
 136
 137 This routine gets called after a panic to check for a keypress by the user.
 138 If implemented it allows the user to press any key on the console to do
 139 the automatic reboot after a panic.  Otherwise the debugging interface
 140 will wait forever for some remote debugger to attach in case of a panic.
 141
 142 int ipkdbcmds(void)
 143
 144 There should be call to this routine from somewhere in locore when the
 145 trap mechanism determines that the debugger should be entered, i.e. on
 146 a single step or breakpoint interrupt from kernel code.  The trapping
 147 mechanism should already have stored the registers into the global area
 148 ipkdbregs.  The layout of this area must be the same as that expected
 149 by GDB.  The return value of this routine is 0, if the user wants to
 150 continue, 1 if the user wants to do single stepping, and 2 if the user
 151 has detached from debugging.
 152
 153 int ipkdbfbyte(u_char *p)
 154
 155 This routine should fetch a byte from address p. It must not enter any
 156 trap handling code, but instead return -1 on inability to access the data.
 157
 158 void ipkdbsbyte(u_char *p,u_char c)
 159
 160 This routine should set the byte pointed to by p to the value given as c.
 161 The routine must not enter any trap handling code.  Furthermore it should
 162 reset the modification bit in the relevant page table entry to the value
 163 before the store.
 164
 165
 166 sys/arch/xxx/include/ipkdb.h
 167
 168
 169 Machine dependent definitions and protoypes should be in
 170 sys/arch/xxx/include/ipkdb.h, i.e. in <machine/ipkdb.h>.  This includes
 171 the size of the array ipkdbregs, that holds the contents of the registers
 172 of the debuggee at the time IPKDB is entered.