IODrive



Member Functions

addToBytesTransferred

protected:

virtual void addToBytesTransferred(UInt64 bytesTransferred, UInt64 totalTime, UInt64 latentTime, bool isWrite);

Update the total number of bytes transferred, the total transfer time, and the total latency time for this drive -- used for statistics. * This method's implementation is not typically overidden.

Parameters

NameDescription
bytesTransferredNumber of bytes transferred in this operation.
totalTimeNanoseconds spent performing this operation.
latentTimeNanoseconds of latency during this operation.
isWriteIndicates whether this operation was a write, otherwise is was a read.

deblockRequest

protected:

virtual void deblockRequest(UInt64 byteStart, IOMemoryDescriptor * buffer, IOStorageCompletion completion);

The deblockRequest method checks to see if the incoming request rests on the media's block boundaries, and if not, deblocks it. Deblocking involves breaking up the request into sub-requests that rest on block boundaries, and performing the appropriate unaligned byte copies from the scratch buffer into into the client's request buffer. * This method is part of a sequence of methods that are called for each read or write request. The first is deblockRequest, which aligns the request at the media's block boundaries; the second is prepareRequest, which prepares the memory involved in the transfer; and the third is executeRequest, which implements the actual transfer from the drive. * This method's implementation is not typically overidden.

Parameters

NameDescription
byteStartStarting byte offset for the data transfer.
bufferBuffer for the data transfer. The size of the buffer implies the size of the data transfer.
completionCompletion routine to call once the data transfer is complete.

ejectMedia

public:

virtual IOReturn ejectMedia() = 0;

Eject the media from the drive. The drive object is responsible for tearing down the child storage objects it created before proceeding with the eject. If the teardown fails, an error should be returned.

Result: An IOReturn code.

executeRequest

protected:

virtual void executeRequest(UInt64 byteStart, IOMemoryDescriptor * buffer, IOStorageCompletion completion) = 0;

Execute the specified storage request. The request is guaranteed to be block-aligned, and to have a memory buffer that is wired, mapped, and is constrained according to the controller's and drive's limits. * This method is part of a sequence of methods that are called for each read or write request. The first is deblockRequest, which aligns the request at the media's block boundaries; the second is prepareRequest, which prepares the buffer involved in the transfer; and the third is executeRequest, which implements the actual transfer from the drive. * When implementing this abstract method, it is important to remember that the buffer must be retained while the asynchronous operation is being processed, as per regular I/O Kit object-passing semantics.

Parameters

NameDescription
byteStartStarting byte offset for the data transfer.
bufferBuffer for the data transfer. The size of the buffer implies the size of the data transfer.
completionCompletion routine to call once the data transfer is complete.

formatMedia

public:

virtual IOReturn formatMedia(UInt64 byteCapacity) = 0;

Format the media in the drive with the specified byte capacity. The drive object is responsible for tearing down the child storage objects and recreating them, if applicable.

Parameters

NameDescription
byteCapacityNumber of bytes to format media to.
Result: An IOReturn code.

getFormatCapacities

public:

virtual UInt32 getFormatCapacities(UInt64 * capacities, UInt32 capacitiesMaxCount) const = 0;

Ask the drive to report the feasible formatting capacities for the inserted media (in bytes). This routine fills the caller's buffer, up to the maximum count specified if the real number of capacities would overflow the buffer. The return value indicates the actual number of capacities copied to the buffer. * If the capacities buffer is not supplied or if the maximum count is zero, the routine returns the proposed count of capacities instead.

Parameters

NameDescription
capacitiesBuffer that will receive the UInt64 capacity values.
capacitiesMaxCountMaximum number of capacity values that can be held in the buffer.
Result: Actual number of capacity values copied to the buffer, or if no buffer is given, the total number of capacity values available.

getMediaBlockSize

protected:

virtual inline UInt64 getMediaBlockSize() const = 0;

Ask the drive about the media's actual block size.

Result: Natural block size, in bytes.

getMediaState

public:

virtual IOMediaState getMediaState() const = 0;

Ask the drive about the media's current state.

Result: An IOMediaState value.

getStatistic

public:

virtual UInt64 getStatistic(Statistics statistic) const;

Ask the drive to report one of its operating statistics.

Parameters

NameDescription
statisticStatistic index (an IODrive::Statistics index).
Result: Statistic value.

getStatistics

public:

virtual UInt32 getStatistics(UInt64 * statistics, UInt32 statisticsMaxCount) const;

