Root/
| Source at commit 2862 created 7 years 26 days ago. By ifabio, Tag 2.3 release, bump svn to 2.4 | |
|---|---|
| 1 | /*␊ |
| 2 | * Copyright (c) 1998-2008 Apple 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 | #ifndef _IOKERNELDEBUGGER_H␊ |
| 24 | #define _IOKERNELDEBUGGER_H␊ |
| 25 | ␊ |
| 26 | #include <IOKit/IOService.h>␊ |
| 27 | ␊ |
| 28 | /*! @typedef IODebuggerRxHandler␊ |
| 29 | @discussion Defines the receive handler that must be implemented␊ |
| 30 | by the target to service KDP receive requests. This handler is called␊ |
| 31 | by kdpReceiveDispatcher().␊ |
| 32 | @param target The target object.␊ |
| 33 | @param buffer KDP receive buffer. The buffer allocated has room for␊ |
| 34 | 1518 bytes. The receive handler must not overflow this buffer.␊ |
| 35 | @param length The amount of data received and placed into the buffer.␊ |
| 36 | Set to 0 if no frame was received during the poll interval.␊ |
| 37 | @param timeout The amount of time to poll in milliseconds while waiting␊ |
| 38 | for a frame to arrive. */␊ |
| 39 | ␊ |
| 40 | typedef void (*IODebuggerRxHandler)( IOService * target,␊ |
| 41 | void * buffer,␊ |
| 42 | UInt32 * length,␊ |
| 43 | UInt32 timeout );␊ |
| 44 | ␊ |
| 45 | /*! @typedef IODebuggerTxHandler␊ |
| 46 | @discussion Defines the transmit handler that must be implemented␊ |
| 47 | by the target to service KDP transmit requests. This handler is called␊ |
| 48 | by kdpTransmitDispatcher().␊ |
| 49 | @param target The target object.␊ |
| 50 | @param buffer KDP transmit buffer. This buffer contains a KDP frame␊ |
| 51 | to be sent on the network.␊ |
| 52 | @param length The number of bytes in the transmit buffer. */␊ |
| 53 | ␊ |
| 54 | typedef void (*IODebuggerTxHandler)( IOService * target,␊ |
| 55 | void * buffer,␊ |
| 56 | UInt32 length );␊ |
| 57 | ␊ |
| 58 | /*! @typedef IODebuggerLockState␊ |
| 59 | @discussion Defines flags returned by IOKernelDebugger::lock().␊ |
| 60 | @constant kIODebuggerLockTaken Set if the debugger lock was taken. */␊ |
| 61 | ␊ |
| 62 | typedef enum {␊ |
| 63 | kIODebuggerLockTaken = 0x1␊ |
| 64 | } IODebuggerLockState;␊ |
| 65 | ␊ |
| 66 | /*! @class IOKernelDebugger␊ |
| 67 | @abstract Kernel debugger nub.␊ |
| 68 | @discussion This object interfaces with the KDP␊ |
| 69 | (kernel debugger protocol) module and dispatches KDP requests to its␊ |
| 70 | target (provider). The target, designated as the debugger device, must ␊ |
| 71 | implement a pair of handler functions that are called to handle KDP ␊ |
| 72 | transmit and receive requests during a debugging session. Only a single␊ |
| 73 | IOKernelDebugger in the system can be active at a given time. The␊ |
| 74 | active IOKernelDebugger is the one that has an IOKDP object attached␊ |
| 75 | as a client.␊ |
| 76 | ␊ |
| 77 | The debugger device is usually a subclass of IOEthernetController.␊ |
| 78 | However, any IOService can service an IOKernelDebugger client,␊ |
| 79 | implement the two polled mode handlers, and transport the KDP␊ |
| 80 | packets through a data channel. However, KDP assumes that the␊ |
| 81 | debugger device is an Ethernet interface and therefore it will␊ |
| 82 | always send, and expect to receive, an Ethernet frame. */␊ |
| 83 | ␊ |
| 84 | class IOKernelDebugger : public IOService␊ |
| 85 | {␊ |
| 86 | OSDeclareDefaultStructors( IOKernelDebugger )␊ |
| 87 | ␊ |
| 88 | protected:␊ |
| 89 | IOService * _target; // target (provider)␊ |
| 90 | IODebuggerTxHandler _txHandler; // target's transmit handler.␊ |
| 91 | IODebuggerRxHandler _rxHandler; // target's receive handler.␊ |
| 92 | IOService * _client; // client that has opened us.␊ |
| 93 | bool _pmDisabled; // true if disabled by PM.␊ |
| 94 | ␊ |
| 95 | struct ExpansionData {␊ |
| 96 | thread_call_t activationChangeThreadCall;␊ |
| 97 | UInt32 stateVars[2];␊ |
| 98 | ␉␉IONotifier * interfaceNotifier;␊ |
| 99 | };␊ |
| 100 | ␊ |
| 101 | /*! @var reserved␊ |
| 102 | Reserved for future use. (Internal use only) */␊ |
| 103 | ExpansionData * _reserved;␊ |
| 104 | ␊ |
| 105 | /*! @function kdpReceiveDispatcher␊ |
| 106 | @abstract The KDP receive dispatch function.␊ |
| 107 | @discussion Field KDP receives requests, then dispatches the call to the␊ |
| 108 | registered receiver handler.␊ |
| 109 | @param buffer KDP receive buffer. The buffer allocated by KDP has room␊ |
| 110 | for 1518 bytes. The receive handler must not overflow this buffer.␊ |
| 111 | @param length The amount of data received and placed into the buffer.␊ |
| 112 | Set to 0 if a frame was not received during the poll interval.␊ |
| 113 | @param timeout The amount of time to poll in milliseconds while waiting␊ |
| 114 | for a frame to arrive. ␊ |
| 115 | */␊ |
| 116 | ␊ |
| 117 | static void kdpReceiveDispatcher(void * buffer,␊ |
| 118 | UInt32 * length,␊ |
| 119 | UInt32 timeout);␊ |
| 120 | ␊ |
| 121 | /*! @function kdpTransmitDispatcher␊ |
| 122 | @abstract The KDP transmit dispatch function.␊ |
| 123 | @discussion Field KDP transmit requests, then dispatches the call to the␊ |
| 124 | registered transmit handler.␊ |
| 125 | @param buffer KDP transmit buffer. This buffer contains a KDP frame to␊ |
| 126 | be sent on the network.␊ |
| 127 | @param length The number of bytes in the transmit buffer. ␊ |
| 128 | */␊ |
| 129 | ␊ |
| 130 | static void kdpTransmitDispatcher(void * buffer, UInt32 length);␊ |
| 131 | ␊ |
| 132 | /*! @function free␊ |
| 133 | @abstract Frees the IOKernelDebugger instance. */␊ |
| 134 | ␊ |
| 135 | virtual void free();␊ |
| 136 | ␊ |
| 137 | /*! @function nullTxHandler␊ |
| 138 | @abstract Null transmit handler.␊ |
| 139 | @discussion This function is registered as the transmit handler when an␊ |
| 140 | IOKernelDebugger object surrenders its status as the active debugger nub.␊ |
| 141 | Until another IOKernelDebugger object gets promoted, this function will␊ |
| 142 | handle polled transmit requests from KDP. This function does nothing␊ |
| 143 | useful. ␊ |
| 144 | */␊ |
| 145 | ␊ |
| 146 | static void nullTxHandler( IOService * target,␊ |
| 147 | void * buffer,␊ |
| 148 | UInt32 length );␊ |
| 149 | ␊ |
| 150 | /*! @function nullRxHandler␊ |
| 151 | @abstract Null receive handler.␊ |
| 152 | @discussion This function is registered as the receive handler when an␊ |
| 153 | IOKernelDebugger object surrenders its status as the active debugger nub.␊ |
| 154 | Until another IOKernelDebugger object gets promoted, this function will␊ |
| 155 | handle polled receive requests from KDP. This function does nothing␊ |
| 156 | except to log a warning message. ␊ |
| 157 | */␊ |
| 158 | ␊ |
| 159 | static void nullRxHandler( IOService * target,␊ |
| 160 | void * buffer,␊ |
| 161 | UInt32 * length,␊ |
| 162 | UInt32 timeout );␊ |
| 163 | ␊ |
| 164 | /*! @function registerHandler␊ |
| 165 | @abstract Registers the target and the handler functions.␊ |
| 166 | @discussion This method is called by handleOpen() and handleClose()␊ |
| 167 | to register or unregister the target and its handler functions.␊ |
| 168 | @param target The target object.␊ |
| 169 | @param txHandler The transmit handler function. The null handler is␊ |
| 170 | registered if the argument is zero.␊ |
| 171 | @param rxHandler The receive handler function. The null handler is␊ |
| 172 | registered if the argument is zero. ␊ |
| 173 | */␊ |
| 174 | ␊ |
| 175 | static void registerHandler( IOService * target,␊ |
| 176 | IODebuggerTxHandler txHandler = 0,␊ |
| 177 | IODebuggerRxHandler rxHandler = 0 );␊ |
| 178 | ␊ |
| 179 | /*! @function powerStateWillChangeTo␊ |
| 180 | @abstract Handles notification that the network controller will change␊ |
| 181 | power state.␊ |
| 182 | @discussion If the controller is about to become unusable, then the␊ |
| 183 | controller's handlers are unregistered, and the controller is disabled.␊ |
| 184 | @param flags Describe the capability of the controller in the new power ␊ |
| 185 | state.␊ |
| 186 | @param stateNumber The number of the state in the state array that the ␊ |
| 187 | controller is switching to.␊ |
| 188 | @param policyMaker The policy maker that manages the controller's␊ |
| 189 | power state.␊ |
| 190 | @result Returns the constant 3000000, to indicate a maximum of 3 seconds for the ␊ |
| 191 | preparation to complete, and an acknowledgement delivered to the␊ |
| 192 | policy maker. ␊ |
| 193 | */␊ |
| 194 | ␊ |
| 195 | virtual IOReturn powerStateWillChangeTo( IOPMPowerFlags flags,␊ |
| 196 | unsigned long stateNumber,␊ |
| 197 | IOService * policyMaker );␊ |
| 198 | ␊ |
| 199 | /*! @function powerStateDidChangeTo␊ |
| 200 | @abstract Handles notification that the network controller did change␊ |
| 201 | power state.␊ |
| 202 | @discussion If the controller became usable, then the controller is ␊ |
| 203 | re-enabled, and the controller's handlers are re-registered.␊ |
| 204 | @param flags Description of the capability of the controller in the new power ␊ |
| 205 | state.␊ |
| 206 | @param stateNumber The number of the state in the state array that the ␊ |
| 207 | controller is switching to.␊ |
| 208 | @param policyMaker The policy maker that manages the controller's␊ |
| 209 | power state.␊ |
| 210 | @result Returns the constant 3000000, to indicate a maximum of 3 seconds for the ␊ |
| 211 | preparation to complete, and an acknowledgement delivered to the␊ |
| 212 | policy maker. ␊ |
| 213 | */␊ |
| 214 | ␊ |
| 215 | virtual IOReturn powerStateDidChangeTo( IOPMPowerFlags flags,␊ |
| 216 | unsigned long stateNumber,␊ |
| 217 | IOService * policyMaker );␊ |
| 218 | ␊ |
| 219 | /*! @function handleOpen␊ |
| 220 | @abstract Handles 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 Returns true on success, false otherwise. ␊ |
| 227 | */␊ |
| 228 | ␊ |
| 229 | virtual bool handleOpen( IOService * forClient,␊ |
| 230 | IOOptionBits options,␊ |
| 231 | void * arg );␊ |
| 232 | ␊ |
| 233 | /*! @function handleClose␊ |
| 234 | @abstract Handles a client close.␊ |
| 235 | @discussion This method is called by IOService::close() to handle a␊ |
| 236 | close from a client with the arbitration lock held.␊ |
| 237 | @param forClient The client (IOKDP) requesting the close.␊ |
| 238 | @param options Options passed to the close() call. Not used. ␊ |
| 239 | */␊ |
| 240 | ␊ |
| 241 | virtual void handleClose( IOService * forClient,␊ |
| 242 | IOOptionBits options );␊ |
| 243 | ␊ |
| 244 | /*! @function handleIsOpen␊ |
| 245 | @abstract Queries whether a client has an open on this object.␊ |
| 246 | @discussion This method is called by IOService::isOpen() with the␊ |
| 247 | arbitration lock held.␊ |
| 248 | @result Returns true if the specified client, or any client if none (0) is␊ |
| 249 | specified, presently has an open on this object. ␊ |
| 250 | */␊ |
| 251 | ␊ |
| 252 | virtual bool handleIsOpen( const IOService * forClient ) const;␊ |
| 253 | ␊ |
| 254 | ␉static bool interfacePublished( void *target, void *param, IOService *service );␊ |
| 255 | ␊ |
| 256 | public:␊ |
| 257 | ␊ |
| 258 | /*! @function lock␊ |
| 259 | @abstract Takes the debugger lock conditionally.␊ |
| 260 | @discussion This method takes the debugger lock if the object given matches the␊ |
| 261 | target registered by registerHandler().␊ |
| 262 | @param target The target or provider of an IOKernelDebugger object.␊ |
| 263 | @result Returns kIODebuggerLockTaken if the lock was taken, or 0 otherwise. ␊ |
| 264 | */␊ |
| 265 | ␊ |
| 266 | static IODebuggerLockState lock( IOService * target );␊ |
| 267 | ␊ |
| 268 | /*! @function unlock␊ |
| 269 | @abstract Releases the debugger lock.␊ |
| 270 | @discussion This method releases the debugger lock if the kIODebuggerLockTaken flag is␊ |
| 271 | set in the argument. ␊ |
| 272 | */␊ |
| 273 | ␊ |
| 274 | static void unlock( IODebuggerLockState state );␊ |
| 275 | ␊ |
| 276 | /*! @function init␊ |
| 277 | @abstract Initializes an IOKernelDebugger instance.␊ |
| 278 | @param target The target object that implements the debugger handlers.␊ |
| 279 | @param txHandler The target's transmit handler. A pointer to a 'C' function.␊ |
| 280 | @param rxHandler The target's receive handler. A pointer to a 'C' function.␊ |
| 281 | @result Returns true if the instance initialized successfully, false otherwise. ␊ |
| 282 | */␊ |
| 283 | ␊ |
| 284 | virtual bool init( IOService * target,␊ |
| 285 | IODebuggerTxHandler txHandler,␊ |
| 286 | IODebuggerRxHandler rxHandler );␊ |
| 287 | ␊ |
| 288 | /*! @function debugger␊ |
| 289 | @abstract Factory method that performs allocation and initialization␊ |
| 290 | of an IOKernelDebugger object.␊ |
| 291 | @param target The target object that implements the debugger handlers.␊ |
| 292 | @param txHandler The target's transmit handler. A pointer to a 'C' function.␊ |
| 293 | @param rxHandler The target's receive handler. A pointer to a 'C' function.␊ |
| 294 | @result Returns an IOKernelDebugger instance on success, 0 otherwise. ␊ |
| 295 | */␊ |
| 296 | ␊ |
| 297 | static IOKernelDebugger * debugger( IOService * target,␊ |
| 298 | IODebuggerTxHandler txHandler,␊ |
| 299 | IODebuggerRxHandler rxHandler );␊ |
| 300 | ␊ |
| 301 | /*␊ |
| 302 | * Entry point for generic messages delivered from the provider.␊ |
| 303 | */␊ |
| 304 | ␊ |
| 305 | virtual IOReturn message( UInt32 type, IOService * provider, void * arg );␊ |
| 306 | ␊ |
| 307 | /*! @function signalDebugger␊ |
| 308 | @abstract Signal the kernel to enter the debugger when safe.␊ |
| 309 | */␊ |
| 310 | static void signalDebugger(void);␊ |
| 311 | ␊ |
| 312 | // Virtual function padding␊ |
| 313 | OSMetaClassDeclareReservedUnused( IOKernelDebugger, 0);␊ |
| 314 | OSMetaClassDeclareReservedUnused( IOKernelDebugger, 1);␊ |
| 315 | OSMetaClassDeclareReservedUnused( IOKernelDebugger, 2);␊ |
| 316 | OSMetaClassDeclareReservedUnused( IOKernelDebugger, 3);␊ |
| 317 | };␊ |
| 318 | ␊ |
| 319 | // Concise form of the lock()/unlock() static member functions.␊ |
| 320 | //␊ |
| 321 | #define IODebuggerLock IOKernelDebugger::lock␊ |
| 322 | #define IODebuggerUnlock IOKernelDebugger::unlock␊ |
| 323 | ␊ |
| 324 | #endif /* !_IOKERNELDEBUGGER_H */␊ |
| 325 | |
