The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/ipkdb/README.port

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

    1 $NetBSD: README.port,v 1.4 2006/11/24 22:52:16 wiz 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.

Cache object: 3b4ca716a96733af8206dc55dae9e100


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.