iokit/IOKit/network/IOKernelDebugger.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22 /*
  23  * Copyright (c) 1999 Apple Computer, Inc.  All rights reserved.
  24  *
  25  * IOKernelDebugger.cpp
  26  *
  27  * HISTORY
  28  *
  29  */
  30
  31 #ifndef _IOKERNELDEBUGGER_H
  32 #define _IOKERNELDEBUGGER_H
  33
  34 #include <IOKit/IOService.h>
  35
  36 /*! @typedef IODebuggerRxHandler
  37     @discussion Defines the receive handler that must be implemented
  38     by the target to service KDP receive requests. This handler is called
  39     by kdpReceiveDispatcher().
  40     @param target The target object.
  41     @param buffer KDP receive buffer. The buffer allocated has room for
  42            1518 bytes. The receive handler must not overflow this buffer.
  43     @param length The amount of data received and placed into the buffer.
  44            Set to 0 if no frame was received during the poll interval.
  45     @param timeout The amount of time to poll in milliseconds while waiting
  46            for a frame to arrive. */
  47
  48 typedef void (*IODebuggerRxHandler)( IOService * target,
  49                                      void *      buffer,
  50                                      UInt32 *    length,
  51                                      UInt32      timeout );
  52
  53 /*! @typedef IODebuggerTxHandler
  54     @discussion Defines the transmit handler that must be implemented
  55     by the target to service KDP transmit requests. This handler is called
  56     by kdpTransmitDispatcher().
  57     @param target The target object.
  58     @param buffer KDP transmit buffer. This buffer contains a KDP frame
  59            to be sent on the network.
  60     @param length The number of bytes in the transmit buffer. */
  61
  62 typedef void (*IODebuggerTxHandler)( IOService * target,
  63                                      void *      buffer,
  64                                      UInt32      length );
  65
  66 /*! @typedef IODebuggerLockState
  67     @discussion Defines flags returned by IOKernelDebugger::lock().
  68     @constant kIODebuggerLockTaken Set if the debugger lock was taken. */
  69
  70 typedef enum {
  71     kIODebuggerLockTaken = 0x1,
  72 } IODebuggerLockState;
  73
  74 /*! class IOKernelDebugger : public IOService
  75     @abstract Kernel debugger nub.
  76     @discussion This object interfaces with the KDP
  77     (kernel debugger protocol) module and dispatches KDP requests to its
  78     target (provider). The target, designated as the debugger device, must
  79     implement a pair of handler functions that are called to handle KDP
  80     transmit and receive requests during a debugging session. Only a single
  81     IOKernelDebugger in the system can be active at a given time. The
  82     active IOKernelDebugger is the one that has an IOKDP object attached
  83     as a client.
  84
  85     The debugger device is usually a subclass of IOEthernetController.
  86     However, any IOService can service an IOKernelDebugger client,
  87     implement the two polled mode handlers, and transport the KDP
  88     packets through a data channel. However, KDP assumes that the
  89     debugger device is an Ethernet interface and therefore it will
  90     always send, and expect to receive, an Ethernet frame. */
  91
  92 class IOKernelDebugger : public IOService
  93 {
  94     OSDeclareDefaultStructors( IOKernelDebugger )
  95
  96 protected:
  97     IOService *            _target;      // target (provider)
  98     IODebuggerTxHandler    _txHandler;   // target's transmit handler.
  99     IODebuggerRxHandler    _rxHandler;   // target's receive handler.
 100     IOService *            _client;      // client that has opened us.
 101     bool                   _pmDisabled;  // true if disabled by PM.
 102
 103     struct ExpansionData { };
 104     /*! @var reserved
 105         Reserved for future use.  (Internal use only)  */
 106     ExpansionData *         _reserved;
 107
 108
 109     static void pmEnableDebugger(  IOKernelDebugger * debugger );
 110     static void pmDisableDebugger( IOKernelDebugger * debugger );
 111
 112 /*! @function kdpReceiveDispatcher
 113     @abstract The KDP receive dispatch function.
 114     @discussion Field KDP receive requests, then dispatches the call to the
 115     registered receiver handler.
 116     @param buffer KDP receive buffer. The buffer allocated by KDP has room
 117            for 1518 bytes. The receive handler must not overflow this buffer.
 118     @param length The amount of data received and placed into the buffer.
 119            Set to 0 if a frame was not received during the poll interval.
 120     @param timeout The amount of time to poll in milliseconds while waiting
 121            for a frame to arrive. */
 122
 123     static void kdpReceiveDispatcher(void *   buffer,
 124                                      UInt32 * length,
 125                                      UInt32   timeout);
 126
 127 /*! @function kdpTransmitDispatcher
 128     @abstract The KDP transmit dispatch function.
 129     @discussion Field KDP transmit requests, then dispatches the call to the
 130     registered transmit handler.
 131     @param buffer KDP transmit buffer. This buffer contains a KDP frame to
 132            be sent on the network.
 133     @param length The number of bytes in the transmit buffer. */
 134
 135     static void kdpTransmitDispatcher(void * buffer, UInt32 length);
 136
 137 /*! @function free
 138     @abstract Free the IOKernelDebugger instance. */
 139
 140     virtual void free();
 141
 142 /*! @function nullTxHandler
 143     @abstract Null transmit handler.
 144     @discussion This function is registered as the transmit handler when an
 145     IOKernelDebugger object surrenders its status as the active debugger nub.
 146     Until another IOKernelDebugger object gets promoted, this function will
 147     handle polled transmit requests from KDP. This function does nothing
 148     useful. */
 149
 150     static void nullTxHandler( IOService * target,
 151                                void *      buffer,
 152                                UInt32      length );
 153
 154 /*! @function nullRxHandler
 155     @abstract Null receive handler.
 156     @discussion This function is registered as the receive handler when an
 157     IOKernelDebugger object surrenders its status as the active debugger nub.
 158     Until another IOKernelDebugger object gets promoted, this function will
 159     handle polled receive requests from KDP. This function does nothing
 160     except to log a warning message. */
 161
 162     static void nullRxHandler( IOService * target,
 163                                void *      buffer,
 164                                UInt32 *    length,
 165                                UInt32      timeout );
 166
 167 /*! @function registerHandler
 168     @abstract Register the target and the handler functions.
 169     @discussion This method is called by handleOpen() and handleClose()
 170     to register or unregister the target and its handler functions.
 171     @param target The target object.
 172     @param txHandler The transmit handler function. The null handler is
 173     registered if the argument is zero.
 174     @param rxHandler The receive handler function. The null handler is
 175     registered if the argument is zero. */
 176
 177     static void registerHandler( IOService *          target,
 178                                  IODebuggerTxHandler  txHandler = 0,
 179                                  IODebuggerRxHandler  rxHandler = 0 );
 180
 181 /*! @function powerStateWillChangeTo
 182     @abstract Handle notification that the network controller will change
 183     power state.
 184     @discussion If the controller is about to become unusable, then the
 185     controller's handlers are unregistered, and the controller disabled.
 186     @param flags Describe the capability of the controller in the new power
 187            state.
 188     @param stateNumber The number of the state in the state array that the
 189            controller is switching to.
 190     @param policyMaker The policy-maker that manages the controller's
 191            power state.
 192     @result The constant 3000000, to indicate a maximum of 3 seconds for the
 193             preparation to complete, and an acknowledgement delivered to the
 194             policy-maker. */
 195
 196     virtual IOReturn powerStateWillChangeTo( IOPMPowerFlags  flags,
 197                                              UInt32          stateNumber,
 198                                              IOService *     policyMaker );
 199
 200 /*! @function powerStateDidChangeTo
 201     @abstract Handle notification that the network controller did change
 202     power state.
 203     @discussion If the controller became usable, then the controller is
 204     re-enabled, and the controller's handlers are re-registered.
 205     @param flags Describe the capability of the controller in the new power
 206            state.
 207     @param stateNumber The number of the state in the state array that the
 208            controller is switching to.
 209     @param policyMaker The policy-maker that manages the controller's
 210            power state.
 211     @result The constant 3000000, to indicate a maximum of 3 seconds for the
 212             preparation to complete, and an acknowledgement delivered to the
 213             policy-maker. */
 214
 215     virtual IOReturn powerStateDidChangeTo( IOPMPowerFlags  flags,
 216                                             UInt32          stateNumber,
 217                                             IOService *     policyMaker );
 218
 219 /*! @function handleOpen
 220     @abstract Handle a client open.
 221     @discussion This method is called by IOService::open() to handle an
 222     open from a client (IOKDP) with the arbitration lock held.
 223     @param forClient The client (IOKDP) requesting the open.
 224     @param options Options passed to the open() call. Not used.
 225     @param arg A family defined argument passed to the open() call. Not used.
 226     @result true on success, false otherwise. */
 227
 228     virtual bool handleOpen( IOService *    forClient,
 229                              IOOptionBits   options,
 230                              void *         arg );
 231
 232 /*! @function handleClose
 233     @abstract Handle a client close.
 234     @discussion This method is called by IOService::close() to handle a
 235     close from a client with the arbitration lock held.
 236     @param forClient The client (IOKDP) requesting the close.
 237     @param options Options passed to the close() call. Not used. */
 238
 239     virtual void handleClose( IOService *   forClient,
 240                               IOOptionBits  options );
 241
 242 /*! @function handleIsOpen
 243     @abstract Query whether a client has an open on this object.
 244     @discussion This method is called by IOService::isOpen() with the
 245     arbitration lock held.
 246     @result true if the specified client, or any client if none (0) is
 247     specified, presently has an open on this object. */
 248
 249     virtual bool handleIsOpen( const IOService * forClient ) const;
 250
 251 public:
 252
 253 /*! @function lock
 254     @abstract Take the debugger lock conditionally.
 255     @discussion Take the debugger lock if the object given matches the
 256     target registered by registerHandler().
 257     @param target The target or provider of an IOKernelDebugger object.
 258     @result kIODebuggerLockTaken if the lock was taken, or 0 otherwise. */
 259
 260     static IODebuggerLockState lock( IOService * target );
 261
 262 /*! @function unlock
 263     @abstract Release the debugger lock.
 264     @discussion Release the debugger lock if the kIODebuggerLockTaken flag is
 265     set in the argument. */
 266
 267     static void unlock( IODebuggerLockState state );
 268
 269 /*! @function init
 270     @abstract Initialize an IOKernelDebugger instance.
 271     @param target The target object that implements the debugger handlers.
 272     @param txHandler The target's transmit handler. A pointer to a 'C' function.
 273     @param rxHandler The target's receive handler. A pointer to a 'C' function.
 274     @result true if the instance initialized successfully, false otherwise. */
 275
 276     virtual bool init( IOService *          target,
 277                        IODebuggerTxHandler  txHandler,
 278                        IODebuggerRxHandler  rxHandler );
 279
 280 /*! @function debugger
 281     @abstract A factory method that performs allocation and initialization
 282     of an IOKernelDebugger object.
 283     @param target The target object that implements the debugger handlers.
 284     @param txHandler The target's transmit handler. A pointer to a 'C' function.
 285     @param rxHandler The target's receive handler. A pointer to a 'C' function.
 286     @result An IOKernelDebugger instance on success, 0 otherwise. */
 287
 288     static IOKernelDebugger * debugger( IOService *          target,
 289                                         IODebuggerTxHandler  txHandler,
 290                                         IODebuggerRxHandler  rxHandler );
 291
 292     // Virtual function padding
 293     OSMetaClassDeclareReservedUnused( IOKernelDebugger,  0);
 294     OSMetaClassDeclareReservedUnused( IOKernelDebugger,  1);
 295     OSMetaClassDeclareReservedUnused( IOKernelDebugger,  2);
 296     OSMetaClassDeclareReservedUnused( IOKernelDebugger,  3);
 297 };
 298
 299 // Concise form of the lock()/unlock() static member functions.
 300 //
 301 #define IODebuggerLock    IOKernelDebugger::lock
 302 #define IODebuggerUnlock  IOKernelDebugger::unlock
 303
 304 #endif /* !_IOKERNELDEBUGGER_H */