IOSCSIHDDrive



Member Functions

RWCompletion

Abstract: Asynchronous read/write completion routine.
public:

virtual void RWCompletion(struct context *cx);

We implement this function in this class. It is called from the base class when an IO operation completes.


allocateFormatBuffer

Abstract: Create a data buffer to be used for formatting the media.
protected:

virtual IOReturn allocateFormatBuffer(UInt8 **buf,UInt32 *buflen);

If a format buffer is to be used, then "allocateFormatBuffer" and deleteFormatBuffer" must be overridden to manage the buffer. The buffer must be prepared for IO upon return from allocateFormatBuffer. The default implementations of these methods don't allocate a buffer.

Parameters

NameDescription
bufA pointer for the returned buffer pointer.
buflenThe desired length of the buffer, in bytes.

composeFormatBuffer

Abstract: Compose the data in the buffer used for the format command.
protected:

virtual UInt8 composeFormatBuffer(UInt8 *buf,UInt32 buflen);

This method will be called to compose the data in the format buffer.

The default implementation of this method does nothing.

Parameters

NameDescription
bufA pointer to the format data buffer.
buflenThe size of the format data buffer, in bytes.
Result: The return value should be the desired values for the "CmpLst" and Defect List Format bits in the CDB. The default implementation returns zero.

constructDeviceProperties

Abstract: Construct a set of properties about the device.
public:

virtual OSDictionary *constructDeviceProperties(void);

This function creates a set of properties reflecting information about the device.

This function is presently not used.

Result: A pointer to an OSDictionary containing the properties. The caller is responsible for releasing the OSDictionary.

createFormatCdb

Abstract: Create a SCSI CDB for a format operation.
protected:

virtual UInt32 createFormatCdb( UInt64 byteCapacity, /* in */ UInt8 *cdb, /* in */ UInt32 *cdbLength, /* out */ UInt8 buf[], /* in */ UInt32 bufLen, /* in */ UInt32 *maxAutoSenseLength, /* out */ UInt32 *timeoutSeconds); /* out */

Override this to control the cdb created for a format operation. The default implementation creates a 6-byte format command with no data buffer, disconnect allowed, 8-byte autosense, and a 15-minute timeout.

See also: allocateFormatBuffer, deleteFormatBuffer, composeFormatBuffer.

Parameters

NameDescription
byteCapacityThe requested byte capacity to which the media should be formatted. This value should have been previously validated, otherwise the device may return an error.
cdbA pointer to the CDB bytes.
cdbLengthThe length of the CDB in bytes.
blockThe device block to be written.
nblksThe number of blocks to be transferred.
maxAutoSenseLengthThe maximum size of the autosense data, in bytes. A value of zero will disable autosense.
timeoutSecondsThe command timeout in seconds.
Result: The IOSCSICommandOptions returned will be used to issue the command.

createNub

Abstract: Create, init, attach, and register the device nub.
protected:

virtual IOService * createNub(void);

This method calls instantiateNub, then init, attach, and register.

Result: A pointer to the nub or NULL if something failed.

deleteFormatBuffer

Abstract: Delete the data buffer to be used for formatting the media.
protected:

virtual void deleteFormatBuffer(UInt8 *buf,UInt32 buflen);

If a format buffer is to be used, then "allocateFormatBuffer" and deleteFormatBuffer" must be overridden to manage the buffer. The default implementation of this method does nothing.

Parameters

NameDescription
bufA pointer to the buffer to delete.
buflenThe size of the buffer, in bytes.

deviceTypeMatches

Abstract: Determine if device type matches expected type.
public:

virtual bool deviceTypeMatches(UInt8 inqBuf[],UInt32 inqLen);

We implement this function so we can return a match on the hard disk device type.


doAsyncReadWrite

Abstract: Start an asynchronous read or write operation.
public:

virtual IOReturn doAsyncReadWrite(IOMemoryDescriptor *buffer, UInt32 block,UInt32 nblks, gdCompletionFunction action, IOService *target,void *param);

See IOHDDriveNub for details.


doEjectMedia

Abstract: Eject the media.
public:

virtual IOReturn doEjectMedia(void);

See IOHDDriveNub for details.


doFormatMedia

Abstract: Format the media to the specified byte capacity.
public:

virtual IOReturn doFormatMedia(UInt64 byteCapacity);

The default implementation ignores the byteCapacity parameter. See IOHDDriveNub for details.


doGetFormatCapacities

Abstract: Return the allowable formatting byte capacities.
public:

virtual UInt32 doGetFormatCapacities(UInt64 * capacities, UInt32 capacitiesMaxCount) const;

The default implementation of this method returns a value of block size * max block, and a capacities count of 1. See IOHDDriveNub for details.


doLockUnlockMedia

Abstract: Lock or unlock the (removable) media in the drive.
public:

virtual IOReturn doLockUnlockMedia(bool doLock);