Ask the drive to report its operating statistics. The statistics are described by the IODrive::Statistics indices. This routine fills the caller's buffer, up to the maximum count specified if the real number of statistics would overflow the buffer. The return value indicates the actual number of statistics copied to the buffer. * If the statistics buffer is not supplied or if the maximum count is zero, the routine returns the proposed count of statistics instead.

Parameters

NameDescription
statisticsBuffer that will receive the UInt64 statistic values.
statisticsMaxCountMaximum number of statistic values that can be held in the buffer.
Result: Actual number of statistic values copied to the buffer, or if no buffer is given, the total number of statistic values available.

handleClose

protected:

virtual void handleClose(IOService * client, IOOptionBits options);

The handleClose method closes the client's access to this object. * This implementation replaces the IOService definition of handleIsOpen().

Parameters

NameDescription
clientClient requesting the close.
optionsOptions for the close. Set to zero.

handleIsOpen

protected:

virtual bool handleIsOpen(const IOService * client) const;

The handleIsOpen method determines whether the specified client, or any client if none is specificed, presently has an open on this object. * This implementation replaces the IOService definition of handleIsOpen().

Parameters

NameDescription
clientClient to check the open state of. Set to zero to check the open state of all clients.
Result: Returns true if the client was (or clients were) open, false otherwise.

handleOpen

protected:

virtual bool handleOpen(IOService * client, IOOptionBits options, void * access);

The handleOpen method grants or denies permission to access this object to an interested client. The argument is an IOStorageAccess value that specifies the level of access desired -- reader or reader-writer. * This method can be invoked to upgrade or downgrade the access level for an existing client as well. The previous access level will prevail for upgrades that fail, of course. A downgrade should never fail. If the new access level should be the same as the old for a given client, this method will do nothing and return success. In all cases, one, singular close-per-client is expected for all opens-per-client received. * This implementation replaces the IOService definition of handleIsOpen().

Parameters

NameDescription
clientClient requesting the open.
optionsOptions for the open. Set to zero.
accessAccess level for the open. Set to kAccessReader or kAccessReaderWriter.
Result: Returns true if the open was successful, false otherwise.

handleStart

protected:

virtual bool handleStart(IOService * provider) = 0;

Prepare the drive for operation. * This is where a media object needs to be created for fixed media, and optionally for removable media. For removable media, the poller will issue handlePoll() once a second, so the creation of the media object could be delayed until then if you wish. * Note that this method is called from the superclass' start() routine; if this method returns successfully, it should be prepared to accept any of IODrive's abstract methods.

Parameters

NameDescription
providerThis object's provider.
Result: Returns true on success, false otherwise.

handleStop

protected:

virtual void handleStop(IOService * provider) = 0;

Stop the drive. * This is where the driver should clean up its state in preparation for removal from the system. * Note that this method is called from the superclass' stop() routine.

Parameters

NameDescription
providerThis object's provider.

incrementErrors

protected:

virtual void incrementErrors(bool isWrite);

Update the total error count -- used for statistics. * This method's implementation is not typically overidden.

Parameters

NameDescription
isWriteIndicates whether this operation was a write, otherwise is was a read.

incrementRetries

protected:

virtual void incrementRetries(bool isWrite);

Update the total retry count -- used for statistics. * This method's implementation is not typically overidden.

Parameters

NameDescription
isWriteIndicates whether this operation was a write, otherwise is was a read.

isMediaEjectable

public:

virtual bool isMediaEjectable() const = 0;

Ask the drive whether it contains ejectable media.

Result: Returns true if the media is ejectable, false otherwise.

isMediaPollExpensive

public:

virtual bool isMediaPollExpensive() const = 0;

Ask the drive whether it a pollMedia would be an expensive operation, that is, one that requires the drive to spin up or delay for a while.

Result: Returns true if polling the media is expensive, false otherwise.

isMediaPollRequired

public:

virtual bool isMediaPollRequired() const = 0;

Ask the drive whether it requires polling, which is typically required for drives with ejectable media without the ability to asynchronously detect the arrival or departure of the media.

Result: Returns true if polling the media is required, false otherwise.

lockMedia

public:

virtual IOReturn lockMedia(bool lock) = 0;

Lock or unlock the ejectable media in the drive, that is, prevent it from manual ejection or allow its manual ejection.

Parameters

NameDescription
lockPass true to lock the media, otherwise pass false to unlock the media.
Result: An IOReturn code.

pollMedia

public:

virtual IOReturn pollMedia() = 0;

