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.
Name Description bytesTransferred Number of bytes transferred in this operation. totalTime Nanoseconds spent performing this operation. latentTime Nanoseconds of latency during this operation. isWrite Indicates whether this operation was a write, otherwise is was a read.
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.
Name Description byteStart Starting byte offset for the data transfer. buffer Buffer for the data transfer. The size of the buffer implies the size of the data transfer. completion Completion routine to call once the data transfer is complete.
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.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.
Name Description byteStart Starting byte offset for the data transfer. buffer Buffer for the data transfer. The size of the buffer implies the size of the data transfer. completion Completion routine to call once the data transfer is complete.
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.
Result: An IOReturn code.
Name Description byteCapacity Number of bytes to format media to.
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.
Result: Actual number of capacity values copied to the buffer, or if no buffer is given, the total number of capacity values available.
Name Description capacities Buffer that will receive the UInt64 capacity values. capacitiesMaxCount Maximum number of capacity values that can be held in the buffer.
protected:
virtual inline UInt64 getMediaBlockSize() const = 0;
Ask the drive about the media's actual block size.
Result: Natural block size, in bytes.public:
virtual IOMediaState getMediaState() const = 0;
Ask the drive about the media's current state.
Result: An IOMediaState value.public:
virtual UInt64 getStatistic(Statistics statistic) const;
Ask the drive to report one of its operating statistics.
Result: Statistic value.
Name Description statistic Statistic index (an IODrive::Statistics index).
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.
Result: Actual number of statistic values copied to the buffer, or if no buffer is given, the total number of statistic values available.
Name Description statistics Buffer that will receive the UInt64 statistic values. statisticsMaxCount Maximum number of statistic values that can be held in the buffer.
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().
Name Description client Client requesting the close. options Options for the close. Set to zero.
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().
Result: Returns true if the client was (or clients were) open, false otherwise.
Name Description client Client to check the open state of. Set to zero to check the open state of all clients.
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().
Result: Returns true if the open was successful, false otherwise.
Name Description client Client requesting the open. options Options for the open. Set to zero. access Access level for the open. Set to kAccessReader or kAccessReaderWriter.
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.
Result: Returns true on success, false otherwise.
Name Description provider This object's provider.
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.
Name Description provider This object's provider.
protected:
virtual void incrementErrors(bool isWrite);
Update the total error count -- used for statistics. * This method's implementation is not typically overidden.
Name Description isWrite Indicates whether this operation was a write, otherwise is was a read.
protected:
virtual void incrementRetries(bool isWrite);
Update the total retry count -- used for statistics. * This method's implementation is not typically overidden.
Name Description isWrite Indicates whether this operation was a write, otherwise is was a read.
public:
virtual bool isMediaEjectable() const = 0;
Ask the drive whether it contains ejectable media.
Result: Returns true if the media is ejectable, false otherwise.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.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.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.
Result: An IOReturn code.
Name Description lock Pass true to lock the media, otherwise pass false to unlock the media.
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.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.
Name Description byteStart Starting byte offset for the data transfer. buffer Buffer for the data transfer. The size of the buffer implies the size of the data transfer. completion Completion routine to call once the data transfer is complete.
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.
Name Description client Client requesting the read. byteStart Starting byte offset for the data transfer. buffer Buffer for the data transfer. The size of the buffer implies the size of the data transfer. completion Completion routine to call once the data transfer is complete.
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.
Name Description client Client requesting the write. byteStart Starting byte offset for the data transfer. buffer Buffer for the data transfer. The size of the buffer implies the size of the data transfer. completion Completion routine to call once the data transfer is complete.
public:enum IOMediaState { kMediaOffline, kMediaOnline, kMediaBusy };
The different states that getMediaState() can report.
Name Description kMediaOffline Media is not available. kMediaOnline Media is available and ready for operations. kMediaBusy Media is available, but not ready for operations.
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.
Name Description kStatisticsReads Number of read operations thus far. kStatisticsSingleBlockReads Number of read operations for a single block thus far. kStatisticsBytesRead Number of bytes read thus far. kStatisticsTotalReadTime Nanoseconds spent performing reads thus far. kStatisticsLatentReadTime Nanoseconds of latency during reads thus far. kStatisticsReadRetries Number of read retries thus far. kStatisticsReadErrors Number of read errors thus far. kStatisticsWrites Number of write operations thus far. kStatisticsSingleBlockWrites Number of write operations for a single block thus far. kStatisticsBytesWritten Number of bytes written thus far. kStatisticsTotalWriteTime Nanoseconds spent performing writes thus far. kStatisticsLatentWriteTime Nanoseconds of latency during writes thus far. kStatisticsWriteRetries Number of write retries thus far. kStatisticsWriteErrors Number of write errors thus far.
© 2000 Apple Computer, Inc. (Last Updated 2/23/2000)