xnu-123.5.tar.gz

[apple/xnu.git] / iokit / IOKit / scsi / IOSCSICommand_Reference.h

/*
 * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * The contents of this file constitute Original Code as defined in and
 * are subject to the Apple Public Source License Version 1.1 (the
 * "License").  You may not use this file except in compliance with the
 * License.  Please obtain a copy of the License at
 * http://www.apple.com/publicsource and read it before using this file.
 * 
 * This Original Code and all software distributed under the License are
 * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
 * License for the specific language governing rights and limitations
 * under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */
 

/*!
@header IOSCSICommand_Reference.h 

This header defines the IOSCSICommand class.

This class encapsulates a SCSI Command. The client driver allocates a
command using IOSCSIDevice::allocCommand() and initializes it using
functions of this class. The client can then submit the command to
the SCSI stack by invoking the execute() function.
*/


/*!
@enum SCSICDBFlags
Defines values for the cdbFlags field in the SCSICDBInfo structure.
@constant kCDBFNoDisconnect
Set by the IOSCSIDevice client to indicate the target may not disconnect
during the execution of this IOSCSICommand.
@constant kCDBFlagsDisableParity
Set by the IOSCSIController class to tell the host adapter driver to disable
parity checking during the execution of this CDB.
@constant kCDBFlagsNoDisconnect
Set by the IOSCSIController class to tell the host adapter driver that the 
target may not disconnect during the execution of this IOSCSICommand.
@constant kCDBFlagsNegotiateSDTR
Set by the IOSCSIController class to tell the host adapter driver that it
should initiate synchronous data transfer negotiation during this IOSCSICommand.
@constant kCDBFlagsNegotiateWDTR
Set by the IOSCSIController class to tell the host adapter driver that it
should initiate wide data transfer negotiation during this IOSCSICommand.
*/
enum SCSICDBFlags {
    kCDBFNoDisconnect		= 0x00000001,

/*
 *  Note: These flags are for IOSCSIController subclasses only
 */
    kCDBFlagsDisableParity	= 0x08000000,
    kCDBFlagsNoDisconnect	= 0x10000000,
    kCDBFlagsNegotiateSDTR	= 0x20000000,
    kCDBFlagsNegotiateWDTR	= 0x40000000,
};


/*!
@enum SCSIAdapterStatus
Defines the values of the adapterStatus field of the SCSIResults structure.
@constant kSCSIAdapterStatusSuccess
Request completed with no adapter reported errors.
@constant kSCSIAdapterStatusProtocolError
Violation of SCSI protocol detected by host adapter.
@constant kSCSIAdapterStatusSelectionTimeout
Target device did not respond to selection.
@constant kSCSIAdapterStatusMsgReject
Adapter received a msg reject from the target device.
@constant kSCSIAdapterStatusParityError
Adapter detected, or target reported a parity error during the
IOSCSICommand.
@constant kSCSIAdapterStatusOverrun
Target device requested more data than supplied by host.
*/
enum SCSIAdapterStatus {
    kSCSIAdapterStatusSuccess	    = 0,
    kSCSIAdapterStatusProtocolError,
    kSCSIAdapterStatusSelectionTimeout,
    kSCSIAdapterStatusMsgReject,
    kSCSIAdapterStatusParityError,
    kSCSIAdapterStatusOverrun,
};


/*!
@typedef SCSICDBInfo
@discussion
Fields specified here are set by IOSCSIDevice client, while others
are set by the IOSCSIController class for use by the host adapter
driver. The client should zero all fields of the structure prior
to use.
@field cdbFlags
See enum SCSICDBFlags for flag definitions.
@field cdbTagMsg 
This field should be set to zero by the IOSCSIDevice client. If the
SCSI device supports tag queuing then the IOSCSIController class
will set this field to select simple (unordered) tags. 
@field cdbTag
This field is set by the IOSCSIController class to tell the host 
adapter driver the SCSI tag value to assign to this IOSCSICommand.
@field cdbLength
Set by the IOSCSIDevice client to the length of the Command Descriptor
Block (CDB).
@field cdb
Set by the IOSCSIDevice client to command descriptor block the client
wishes the target to execute.
*/
typedef struct SCSICDBInfo {
	
    UInt32      cdbFlags;

    UInt32	cdbTagMsg;
    UInt32	cdbTag;

    UInt32	cdbAbortMsg;

    UInt32	cdbLength;
    UInt8	cdb[16];
    
    UInt32	reserved[16];
} SCSICDBInfo;