Poll for the presence of media in the drive. The drive object is responsible for tearing down the child storage objects it created should the media have been removed since the last poll, and vice- versa, creating the child storage objects should new media have arrived since the last poll.

Result: An IOReturn code.

prepareRequest

protected:

virtual void prepareRequest(UInt64 byteStart, IOMemoryDescriptor * buffer, IOStorageCompletion completion);

The prepareRequest method prepares the memory involved in the transfer. The memory will be wired down, physically mapped, and broken up based on the controller's and drive's constraints. * This method is part of a sequence of methods that are called for each read or write request. The first is deblockRequest, which aligns the request at the media's block boundaries; the second is prepareRequest, which prepares the buffer involved in the transfer; and the third is executeRequest, which implements the actual transfer from the drive. * This method's implementation is not typically overidden.

Parameters

NameDescription
byteStartStarting byte offset for the data transfer.
bufferBuffer for the data transfer. The size of the buffer implies the size of the data transfer.
completionCompletion routine to call once the data transfer is complete.

read

public:

virtual void read(IOService * client, UInt64 byteStart, IOMemoryDescriptor * buffer, IOStorageCompletion completion);

The read method is the receiving end for all read requests from the storage framework, that is, the child storage objects of this drive. * This method kicks off a sequence of methods which are called for each read or write request. The first is deblockRequest, which aligns the request at the media's block boundaries; the second is prepareRequest, which prepares the buffer involved in the transfer; and the third is executeRequest, which implements the actual transfer from the drive. * This method's implementation is not typically overidden.

Parameters

NameDescription
clientClient requesting the read.
byteStartStarting byte offset for the data transfer.
bufferBuffer for the data transfer. The size of the buffer implies the size of the data transfer.
completionCompletion routine to call once the data transfer is complete.

write

public:

virtual void write(IOService * client, UInt64 byteStart, IOMemoryDescriptor * buffer, IOStorageCompletion completion);

The write method is the receiving end for all write requests from the storage framework, that is, the child storage objects of this drive. * This method kicks off a sequence of methods which are called for each read or write request. The first is deblockRequest, which aligns the request at the media's block boundaries; the second is prepareRequest, which prepares the buffer involved in the transfer; and the third is executeRequest, which implements the actual transfer from the drive. * This method's implementation is not typically overidden.

Parameters

NameDescription
clientClient requesting the write.
byteStartStarting byte offset for the data transfer.
bufferBuffer for the data transfer. The size of the buffer implies the size of the data transfer.
completionCompletion routine to call once the data transfer is complete.

Member Data

IOMediaState

public:
  enum  IOMediaState
  {
  kMediaOffline,
  kMediaOnline,
  kMediaBusy
  };

The different states that getMediaState() can report.

Constants

NameDescription
kMediaOfflineMedia is not available.
kMediaOnlineMedia is available and ready for operations.
kMediaBusyMedia is available, but not ready for operations.

Statistics

public:
  enum  Statistics
  {
  kStatisticsReads,
  kStatisticsSingleBlockReads,
  kStatisticsBytesRead,
  kStatisticsTotalReadTime,
  kStatisticsLatentReadTime,
  kStatisticsReadRetries,
  kStatisticsReadErrors,

  kStatisticsWrites,
  kStatisticsSingleBlockWrites,
  kStatisticsBytesWritten,
  kStatisticsTotalWriteTime,
  kStatisticsLatentWriteTime,
  kStatisticsWriteRetries,
  kStatisticsWriteErrors
  };

Indices for the different statistics that getStatistics() can report.

Constants

NameDescription
kStatisticsReadsNumber of read operations thus far.
kStatisticsSingleBlockReadsNumber of read operations for a single block thus far.
kStatisticsBytesReadNumber of bytes read thus far.
kStatisticsTotalReadTimeNanoseconds spent performing reads thus far.
kStatisticsLatentReadTimeNanoseconds of latency during reads thus far.
kStatisticsReadRetriesNumber of read retries thus far.
kStatisticsReadErrorsNumber of read errors thus far.
kStatisticsWritesNumber of write operations thus far.
kStatisticsSingleBlockWritesNumber of write operations for a single block thus far.
kStatisticsBytesWrittenNumber of bytes written thus far.
kStatisticsTotalWriteTimeNanoseconds spent performing writes thus far.
kStatisticsLatentWriteTimeNanoseconds of latency during writes thus far.
kStatisticsWriteRetriesNumber of write retries thus far.
kStatisticsWriteErrorsNumber of write errors thus far.

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