Return to IOSCSIDevice_Reference.h CVS log

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

Annotation of XNU/iokit/IOKit/scsi/IOSCSIDevice_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 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.