/*!
@typedef SCSIResults
@field returnCode
The overall return code for the command. See iokit/iokit/IOReturn.h.
This value is also returned as the getResults() return value.

Note: The SCSI Family will automatically generate standard return codes
based on the values in the adapterStatus and scsiStatus fields. Unless 
the IOSCSIController subclass needs set a specific return code, it should
leave this field set to zero.
@field bytesTransferred
The total number of bytes transferred to/from the target device.
@field adapterStatus
The IOSCSIController subclass must fill-in this field as appropriate.
See enum SCSIAdapterStatus. 
@field scsiStatus
The SCSI Status byte returned from the target device.
@field requestSenseDone
A boolean indicating whether sense data was obtained from the target
device.
@field requestSenseLength
The number of sense data bytes returned from the target device.
*/
typedef struct SCSIResults {
    IOReturn			returnCode;
    
    UInt32			bytesTransferred;

    enum SCSIAdapterStatus	adapterStatus;	
    UInt8			scsiStatus;
    
    bool			requestSenseDone;
    UInt32			requestSenseLength;
} SCSIResults;


/*!
@enum SCSIQueueType
Each IOSCSIDevice has two queues, a normal Q and a bypass Q. The treatment of the
queues is essentially identical except that the bypass Q is given preference whenever
it has commands available. 

Usually, the client will use the normal Q for regular I/O commands and the bypass Q
to send error recovery commands to the device.
@constant kQTypeNormalQ
Indicates command applies to the normal IOSCSIDevice queue.
@constant kQTypeBypassQ
Indicates command applies to the bypass IOSCSIDevice queue.
*/
enum SCSIQueueType {
    kQTypeNormalQ	= 0,
    kQTypeBypassQ	= 1,
};


/*!
@enum SCSIQueuePosition
Indicates whether a IOSCSICommand should be added to the head or tail
of the queue selected.
@constant kQPositionTail
Queue request at the tail (end) of the selected queue.
@constant kQPositionHead
Queue request at the head (front) of the selected queue.
*/
enum SCSIQueuePosition {
    kQPositionTail	= 0,
    kQPositionHead	= 1,
};


/*!
@struct SCSITargetLun
@field target
The SCSI Id for the SCSI device being selected.
@field lun
The SCSI Lun for the SCSI device being selected.
*/ 
typedef struct SCSITargetLun {
    UInt8   target;
    UInt8   lun;
    UInt8   reserved[2];
} SCSITargetLun;

