![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to IOKernelDebugger.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / XNU / iokit / IOKit / network|
Return to IOKernelDebugger.h CVS log | Up to [Apple XNU] / XNU / iokit / IOKit / network |
1.1 root 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: // #define __USE_DEBUGGER_LOCK 1 // XXX - not yet!!!
35:
36: #include <IOKit/IOService.h>
37:
38:
39: /*! @typedef IODebuggerRxHandler
40: @discussion Defines the receive handler that must be implemented
41: by the provider to service KDP requests. This handler is called
42: by the dispatch function in IOKernelDebugger.
43: @param provider The provider object.
44: @param buffer KDP receive buffer. The buffer allocated has room for
45: 1518 bytes. Never overflow the buffer!
46: @param length The amount of data placed into the receive buffer
47: by teh receive handler. Set to 0 if no frame was received
48: during the poll interval.
49: @param timeout Poll for a maximum period of 'timeout' milliseconds
50: while waiting for a frame to arrive. */
51:
52: typedef void (*IODebuggerRxHandler)(IOService * provider,
53: void * buffer,
54: UInt * length,
55: UInt timeout);
56:
57: /*! @typedef IODebuggerTxHandler
58: @discussion Defines the transmit handler that must be implemented
59: by the provider to service KDP requests. This handler is called
60: by the dispatch function in IOKernelDebugger.
61: @param provider The provider object.
62: @param buffer KDP transmit buffer. This buffer contains a KDP frame
63: to be sent on the wire.
64: @param length The number of bytes in the transmit buffer. */
65:
66: typedef void (*IODebuggerTxHandler)(IOService * provider,
67: void * buffer,
68: UInt length);
69:
70: /*! @typedef IODebuggerLockState
71: @discussion Defines the return from IOKernelDebugger::lock.
72: @constant kIODebuggerLocked Set if the debugger lock was taken.
73: Otherwise, the debugger lock was not taken. */
74:
75: typedef enum {
76: kIODebuggerLockTaken = 0x1,
77: } IODebuggerLockState;
78:
79: /*! class IOKernelDebugger : public IOService
80: @abstract Kernel debugger nub.
81: @discussion This object interfaces with the KDP module and
82: dispatches KDP requests to its provider. The provider, designated the
83: debugger device, must implement a pair of handler functions that are
84: called to handle KDP transmit and receive requests. A debugger lock,
85: allocated by the IOKernelDebugger, can be used by the debugger device
86: to block calls to its handler functions during critical sections.
87: Only a single IOKernelDebugger can be registered at any given time.
88:
89: The debugger device is usually a subclass of IOEthernetController.
90: However, any IOService can attach an IOKernelDebugger client,
91: implement the two polled mode handlers, and transport the KDP
92: packets through a data channel. Having said this, the KDP assumes
93: that the debugger device is an Ethernet interface and therefore
94: it will always send, and expect to receive, an Ethernet frame. */
95:
96: class IOKernelDebugger : public IOService
97: {
98: OSDeclareDefaultStructors(IOKernelDebugger)
99:
100: protected:
101: IOService * _provider; // debugger device.
102: IODebuggerTxHandler _txHandler; // provider's transmit handler.
103: IODebuggerRxHandler _rxHandler; // provider's receive handler.
104:
105: /*! @function initialize
106: @discussion IOKernelDebugger class initializer.
107: The debugger lock is allocated and initialized. */
108:
109: static void initialize();
110:
111: /*! @function kdpReceiveDispatcher
112: @abstract The KDP receive dispatch function.
113: @discussion Handles KDP receive requests during a debugging session,
114: then dispatches the call to the registered receiver handler. This
115: function is registered with KDP via kdp_register_send_receive().
116: @param pkt KDP receive buffer. The buffer allocated has room for
117: 1518 bytes. Never overflow the buffer!
118: @param pkt_len The amount of data placed into the receive buffer.
119: Set to 0 if a frame was not received during the poll interval.
120: @param timeout The registered handler must poll for a maximum period of
121: 'timeout' milliseconds while waiting for a frame to arrive. */
122:
123: static void kdpReceiveDispatcher(void * pkt, UInt * pkt_len, UInt timeout);
124:
125: /*! @function kdpTransmitDispatcher
126: @abstract The KDP transmit dispatch function.
127: @discussion Handles KDP transmit requests during a debugging session,
128: then dispatches the call to the registered transmit handler. This
129: function is registered with KDP via kdp_register_send_receive().
130: @param pkt KDP transmit buffer. This buffer contains a KDP frame to be
131: sent on the wire.
132: @param pkt_len The number of bytes in the transmit buffer. */
133:
134: static void kdpTransmitDispatcher(void * pkt, UInt pkt_len);
135:
136: /*! @function free
137: @discussion Free the IOKernelDebugger instance. Used for debugging.
138: Log a message then call super::free(). */
139:
140: virtual void free();
141:
142: /*! @function openProvider
143: @discussion Open the attached provider, register it as the debugger
144: device, and register the dispatch and handler functions.
145: @param provider The provider object. This object is registered as the
146: debugger device.
147: @result true on sucess, or false if the controller open failed, or an
148: IOKernelDebugger instance has already been registered. */
149:
150: bool openProvider(IOService * provider);
151:
152: /*! @function closeProvider
153: @discussion Close our provider, and undo the registration performed in
154: openProvider(). Another IOKernelDebugger instance that comes along will
155: be able to take over the debugging responsibilities.
156: provider: The provider object. */
157:
158: void closeProvider(IOService * provider);
159:
160: /*! @function nullTxHandler
161: @abstract Null transmit handler.
162: @discussion This function is registered as the transmit handler by
163: closeProvider() after the provider's handler is unregistered. This
164: function does nothing except to log a warning message. */
165:
166: static void nullTxHandler(IOService * provider,
167: void * buffer,
168: UInt length);
169:
170: /*! @function nullRxHandler
171: @abstract Null receive handler.
172: @discussion This function is registered as the receive handler by
173: closeProvider() after the provider's handler is unregistered. This
174: function does nothing except to log a warning message. */
175:
176: static void nullRxHandler(IOService * provider,
177: void * buffer,
178: UInt * length,
179: UInt timeout);
180:
181: public:
182:
183: /*! @function lock
184: @discussion Take the debugger lock conditionally. The debugger lock
185: is taken only if the provider given is the current registered
186: debugger device. The debugger device is registered via the
187: openProvider() method, and unregistered via closeProvider().
188: @param provider The caller of the lock function.
189: @result kIODebuggerLocked if the lock was taken, or kIODebuggerUnlocked
190: if the lock was not taken. */
191:
192: static IODebuggerLockState lock(IOService * provider);
193:
194: /*! @function unlock
195: @discussion Release the debugger lock if the argument is
196: kIODebuggerLocked.
197: @param state The return from the IOKernelDebugger::lock(). */
198:
199: static void unlock(IODebuggerLockState state);
200:
201: /*! @function init
202: @discussion The IOKernelDebugger initializer.
203: @param provider The provider of the IOKernelDebugger object.
204: @param txHandler The provider's transmit handler. A pointer to a C
205: function.
206: @param rxHandler The provider's receive handler. A pointer to a C function.
207: @result true if the instance initialized successfully, false otherwise. */
208:
209: virtual bool init(IOService * provider,
210: IODebuggerTxHandler txHandler,
211: IODebuggerRxHandler rxHandler);
212:
213: /*! @function debugger
214: @discussion A factory method that performs allocation and initialization.
215: @param provider The provider of the IOKernelDebugger object.
216: @param txHandler The provider's transmit handler. A pointer to a C
217: function.
218: @param rxHandler The provider's receive handler. A pointer to a C function.
219: @result An IOKernelDebugger instance on success, 0 otherwise. */
220:
221: static IOKernelDebugger * debugger(IOService * provider,
222: IODebuggerTxHandler txHandler,
223: IODebuggerRxHandler rxHandler);
224:
225: /*! @function attach
226: @discussion Attach to our provider, then call openProvider().
227: @param provider The provider object.
228: @result true on success, false otherwise. */
229:
230: virtual bool attach(IOService * provider);
231:
232: /*! @function detach
233: @discussion Call closeProvider(), then detach from our provider.
234: @param provider The provider object. */
235:
236: virtual void detach(IOService * provider);
237:
238: /*! @function finalize
239: @discussion Final termination notification. To ensure that closeProvider()
240: is called before the object is terminated.
241: @param options termination options, not used. */
242:
243: virtual bool finalize(IOOptionBits options = 0);
244:
245: /*! @function message
246: @discussion Facility provided by IOService for general purpose
247: provider-to-client notification. We catch the kIOMessageServiceIsTerminated
248: message to detect when our provider becomes inactive, and call
249: closeProvider().
250: @param type message tupe.
251: @param provider The provider object.
252: @param argument message argument. Not used.
253: @result kIOReturnSuccess for kIOMessageServiceIsTerminated messages,
254: kIOReturnUnsupported otherwise. */
255:
256: virtual IOReturn message(UInt32 type,
257: IOService * provider,
258: void * argument = 0);
259: };
260:
261: // Shortened versions of the lock/unlock static functions.
262: //
263: #define IODebuggerLock IOKernelDebugger::lock
264: #define IODebuggerUnlock IOKernelDebugger::unlock
265:
266: #endif /* !_IOKERNELDEBUGGER_H */
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.