This method issues a standard SCSI Prevent/Allow command to lock or unlock the media in the drive. See IOHDDriveNub for details.


doStart

Abstract: Start (spin up) the media.
protected:

virtual IOReturn doStart(void);

This method calls doStartStop.


doStartStop

Abstract: Perform the actual spin up/down command.
protected:

virtual IOReturn doStartStop(bool start,bool loadEject,UInt8 powerCondition);

This method issues a SCSI Start Stop Unit command to start or stop the device. Because the powerCondition value is only for use with SCSI-3 devices, the current implementation ignores powerCondition.

Parameters

NameDescription
startTrue to start (spin-up) the media; False to stop (spin-down) the media.
loadEjectTrue to eject; False to not eject. This parameter is applicable only to a stop operation.
powerConditionThe power condition to which the drive should transition. This is a SCSI-3 capability; it is presently unused.

doStop

Abstract: Stop (spin down) the media.
protected:

virtual IOReturn doStop(void);

This method calls doStartStop.


doSyncReadWrite

Abstract: Perform a synchronous read or write operation.
public:

virtual IOReturn doSyncReadWrite(IOMemoryDescriptor *buffer,UInt32 block,UInt32 nblks);

See IOHDDriveNub for details.


doSynchronizeCache

Abstract: Force data blocks in the drive's buffer to be flushed to the media.
public:

virtual IOReturn doSynchronizeCache(void);

This method issues a SCSI Synchronize Cache command, to ensure that all blocks in the device cache are written to the media. See IOHDDriveNub for details.


getDeviceTypeName

Abstract: Return a character string for the device type.
protected:

virtual const char * getDeviceTypeName(void);

The default implementation of this method returns kDeviceTypeHardDisk.


getEjectPowerState

Abstract: Return the required device power level to determine eject the media.
protected:

virtual UInt32 getEjectPowerState(void); /* default = kElectronicsOn */

The default implementation of this method returns kElectronicsOn.

Result: The return value must be a valid power state value.

getExecuteCDBPowerState

protected:

virtual UInt32 getExecuteCDBPowerState(void); /* default = kAllOn */

Result: The return value must be a valid power state value.

getFormatMediaPowerState

Abstract: Return the required device power level to execute a client CDB.
protected:

virtual UInt32 getFormatMediaPowerState(void); /* default = kAllOn */

The default implementation of this method returns kAllOn.

Result: The return value must be a valid power state value.

getInitialPowerState

Abstract: Report the initial power state of the device.
protected:

virtual unsigned long getInitialPowerState(void); /* default = kAllOn */

The default implementation of this method returns kAllOn, assuming that the drive spindle spins up initially.

Result: The return value must be a valid power state value.

getInquiryPowerState

Abstract: Return the required device power level to execute an Inquiry command.
protected:

virtual UInt32 getInquiryPowerState(void); /* default = kElectronicsOn */

The default implementation of this method returns kElectronicsOn.

Result: The return value must be a valid power state value.

getLockUnlockMediaPowerState

Abstract: Return the required device power level to lock or unlock the media.
protected:

virtual UInt32 getLockUnlockMediaPowerState(void); /* default = kElectronicsOn */

The default implementation of this method returns kElectronicsOn.

Result: The return value must be a valid power state value.

getReadCapacityPowerState

Abstract: Return the required device power level to execute a Read-Capacity command.
protected:

virtual UInt32 getReadCapacityPowerState(void); /* default = kElectronicsOn */

The default implementation of this method returns kElectronicsOn.

Result: The return value must be a valid power state value.

getReadWritePowerState

Abstract: Return the required device power level to execute a Read or Write command.
protected:

virtual UInt32 getReadWritePowerState(void); /* default = kAllOn */

The default implementation of this method returns kAllOn.

Result: The return value must be a valid power state value.

getReportWriteProtectionPowerState

Abstract: Return the required device power level to report media write protection.
protected:

virtual UInt32 getReportWriteProtectionPowerState(void); /* default = kElectronicsOn */

The default implementation of this method returns kElectronicsOn.

Result: The return value must be a valid power state value.

getStartPowerState

Abstract: Return the required device power level to start (spin up) the media.
protected:

virtual UInt32 getStartPowerState(void); /* default = kElectronicsOn */

The default implementation of this method returns kElectronicsOn.

Result: The return value must be a valid power state value.

getStopPowerState

Abstract: Return the required device power level to stop (spin down) the media.
protected:

virtual UInt32 getStopPowerState(void); /* default = kAllOn */

The default implementation of this method returns kAllOn.

Result: The return value must be a valid power state value.

getSynchronizeCachePowerState

Abstract: Return the required device power level to issue a Synchronize-Cache command.
protected:

virtual UInt32 getSynchronizeCachePowerState(void); /* default = kAllOn */

The default implementation of this method returns kAllOn.

