![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to IOSCSIDevice_Reference.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / XNU / iokit / IOKit / scsi|
Return to IOSCSIDevice_Reference.h CVS log | Up to [Apple XNU] / XNU / iokit / IOKit / scsi |
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:
24: /*!
25: @header IOSCSIDevice_Reference.h
26:
27: This header defines the IOSCSIDevice class.
28:
29: The SCSI framework creates instances of this class to
30: represent each valid SCSI device (target/lun) detected during
31: SCSI bus scanning. When an instance of this class is registered with
32: IOKit, the instance will be presented to clients which
33: 'match' the IOSCSIDevice class.
34: */
35:
36: /*!
37: @typedef SCSITargetParms
38: Parameter structure for get/setTargetParms
39: @field transferPeriodpS
40: Minimum SCSI synchronous transfer period allowed
41: for this target in picoseconds (10E-12). For asynchronous data transfer,
42: set this field to 0.
43: @field transferOffset
44: Maximum SCSI synchronous transfer offset allowed for this target in
45: bytes. For asynchronous data transfer, set this field to 0.
46: @field transferWidth
47: Maximum SCSI bus width in bytes. Note: must be a
48: power of 2.
49: @field enableTagQueuing
50: Setting enableTagQueuing to true enables tag queuing for SCSI Commands
51: issued to the target.
52: @field disableParity
53: Set to (true) to disable parity checking on the
54: SCSI bus for this target.
55: */
56: typedef struct SCSITargetParms {
57: UInt32 transferPeriodpS;
58: UInt32 transferOffset;
59: UInt32 transferWidth;
60:
61: bool enableTagQueuing;
62: bool disableParity;
63:
64: UInt32 reserved[16];
65:
66: } SCSITargetParms;
67:
68:
69: /*!
70: @typedef SCSILunParms
71: Parameter structure for get/setLunParms
72: @field disableDisconnect
73: Setting disableDisconnect to true disables SCSI disconnect for SCSI
74: Commands issued to the target/lun pair.
75: */
76: typedef struct SCSILunParms {
77: bool disableDisconnect;
78:
79: UInt32 reserved[16];
80:
81: } SCSILunParms;
82:
83:
84: /*!
85: @enum SCSIClientMessage
86: @discussion
87: IOSCSIDevice notifies its client of significant 'events' by the IOService::message()
88: api. When possible the client is notified of the event prior to any action taken. The
89: client is responsible for managing the device queue for the IOSCSIDevice
90: via the holdQueue(), releaseQueue(), flushQueue() and notifyIdle() api's. The client is also
91: notified at the end of an 'event' by the corresponding message id with or'd with
92: kClientMsgDone.
93: @constant kClientMsgDeviceAbort
94: A client initiated device abort is beginning.
95: @constant kClientMsgDeviceReset
96: A client initiated device reset is beginning.
97: @constant kClientMsgBusReset
98: An unsolicited bus reset has occurred.
99: @constant kClientMsgDone
100: This constant is or'd with one of the above message ids to indicate the
101: client should complete processing of the corresponding event.
102: */
103: enum SCSIClientMessage {
104: kClientMsgDeviceAbort = 0x00005000,
105: kClientMsgDeviceReset,
106: kClientMsgBusReset,
107:
108: kClientMsgDone = 0x80000000,
109: };
110:
111:
112: /*!
113: @class IOSCSIDevice : public IOCDBDevice
114: @abstract
115: Class that describes a SCSI device (target/lun pair).
116: @discussion
117: The IOSCSIDevice class provides basic services
118: to initialize and supervise a SCSI device. Once the device is
119: initialized, the client will normally use the allocCommand() member
120: function to create IOSCSICommand(s) to send SCSI CDBs to the target/lun.
121: */
122: class IOSCSIDevice : public IOCDBDevice
123: {
124: public:
125:
126: /*!
127: @function allocCommand
128: @abstract
129: Allocates a IOSCSICommand object for this device.
130: @discussion
131: The client uses the allocCommand() member function to allocate IOSCSICommand(s)
132: for a IOSCSIDevice. The client then uses the member functions of
133: the IOSCSICommand to initialize it and send it to the device. A completed IOSCSICommand
134: may be reused for subsequent I/O requests or returned to the SCSI Family.
135: @param scsiDevice
136: Always specify kIOSCSIDevice.
137: @param clientDataSize
138: The client may indicate the size of a per-command data area for its own
139: use.
140:
141: Note: The amount of per-command storage allowed is under review. We
142: anticipate that typical SCSI clients will need not more than 1024 bytes
143: per command.
144: */
145: IOSCSICommand *allocCommand( IOSCSIDevice *scsiDevice, UInt32 clientDataSize = 0 );
146:
147:
148: /*!
149: @function setTargetParms
150: @abstract
151: Sets SCSI parameters that apply to all luns on a SCSI target device.
152: @discussion
153: This function will block until we attempt to set the
154: requested parameters. It may not be called from the device's workloop context.
155:
156: The SCSI Family will serialize accesses to the SCSI
157: target so as not to disrupt commands in progress prior to processing a
158: change of target parameters.
159: @param targetParms
160: Pointer to structure of type SCSITargetParms.
161: */
162: bool setTargetParms( SCSITargetParms *targetParms );
163:
164:
165: /*!
166: @function getTargetParms
167: @abstract
168: Gets the current target parameters.
169: @discussion
170: Returns the parameters currently in effect for the SCSI target.
171: See setTargetParms().
172: @param targetParms
173: Pointer to structure of type SCSITargetParms.
174: */
175: void getTargetParms( SCSITargetParms *targetParms );
176:
177:
178: /*!
179: @function setLunParms
180: @abstract
181: Sets the logical unit parameters for this device.
182: @discussion
183: This function will block until we attempt to set the
184: requested parameters. It may not be called from the device's workloop context.
185:
186: The SCSI Family will serialize accesses to the SCSI
187: target/lun so as not to disrupt commands in progress prior to processing a
188: change of lun parameters.
189: @param lunParms
190: Pointer to structure of type SCSILunParms
191: */
192: bool setLunParms( SCSILunParms *lunParms );
193:
194:
195: /*!
196: @function getLunParms
197: @abstract
198: Gets the current logical unit parameters.
199: @discussion
200: Returns the parameters currently in effect for the SCSI target/lun.
201: @param lunParms
202: Pointer to structure of type SCSITargetParms
203: */
204: void getLunParms( SCSILunParms *lunParms );
205:
206:
207: /*!
208: @function abort
209: @abstract
210: Aborts all outstanding requests for the target/lun pair.
211: @discussion
212: If any I/O requests are currently active for the target/lun, an abort
213: command is sent to the device and any active requests are completed.
214:
215: Prior to abort processing beginning, the client will be notified via:
216:
217: message( kClientMsgDeviceAbort );
218:
219: When abort processing is completed, the client will be notified via:
220:
221: message( kClientMsgDeviceAbort | kClientMsgDone );
222:
223: The client is responsible for managing the pending work queue for
224: the device when an abort request occurs. See holdQueue(), flushQueue(),
225: notifyIdle() functions.
226: */
227: void abort();
228:
229:
230: /*!
231: @function reset
232: @abstract
233: Resets the SCSI target.
234: @discussion
235: Since a SCSI target may have multiple logical units (lun(s)) the
236: reset() function may affect multiple IOSCSIDevice instances. Processing for
237: each lun is similar.
238:
239: Prior to reset processing beginning, the client will be notified via:
240:
241: message( kClientMsgDeviceReset );
242:
243: When reset processing is completed, the client will be notified via:
244:
245: message( kClientMsgDeviceReset | kClientMsgDone );
246:
247: The client is responsible for managing the pending work queue for
248: the device when an abort request occurs. See holdQueue(), flushQueue(),
249: notifyIdle() functions.
250: */
251: void reset();
252:
253:
254: /*!
255: @function getInquiryData
256: @abstract Returns SCSI Inquiry data for the IOSCSIDevice.
257: @discussion
258: Inquiry data returned is from the results of the last SCSI bus probe.
259: @param inquiryBuffer
260: Pointer to a buffer to receive the Inquiry data.
261: @param inquiryBufSize
262: Size of the buffer supplied.
263: @param inquiryDataSize
264: Pointer to a UInt32 to receive the size of the Inquiry data actually
265: returned.
266: */
267: void getInquiryData( void *inquiryBuffer, UInt32 inquiryBufSize, UInt32 *inquiryDataSize );
268:
269:
270: /*!
271: @function message
272: @abstract
273: IOService message function.
274: @discussion
275: IOSCSIDevice notifies its client of significant 'events' by the IOService::message()
276: api. When possible the client is notified of the event prior to any action taken. The
277: client is responsible for managing the device queue for the IOSCSIDevice
278: via the holdQueue(), releaseQueue(), flushQueue() and notifyIdle() api's.
279:
280: Any return codes provided by the client are ignored.
281: @param message-id
282: Message id's for IOSCSIDevice are defined by enum SCSIClientMessage
283: @param provider
284: Pointer to the IOSCSIDevice reporting the event.
285: @param argument
286: Unused.
287: */
288: IOReturn message( UInt32 type, IOService * provider, void * argument = 0 );
289:
290:
291: /*!
292: @function open
293: @abstract
294: IOService open function
295: @discussion
296: A client should open a IOSCSIDevice prior to accessing it. Only one open is allowed
297: per device.
298: @param client
299: Pointer to the IOSCSI device the client is opening.
300: @param options
301: There are currently no options defined by the SCSI Family.
302: @param arg
303: Unused. Omit or specify 0.
304: */
305: bool open( IOService *client, IOOptionBits options = 0, void *arg = 0 );
306:
307:
308: /*!
309: @function close
310: @abstract
311: IOService close function
312: @discussion
313: A client must close a IOSCSIDevice if the client plans no further accesses to it.
314: @param client
315: Pointer to the IOSCSI device the client is closing.
316: @param options
317: There are currently no options defined by the SCSI Family.
318: */
319: void close( IOService *client, IOOptionBits options = 0 );
320:
321:
322: /*!
323: @function holdQueue
324: @abstract
325: Suspends sending additional IOSCSICommands to the target/lun.
326: @discussion
327: holdQueue() may only be called from the IOSCSIDevice workloop. The client
328: is guaranteed to be running in this context during a message() notification.
329:
330: holdQueue() has no effect on commands already passed to the host adapter. One
331: or more commands may complete after the queue is held. See notifyIdle()
332: @param queueType
333: Perform action on the indicated queue. See enum SCSIQueueType in IOSCSICommand.
334: */
335: holdQueue( UInt32 queueType );
336:
337:
338: /*!
339: @function flushQueue
340: @abstract
341: Returns any commands on the IOSCSIDevice's pending work queue.
342: @discussion
343: flushQueue() may only be called from the IOSCSIDevice workloop. This is
344: guaranteed to be the case after a IOSCSICommand completion of after a
345: message() notification.
346:
347: All pending command are completed prior to flushQueue() returning to the caller.
348:
349: flushQueue() has no effect on commands already passed to the host adapter. One
350: or more commands may complete after the queue is flushed. See notifyIdle().
351: @param queueType
352: Perform action on the indicated queue. See enum SCSIQueueType in IOSCSICommand.
353: @param rc
354: The return code of any flushed commands is set to (rc).
355: */
356: void flushQueue( UInt32 queueType, IOReturn rc );
357:
358:
359: /*!
360: @function notifyIdle
361: @abstract
362: Notifies the client when all active commands on a SCSI device have completed.
363: @discussion
364: notifyIdle() may only be called from the IOSCSIDevice workloop. This is guaranteed
365: to be the case after a IOSCSICommand completion of after a message() notification.
366:
367: Only one notifyIdle() call may be active. Any outstanding notifyIdle() calls may
368: be cancelled by calling notifyIdle() with no parameters.
369: @param target
370: Object to receive the notification. Normally the client's (this) pointer.
371: @param callback
372: Pointer to a callback routine of type CallbackFn.
373: @param refcon
374: Pointer to client's private data.
375: */
376: void notifyIdle( void *target, Callback callback, void *refcon );
377:
378:
379: /*!
380: @function releaseQueue
381: @abstract
382: Resumes sending IOSCSICommands to the IOSCSIDevice.
383: @discussion
384: If the device queue was not held, releaseQueue() has no effect.
385:
386: releaseQueue() may only be called from the IOSCSIDevice workloop. This is guaranteed
387: to be the case after a IOSCSICommand completion of after a message() notification.
388: @param queueType
389: Perform action on the indicated queue. See enum SCSIQueueType in IOSCSICommand.
390: */
391: void releaseQueue( UInt32 queueType );
392:
393:
394: /*!
395: @function getWorkLoop
396: @abstract
397: Returns the IOWorkLoop object that services this IOSCSIDevice.
398: */
399: IOWorkloop *getWorkLoop();
400:
401: }
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.