Return to IOSCSICommand_Reference.h CVS log

Up to [Apple XNU] / XNU / iokit / IOKit / scsi

Annotation of XNU/iokit/IOKit/scsi/IOSCSICommand_Reference.h, revision 1.1

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.