Result: The return value must be a valid power state value.

getTestUnitReadyPowerState

Abstract: Return the required device power level to issue a Test Unit Ready command.
protected:

virtual UInt32 getTestUnitReadyPowerState(void); /* default = kElectronicsOn */

The default implementation of this method returns kElectronicsOn.

Result: The return value must be a valid power state value.

initialPowerStateForDomainState

Abstract: Return the initial power state for the device.
protected:

virtual unsigned long initialPowerStateForDomainState( IOPMPowerFlags domainState );

This method is called to obtain the initial power state for the device, by calling getInitialPowerState.

Parameters

NameDescription
domainStatePower domain state flags.
Result: The return value must be a valid power state value.

instantiateNub

Abstract: Create the device nub.
protected:

virtual IOService * instantiateNub(void);

A subclass will override this method to change the type of nub created. A CD driver, for example, will instantiate an IOSCSICDDriveNub instead of the default implementation's IOSCSIHDDriveNub.


maxCapabilityForDomainState

Abstract: Return the maximum power level obtainable for the given state.
protected:

virtual unsigned long maxCapabilityForDomainState( IOPMPowerFlags domainState );

This method is called to obtain the maximum power level obtainable for the given state.

Parameters

NameDescription
domainStatePower domain state flags.
Result: The return value must be a valid power state value.

powerStateDidChangeTo

Abstract: React to a change in power state.
protected:

virtual IOReturn powerStateDidChangeTo( unsigned long, unsigned long stateOrdinal, IOService* );

This method is called when the power state changes. We call restoreElectronicsState if necessary, then call dequeueCommands if we have changed to a state that has power.

Parameters

NameDescription
stateOrdinalThe power level to which we have changed.

powerStateForDomainState

protected:

virtual unsigned long powerStateForDomainState( IOPMPowerFlags domainState );

This method is called to obtain the maximum power level obtainable for the given state.

Parameters

NameDescription
domainStatePower domain state flags.
Result: The return value must be a valid power state value.

powerStateWillChangeTo

Abstract: Prepare for a power state change.
protected:

virtual IOReturn powerStateWillChangeTo( unsigned long, unsigned long stateOrdinal, IOService* );

This method is called when the power state will change. If we are powering-up from kAllOff, we schedule a call to restoreElectronicsState. If, instead, we are powering-down from an "on" state, we schedule a call to saveElectronicsState.

Parameters

NameDescription
stateOrdinalThe power level to which we will change.

powerTickle

protected:

virtual bool powerTickle(UInt32 desiredState);

This method simply "tickles" the Power Management subsystem to ensure that the device transitions to the desired state if necessary.


reportMediaState

Abstract: Report the device's media state.
public:

virtual IOReturn reportMediaState(bool *mediaPresent,bool *changed);

This method reports whether media is present or not, and also whether the media state has changed since the last call to reportMediaState. The default implementation issues a SCSI Test Unit Ready command: depending on the result of that command, the following cases are reported:

1. TUR status == good completion: we report media present and return kIOReturnSuccess.

2. TUR status != good completion, but good autosense returned:

2a: sense key says not ready: we report media not present and return kIOReturnSuccess.

2b: sense key is anything else: we report media not present and return kIOReturnIOError.

3. TUR status != good completion, and no autosense data: we do not set mediaPresent or changedState, and we return whatever result came back from the SCSI operation.


restoreElectronicsState

Abstract: Restore the state of the device electronics when powering-up.
protected:

virtual IOReturn restoreElectronicsState(void);

This method is called just after the device transitions from a powered-off state.

The default implementation of this method does nothing and returns kIOReturnSuccess.


saveElectronicsState

Abstract: Save the state of the device electronics when powering-down.
protected:

virtual IOReturn saveElectronicsState(void);

This method is called just before the device transitions to a powered-off state.

The default implementation of this method does nothing and returns kIOReturnSuccess.


setPowerState

Abstract: Set the power state to the specified state.
protected:

virtual IOReturn setPowerState( unsigned long powerStateOrdinal, IOService* );

This method is called to cause a change in power state. We handle changes to and from kAllOn and kElectronicsOn, which are done by spinning up and down the media.

Parameters

NameDescription
powerStateOrdinalThe power level to which we must change.

start

Abstract: Start the driver.
public:

virtual bool start(IOService * provider);

We override IOBasicSCSI::start so we can initialize Power Management, then we call createNub to create an IOSCSIHDDriveNub.


Member Data

_mediaPresent

protected:
 bool _mediaPresent;

True if media is present; False if media is not present.


_restoreState

protected:
 bool _restoreState; /* true if we must restore after power-up */ };

True if we must restore the device electronics state after a power-up.


_startStopDisabled

protected:
 bool _startStopDisabled;

True if the start/stop commands are disabled due to an error.


© 2000 Apple Computer, Inc. — (Last Updated 2/23/2000)