![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to IOSCSICommand_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 IOSCSICommand_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 IOSCSICommand_Reference.h
26:
27: This header defines the IOSCSICommand class.
28:
29: This class encapsulates a SCSI Command. The client driver allocates a
30: command using IOSCSIDevice::allocCommand() and initializes it using
31: functions of this class. The client can then submit the command to
32: the SCSI stack by invoking the execute() function.
33: */
34:
35:
36: /*!
37: @enum SCSICDBFlags
38: Defines values for the cdbFlags field in the SCSICDBInfo structure.
39: @constant kCDBFNoDisconnect
40: Set by the IOSCSIDevice client to indicate the target may not disconnect
41: during the execution of this IOSCSICommand.
42: @constant kCDBFlagsDisableParity
43: Set by the IOSCSIController class to tell the host adapter driver to disable
44: parity checking during the execution of this CDB.
45: @constant kCDBFlagsNoDisconnect
46: Set by the IOSCSIController class to tell the host adapter driver that the
47: target may not disconnect during the execution of this IOSCSICommand.
48: @constant kCDBFlagsNegotiateSDTR
49: Set by the IOSCSIController class to tell the host adapter driver that it
50: should initiate synchronous data transfer negotiation during this IOSCSICommand.
51: @constant kCDBFlagsNegotiateWDTR
52: Set by the IOSCSIController class to tell the host adapter driver that it
53: should initiate wide data transfer negotiation during this IOSCSICommand.
54: */
55: enum SCSICDBFlags {
56: kCDBFNoDisconnect = 0x00000001,
57:
58: /*
59: * Note: These flags are for IOSCSIController subclasses only
60: */
61: kCDBFlagsDisableParity = 0x08000000,
62: kCDBFlagsNoDisconnect = 0x10000000,
63: kCDBFlagsNegotiateSDTR = 0x20000000,
64: kCDBFlagsNegotiateWDTR = 0x40000000,
65: };
66:
67:
68: /*!
69: @enum SCSIAdapterStatus
70: Defines the values of the adapterStatus field of the SCSIResults structure.
71: @constant kSCSIAdapterStatusSuccess
72: Request completed with no adapter reported errors.
73: @constant kSCSIAdapterStatusMsgReject
74: Adapter received a msg reject from the target device.
75: @constant kSCSIAdapterStatusParityError
76: Adapter detected, or target reported a parity error during the
77: IOSCSICommand.
78: */
79: enum SCSIAdapterStatus {
80: kSCSIAdapterStatusSuccess = 0,
81: kSCSIAdapterStatusMsgReject,
82: kSCSIAdapterStatusParityError,
83: };
84:
85:
86: /*!
87: @typedef SCSICDBInfo
88: @discussion
89: Fields specified here are set by IOSCSIDevice client, while others
90: are set by the IOSCSIController class for use by the host adapter
91: driver. The client should zero all fields of the structure prior
92: to use.
93: @field cdbFlags
94: See enum SCSICDBFlags for flag definitions.
95: @field cdbTagMsg
96: This field should be set to zero by the IOSCSIDevice client. If the
97: SCSI device supports tag queuing then the IOSCSIController class
98: will set this field to select simple (unordered) tags.
99: @field cdbTag
100: This field is set by the IOSCSIController class to tell the host
101: adapter driver the SCSI tag value to assign to this IOSCSICommand.
102: @field cdbLength
103: Set by the IOSCSIDevice client to the length of the Command Descriptor
104: Block (CDB).
105: @field cdb
106: Set by the IOSCSIDevice client to command descriptor block the client
107: wishes the target to execute.
108: */
109: typedef struct SCSICDBInfo {
110:
111: UInt32 cdbFlags;
112:
113: UInt32 cdbTagMsg;
114: UInt32 cdbTag;
115:
116: UInt32 cdbAbortMsg;
117:
118: UInt32 cdbLength;
119: UInt8 cdb[16];
120:
121: UInt32 reserved[16];
122: } SCSICDBInfo;
123:
124:
125: /*!
126: @typedef SCSIResults
127: @field returnCode
128: The overall return code for the command. See iokit/iokit/IOReturn.h.
129: This value is also returned as the getResults() return value.
130:
131: Note: The exact subset of return codes a SCSI command will return is
132: currently under review.
133: @field bytesTransferred
134: The total number of bytes transferred to/from the target device.
135: @field adapterStatus
136: This field provides additional adapter reported error information. The SCSI
137: Family uses this information to determine whether the target rejected a
138: negotiation attempt (either/or) wide or synchronous.
139: @field scsiStatus
140: The SCSI Status byte returned from the target device.
141: @field requestSenseDone
142: A boolean indicating whether sense data was obtained from the target
143: device.
144: @field requestSenseLength
145: The number of sense data bytes returned from the target device.
146: */
147: typedef struct SCSIResults {
148: IOReturn returnCode;
149:
150: UInt32 bytesTransferred;
151:
152: UInt32 adapterStatus;
153: UInt8 scsiStatus;
154:
155: bool requestSenseDone;
156: UInt32 requestSenseLength;
157: } SCSIResults;
158:
159:
160: /*!
161: @enum SCSIQueueType
162: Each IOSCSIDevice has two queues, a normal Q and a bypass Q. The treatment of the
163: queues is essentially identical except that the bypass Q is given preference whenever
164: it has commands available.
165:
166: Usually, the client will use the normal Q for regular I/O commands and the bypass Q
167: to send error recovery commands to the device.
168: @constant kQTypeNormalQ
169: Indicates command applies to the normal IOSCSIDevice queue.
170: @constant kQTypeBypassQ
171: Indicates command applies to the bypass IOSCSIDevice queue.
172: */
173: enum SCSIQueueType {
174: kQTypeNormalQ = 0,
175: kQTypeBypassQ = 1,
176: };
177:
178:
179: /*!
180: @enum SCSIQueuePosition
181: Indicates whether a IOSCSICommand should be added to the head or tail
182: of the queue selected.
183: @constant kQPositionTail
184: Queue request at the tail (end) of the selected queue.
185: @constant kQPositionHead
186: Queue request at the head (front) of the selected queue.
187: */
188: enum SCSIQueuePosition {
189: kQPositionTail = 0,
190: kQPositionHead = 1,
191: };
192:
193:
194: /*!
195: @struct SCSITargetLun
196: @field target
197: The SCSI Id for the SCSI device being selected.
198: @field lun
199: The SCSI Lun for the SCSI device being selected.
200: */
201: typedef struct SCSITargetLun {
202: UInt8 target;
203: UInt8 lun;
204: UInt8 reserved[2];
205: } SCSITargetLun;
206:
207: /*!
208: @class IOSCSICommand : public IOCDBCommand
209: @abstract
210: Class that describes a SCSI device (target/lun pair).
211: @discussion
212: This class encapsulates a SCSI Command. The client driver allocates a
213: command using IOSCSIDevice::allocCommand() and initializes it using
214: functions of this class. The client can then submit the command to
215: the SCSI stack by invoking the execute() function.
216: */
217: class IOSCSICommand : public IOCDBCommand
218: {
219: public:
220:
221:
222: /*!
223: @function setPointers
224: @abstract
225: Sets the data buffer component of a SCSI Command.
226: @discussion
227: The client provides an IOMemoryDescriptor object to corresponding
228: to the client's data or request sense buffer, the maximum data transfer count
229: and data transfer direction.
230: @param desc
231: Pointer to a IOMemoryDescriptor describing the client's I/O buffer.
232: @param transferCount
233: Maximum data transfer count in bytes.
234: @param isWrite
235: Data transfer direction. (Defined with respect to the device, i.e. isWrite = true
236: indicates the host is writing to the device.
237: @param isSense
238: If isSense is set to true, the IOSCSICommand's data buffer information is set. Otherwise,
239: the IOSCSICommand's request sense buffer information is set
240: */
241: void setPointers( IOMemoryDescriptor *desc, UInt32 transferCount, bool isWrite, bool isSense=false );
242:
243:
244: /*!
245: @function getPointers
246: @abstract
247: Gets the data buffer component of a SCSI Command.
248: @discussion
249: The client provides a set of pointers to fields to receive the IOSCSICommand's
250: data/request sense buffer pointers.
251: @param desc
252: Pointer to a field (IOMemoryDescriptor *) to receive the IOSCSICommand's IOMemoryDescriptor pointer.
253: @param transferCount
254: Pointer to a field (UInt32) to receive the IOSCSICommand's maximum transfer count.
255: @param isWrite
256: Pointer to a field (bool) to receive the IOSCSICommand's transfer direction.
257: @param isSense
258: If isSense is set to true, the IOSCSICommand's data buffer information is returned. Otherwise,
259: the IOSCSICommand's request sense buffer information is returned.
260: */
261: void getPointers( IOMemoryDescriptor **desc, UInt32 *transferCount, bool *isWrite, bool isSense = false );
262:
263: /*!
264: @function setTimeout
265: @abstract
266: Sets the timeout for the command in milliseconds.
267: @discussion
268: The IOSCSIController class will abort a command which does not
269: complete with in the time interval specified. The client should
270: set the timeout parameter to zero if they want to suppress
271: timing.
272: @param timeout
273: Command timeout in milliseconds.
274: */
275: void setTimeout( UInt32 timeoutmS );
276:
277: /*!
278: @function getTimeout
279: @abstract
280: Gets the timeout for the command in milliseconds.
281: @discussion
282: This function returns the command timeout previously set by setTimeout().
283: @param timeout
284: Command timeout in milliseconds.
285: */
286: UInt32 getTimeout();
287:
288:
289: /*!
290: @function setCallback
291: @abstract
292: Sets the callback routine to be invoked when the SCSI Command completes.
293: @param target
294: Pointer to the object to be passed to the callback routine. This would usually
295: be the client's (this) pointer.
296: @param callback
297: Pointer to the client's function to process the completed command
298: @param refcon
299: Pointer to the information required by the client's callback routine to process
300: the completed command.
301: */
302: void setCallback( void *target = 0, CallbackFn callback = 0, void *refcon = 0 );
303:
304:
305: /*!
306: @function getClientData
307: @abstract
308: Returns a pointer to the SCSI Command's client data area.
309: @discussion
310: The client may allocate storage in the SCSI Command for its own use.
311: See IOSCSIDevice::allocateCmd().
312: */
313: void *getClientData();
314:
315: /*
316: @function getCommandData
317: @abstract
318: Returns a pointer to the SCSI Command's controller data area
319: @discussion
320: This area is allocated for use by the IOSCSIController subclass (host adapter
321: driver). The client should not normally access this area.
322: */
323: void *getCommandData();
324:
325:
326: /*!
327: @function setCDB
328: @abstract
329: Sets the CDB component of a SCSI Command.
330: @param scsiCDB
331: Pointer to a SCSICDBInfo structure.
332: */
333: void setCDB( SCSICDBInfo *scsiCmd );
334:
335:
336: /*!
337: @function getCDB
338: @abstract
339: Gets the CDB component of a SCSI Command.
340: @param scsiCDB
341: Pointer to a SCSICDBInfo structure to receive the SCSI Command's cdb information.
342: */
343: void getCDB( SCSICDBInfo *scsiCmd );
344:
345:
346: /*!
347: @function getResults
348: @abstract
349: Gets results from a completed SCSI Command.
350: @discussion
351: The getResults() function returns the value of the returnCode field of the command results. If
352: the client is only interested in a pass/fail indication for the command, the client
353: can pass (SCSIResult *)0 as a parameter.
354: @param results
355: Pointer to a SCSIResults structure to receive the SCSI Commands completion information.
356: */
357: IOReturn getResults( SCSIResults *results );
358:
359: /*!
360: @function setResults
361: @abstract
362: Sets the results component of a SCSI Command.
363: @discussion
364: The setResults() function is used by the IOSCSIController subclass (host
365: adapter driver) return results for a SCSI Command about to be completed.
366: @param scsiResults Pointer to a SCSIResults structure containing
367: completion information for the SCSI Command.
368:
369: Completion information is copied into the command, so the caller may
370: release the SCSIResults structure provided when this function returns.
371: */
372: void setResults( SCSIResults *results );
373:
374:
375: /*!
376: @function getDevice
377: @abstract
378: Returns the IOSCSIDevice this command is targeted to.
379: @param deviceType
380: The caller should use value kIOSCSIDeviceType.
381: @discussion
382: In some cases a IOSCSICommand is not associated with a specific target/lun. This
383: would be the case for a SCSI Bus Reset. In this case getDevice() returns 0.
384: */
385: IOSCSIDevice *getDevice( IOSCSIDevice *deviceType );
386:
387:
388: /*!
389: @function getTargetLun
390: @abstract
391: Returns the target/lun for the IOSCSIDevice this command is associated with.
392: @param targetLun
393: Pointer to a SCSITargetLun structure to receive the target/lun information.
394: */
395: void getTargetLun( SCSITargetLun *targetLun );
396:
397:
398: /*!
399: @function execute
400: @abstract
401: Submits a SCSI command to be executed.
402: @discussion
403: Once the execute() function is called, the client should not
404: invoke any further functions on the SCSI Command with the
405: exception of abort().
406:
407: The execute() function optionally returns sets a unique sequence
408: number token for the command. If the client intends to use the abort()
409: method they must retain this sequence number token.
410: @param sequenceNumber
411: Pointer to field (UInt32) to receive the sequence number assigned to the SCSI
412: Command.
413: */
414: bool execute( UInt32 *sequenceNumber = 0 );
415:
416: /*!
417: @function abort
418: @abstract
419: Aborts an executing SCSI Command.
420: @discussion
421: The client may invoke the abort() method to force the completion of an
422: executing SCSI Command. The client must pass the sequence number
423: provided when the execute() function was invoked.
424:
425: Note: The abort function provides no status on whether or not a
426: command has been successfully aborted. The client should wait for the
427: command to actually complete to determine whether the abort completed
428: successfully.
429: @param sequenceNumber
430: The client must pass the sequence number assigned to the command when
431: the client called the execute() function.
432: */
433: void abort( UInt32 sequenceNumber );
434:
435: /*!
436: @function complete
437: @abstract
438: Indicates the IOSCSIController subclass (host adapter driver) has completed a SCSI command.
439: @discussion
440: Once the complete() function is called, the controller
441: subclass should make no further accesses to the IOSCSICommand
442: being completed.
443:
444: A IOSCSIDevice client would not normally call this function.
445: */
446: void complete();
447:
448:
449: /*!
450: @function getSequenceNumber
451: @abstract
452: Returns the sequence number assigned to an executing command.
453: @discussion
454: The caller should check the sequence number for 0. This indicates that
455: the command has completed or has not been processed to the point where
456: a sequence number has been assigned.
457: */
458: UInt32 getSequenceNumber();
459:
460:
461: /*!
462: @function setQueueInfo
463: @abstract
464: Sets queuing information for the SCSI Command.
465: @discussion
466: Each IOSCSIDevice has two queues, a normal Q and a bypass Q. The treatment of the
467: queues is esentially identical except that the bypass Q is given preference whenever
468: it has commands available.
469:
470: Usually, the client will use the normal Q for regular I/O commands and the bypass Q
471: to send error recovery commands to the device.
472: @param queueType
473: Set to kQTypeNormalQ or kQTypeBypassQ to indicate which IOSCSIDevice queue the
474: SCSI Command should be routed to.
475: @param queuePosition
476: Set to kQPositionTail or kQPositionHead to indicate whether the SCSI Command should
477: be added to the head to tail for the selected IOSCSIDevice queue.
478: */
479: void setQueueInfo( UInt32 queueType = kQTypeNormalQ, UInt32 queuePosition = kQPositionTail );
480:
481:
482: /*!
483: @function getQueueInfo
484: @abstract
485: Gets queuing information for the SCSI Command.
486: @param queueType
487: Pointer to a field (UInt32) to receive the queue type previously set for this SCSI Command.
488: @param queuePosition
489: Pointer to a field (UInt32) to receive the queue position previously set for this SCSI Command.
490: */
491: void getQueueInfo( UInt32 *queueType, UInt32 *queuePosition = 0 );
492:
493:
494: /*!
495: @function getCmdType
496: @abstract
497: Obtains the underlying 'intent' of a SCSI Command.
498: @discussion
499: This function provides information on the intent of a SCSI
500: Command. For example, since Aborts, Request Sense and normal Execute commands are
501: all sent to the executeCommand() function, invoking getCmdType()
502: will indicate whether a Request Sense, Abort or Normal I/O request is
503: being processed.
504:
505: It this information is not normally meaningful to IOSCSIDevice clients.
506: */
507: UInt32 getCmdType();
508:
509:
510: /*!
511: @function getOriginalCmd
512: @abstract
513: Obtains a 'related' SCSI Command.
514: @discussion
515: In cases where a SCSI command is related to a previous command, this
516: function will return the original command. For example, if a
517: Request Sense command (CmdType = kSCSICommandReqSense)is processed,
518: then this function can be used to obtain the original command that
519: caused the check condition. If an Abort command (CmdType =
520: kSCSICommandAbort) then this function can be used to obtain the original
521: command the abort was issued against.
522:
523:
524: It this information is not normally meaningful to IOSCSIDevice clients.
525: */
526: IOSCSICommand *getOriginalCmd();
527:
528: };
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.