/*!
@class IOSCSICommand : public IOCDBCommand
@abstract 
Class that describes a SCSI device (target/lun pair).
@discussion 
This class encapsulates a SCSI Command. The client driver allocates a
command using IOSCSIDevice::allocCommand() and initializes it using
functions of this class. The client can then submit the command to
the SCSI stack by invoking the execute() function.
*/
class IOSCSICommand : public IOCDBCommand
{
public:


/*!
@function setPointers
@abstract
Sets the data buffer component of a SCSI Command.
@discussion
The client provides an IOMemoryDescriptor object to corresponding
to the client's data or request sense buffer, the maximum data transfer count
and data transfer direction.
@param desc
Pointer to a IOMemoryDescriptor describing the client's I/O buffer.
@param transferCount
Maximum data transfer count in bytes.
@param isWrite
Data transfer direction. (Defined with respect to the device, i.e. isWrite = true
indicates the host is writing to the device.
@param isSense
If isSense is set to false, the IOSCSICommand's data buffer information is set. Otherwise,
the IOSCSICommand's request sense buffer information is set
*/
void setPointers( IOMemoryDescriptor *desc, UInt32 transferCount, bool isWrite, bool isSense=false );


/*!
@function getPointers
@abstract
Gets the data buffer component of a SCSI Command.
@discussion
The client provides a set of pointers to fields to receive the IOSCSICommand's
data/request sense buffer pointers.
@param desc
Pointer to a field (IOMemoryDescriptor *) to receive the IOSCSICommand's IOMemoryDescriptor pointer.
@param transferCount
Pointer to a field (UInt32) to receive the IOSCSICommand's maximum transfer count.
@param isWrite 
Pointer to a field (bool) to receive the IOSCSICommand's transfer direction.
@param isSense
If isSense is set to true, the IOSCSICommand's data buffer information is returned. Otherwise,
the IOSCSICommand's request sense buffer information is returned.
*/
void getPointers( IOMemoryDescriptor **desc, UInt32 *transferCount, bool *isWrite, bool isSense = false );

/*!
@function setTimeout
@abstract
Sets the timeout for the command in milliseconds.
@discussion
The IOSCSIController class will abort a command which does not
complete with in the time interval specified. The client should
set the timeout parameter to zero if they want to suppress
timing.
@param timeout
Command timeout in milliseconds.
*/
void setTimeout( UInt32 timeoutmS );	    

/*!
@function getTimeout
@abstract
Gets the timeout for the command in milliseconds.
@discussion
This function returns the command timeout previously set by setTimeout().
@param timeout
Command timeout in milliseconds.
*/
UInt32	    getTimeout();


/*!
@function setCallback
@abstract
Sets the callback routine to be invoked when the SCSI Command completes.
@param target
Pointer to the object to be passed to the callback routine. This would usually
be the client's (this) pointer.
@param callback
Pointer to the client's function to process the completed command
@param refcon
Pointer to the information required by the client's callback routine to process
the completed command.
*/
void setCallback( void *target = 0, CallbackFn callback = 0, void *refcon = 0 );


/*!
@function getClientData
@abstract
Returns a pointer to the SCSI Command's client data area.
@discussion
The client may allocate storage in the SCSI Command for its own use.
See IOSCSIDevice::allocateCmd().
*/
void	    *getClientData();

/*
@function getCommandData
@abstract
Returns a pointer to the SCSI Command's controller data area
@discussion
This area is allocated for use by the IOSCSIController subclass (host adapter
driver). The client should not normally access this area.
*/
void	    *getCommandData();


/*!
@function setCDB
@abstract
Sets the CDB component of a SCSI Command. 
@param scsiCDB
Pointer to a SCSICDBInfo structure.
*/
void setCDB( SCSICDBInfo *scsiCmd );


/*!
@function getCDB
@abstract
Gets the CDB component of a SCSI Command. 
@param scsiCDB
Pointer to a SCSICDBInfo structure to receive the SCSI Command's cdb information.
*/
void getCDB( SCSICDBInfo *scsiCmd );


/*!
@function getResults
@abstract
Gets results from a completed SCSI Command.
@discussion
The getResults() function returns the value of the returnCode field of the command results. If
the client is only interested in a pass/fail indication for the command, the client 
can pass (SCSIResult *)0 as a parameter.
@param results
Pointer to a SCSIResults structure to receive the SCSI Commands completion information.
*/
IOReturn getResults( SCSIResults *results );

/*!
@function setResults
@abstract
Sets the results component of a SCSI Command.
@discussion
The setResults() function is used by the IOSCSIController subclass (host
adapter driver) return results for a SCSI Command about to be completed.
@param scsiResults Pointer to a SCSIResults structure containing
completion information for the SCSI Command.

Completion information is copied into the command, so the caller may
release the SCSIResults structure provided when this function returns.
*/
void setResults( SCSIResults *results );


/*!
@function getDevice
@abstract 
Returns the IOSCSIDevice this command is targeted to.
@param deviceType
The caller should use value kIOSCSIDeviceType.
@discussion
In some cases a IOSCSICommand is not associated with a specific target/lun. This
would be the case for a SCSI Bus Reset. In this case getDevice() returns 0.
*/
IOSCSIDevice *getDevice( IOSCSIDevice *deviceType );


/*!
@function getTargetLun
@abstract 
Returns the target/lun for the IOSCSIDevice this command is associated with.
@param targetLun
Pointer to a SCSITargetLun structure to receive the target/lun information.
*/
void getTargetLun( SCSITargetLun *targetLun );


/*!
@function execute
@abstract 
Submits a SCSI command to be executed.
@discussion
Once the execute() function is called, the client should not
invoke any further functions on the SCSI Command with the
exception of abort().

The execute() function optionally returns sets a unique sequence
number token for the command. If the client intends to use the abort()
method they must retain this sequence number token.
@param sequenceNumber
Pointer to field (UInt32) to receive the sequence number assigned to the SCSI
Command.
*/
bool execute( UInt32 *sequenceNumber = 0 );

/*!
@function abort
@abstract
Aborts an executing SCSI Command.
@discussion
The client may invoke the abort() method to force the completion of an
executing SCSI Command. The client must pass the sequence number
provided when the execute() function was invoked.

Note: The abort function provides no status on whether or not a
command has been successfully aborted. The client should wait for the
command to actually complete to determine whether the abort completed
successfully.
@param sequenceNumber
The client must pass the sequence number assigned to the command when
the client called the execute() function.
*/
void abort( UInt32 sequenceNumber );

/*!
@function complete
@abstract
Indicates the IOSCSIController subclass (host adapter driver) has completed a SCSI command.
@discussion
Once the complete() function is called, the controller
subclass should make no further accesses to the IOSCSICommand
being completed.

A IOSCSIDevice client would not normally call this function.
*/
void complete();


/*!
@function getSequenceNumber
@abstract
Returns the sequence number assigned to an executing command.
@discussion
The caller should check the sequence number for 0. This indicates that
the command has completed or has not been processed to the point where
a sequence number has been assigned.
*/
UInt32 getSequenceNumber();


/*!
@function setQueueInfo
@abstract
Sets queuing information for the SCSI Command.
@discussion
Each IOSCSIDevice has two queues, a normal Q and a bypass Q. The treatment of the
queues is esentially identical except that the bypass Q is given preference whenever
it has commands available. 

Usually, the client will use the normal Q for regular I/O commands and the bypass Q
to send error recovery commands to the device.
@param queueType
Set to kQTypeNormalQ or kQTypeBypassQ to indicate which IOSCSIDevice queue the 
SCSI Command should be routed to.
@param queuePosition
Set to kQPositionTail or kQPositionHead to indicate whether the SCSI Command should
be added to the head to tail for the selected IOSCSIDevice queue.
*/
void setQueueInfo(  UInt32 queueType = kQTypeNormalQ, UInt32 queuePosition = kQPositionTail );


/*!
@function getQueueInfo
@abstract
Gets queuing information for the SCSI Command.
@param queueType
Pointer to a field (UInt32) to receive the queue type previously set for this SCSI Command.
@param queuePosition
Pointer to a field (UInt32) to receive the queue position previously set for this SCSI Command.
*/
void getQueueInfo(  UInt32 *queueType, UInt32 *queuePosition = 0 );


/*!
@function getCmdType
@abstract
Obtains the underlying 'intent' of a SCSI Command.
@discussion
This function provides information on the intent of a SCSI
Command. For example, since Aborts, Request Sense and normal Execute commands are
all sent to the executeCommand() function, invoking getCmdType()
will indicate whether a Request Sense, Abort or Normal I/O request is
being processed.

It this information is not normally meaningful to IOSCSIDevice clients.
*/
UInt32	    getCmdType();


/*!
@function getOriginalCmd
@abstract
Obtains a 'related' SCSI Command.
@discussion
In cases where a SCSI command is related to a previous command, this
function will return the original command. For example, if a
Request Sense command  (CmdType = kSCSICommandReqSense)is processed,
then this function can be used to obtain the original command that
caused the check condition. If an Abort command (CmdType =
kSCSICommandAbort) then this function can be used to obtain the original
command the abort was issued against.


It this information is not normally meaningful to IOSCSIDevice clients.
*/
IOSCSICommand	*getOriginalCmd();    

};