Root/
Source at commit 2351 created 10 years 5 months ago. By ifabio, more info from dmi tables | |
---|---|
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 |