+++ /dev/null
-/*
- * 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 IOBlockStorageDriver
- * @abstract
- * This header contains the IOBlockStorageDriver class definition.
- */
-
-#ifndef _IOBLOCKSTORAGEDRIVER_H
-#define _IOBLOCKSTORAGEDRIVER_H
-
-/*!
- * @defined kIOBlockStorageDriverClass
- * @abstract
- * kIOBlockStorageDriverClass is the name of the IOBlockStorageDriver class.
- * @discussion
- * kIOBlockStorageDriverClass is the name of the IOBlockStorageDriver class.
- */
-
-#define kIOBlockStorageDriverClass "IOBlockStorageDriver"
-
-/*!
- * @defined kIOBlockStorageDriverStatisticsKey
- * @abstract
- * This property holds a table of numeric values describing the driver's
- * operating statistics.
- * @discussion
- * This property holds a table of numeric values describing the driver's
- * operating statistics. The table is an OSDictionary, where each entry
- * describes one given statistic.
- */
-
-#define kIOBlockStorageDriverStatisticsKey "Statistics"
-
-/*!
- * @defined kIOBlockStorageDriverStatisticsBytesReadKey
- * @abstract
- * This property describes the number of bytes read since the block storage
- * driver was instantiated. It is one of the statistic entries listed under
- * the top-level kIOBlockStorageDriverStatisticsKey property table.
- * @discussion
- * This property describes the number of bytes read since the block storage
- * driver was instantiated. It is one of the statistic entries listed under
- * the top-level kIOBlockStorageDriverStatisticsKey property table. It has
- * an OSNumber value.
- */
-
-#define kIOBlockStorageDriverStatisticsBytesReadKey "Bytes (Read)"
-
-/*!
- * @defined kIOBlockStorageDriverStatisticsBytesWrittenKey
- * @abstract
- * This property describes the number of bytes written since the block storage
- * driver was instantiated. It is one of the statistic entries listed under the
- * top-level kIOBlockStorageDriverStatisticsKey property table.
- * @discussion
- * This property describes the number of bytes written since the block storage
- * driver was instantiated. It is one of the statistic entries listed under the
- * top-level kIOBlockStorageDriverStatisticsKey property table. It has an
- * OSNumber value.
- */
-
-#define kIOBlockStorageDriverStatisticsBytesWrittenKey "Bytes (Write)"
-
-/*!
- * @defined kIOBlockStorageDriverStatisticsReadErrorsKey
- * @abstract
- * This property describes the number of read errors encountered since the block
- * storage driver was instantiated. It is one of the statistic entries listed
- * under the top-level kIOBlockStorageDriverStatisticsKey property table.
- * @discussion
- * This property describes the number of read errors encountered since the block
- * storage driver was instantiated. It is one of the statistic entries listed
- * under the top-level kIOBlockStorageDriverStatisticsKey property table. It
- * has an OSNumber value.
- */
-
-#define kIOBlockStorageDriverStatisticsReadErrorsKey "Errors (Read)"
-
-/*!
- * @defined kIOBlockStorageDriverStatisticsWriteErrorsKey
- * @abstract
- * This property describes the number of write errors encountered since the
- * block storage driver was instantiated. It is one of the statistic entries
- * listed under the top-level kIOBlockStorageDriverStatisticsKey property table.
- * @discussion
- * This property describes the number of write errors encountered since the
- * block storage driver was instantiated. It is one of the statistic entries
- * listed under the top-level kIOBlockStorageDriverStatisticsKey property table.
- * It has an OSNumber value.
- */
-
-#define kIOBlockStorageDriverStatisticsWriteErrorsKey "Errors (Write)"
-
-/*!
- * @defined kIOBlockStorageDriverStatisticsLatentReadTimeKey
- * @abstract
- * This property describes the number of nanoseconds of latency during reads
- * since the block storage driver was instantiated. It is one of the statistic
- * entries listed under the top-level kIOBlockStorageDriverStatisticsKey
- * property table.
- * @discussion
- * This property describes the number of nanoseconds of latency during reads
- * since the block storage driver was instantiated. It is one of the statistic
- * entries listed under the top-level kIOBlockStorageDriverStatisticsKey
- * property table. It has an OSNumber value.
- */
-
-#define kIOBlockStorageDriverStatisticsLatentReadTimeKey "Latency Time (Read)"
-
-/*!
- * @defined kIOBlockStorageDriverStatisticsLatentWriteTimeKey
- * @abstract
- * This property describes the number of nanoseconds of latency during writes
- * since the block storage driver was instantiated. It is one of the statistic
- * entries listed under the top-level kIOBlockStorageDriverStatisticsKey
- * property table.
- * @discussion
- * This property describes the number of nanoseconds of latency during writes
- * since the block storage driver was instantiated. It is one of the statistic
- * entries listed under the top-level kIOBlockStorageDriverStatisticsKey
- * property table. It has an OSNumber value.
- */
-
-#define kIOBlockStorageDriverStatisticsLatentWriteTimeKey "Latency Time (Write)"
-
-/*!
- * @defined kIOBlockStorageDriverStatisticsReadsKey
- * @abstract
- * This property describes the number of read operations processed since the
- * block storage driver was instantiated. It is one of the statistic entries
- * listed under the top-level kIOBlockStorageDriverStatisticsKey property table.
- * @discussion
- * This property describes the number of read operations processed since the
- * block storage driver was instantiated. It is one of the statistic entries
- * listed under the top-level kIOBlockStorageDriverStatisticsKey property table.
- * It has an OSNumber value.
- */
-
-#define kIOBlockStorageDriverStatisticsReadsKey "Operations (Read)"
-
-/*!
- * @defined kIOBlockStorageDriverStatisticsWritesKey
- * @abstract
- * This property describes the number of write operations processed since the
- * block storage driver was instantiated. It is one of the statistic entries
- * listed under the top-level kIOBlockStorageDriverStatisticsKey property table.
- * @discussion
- * This property describes the number of write operations processed since the
- * block storage driver was instantiated. It is one of the statistic entries
- * listed under the top-level kIOBlockStorageDriverStatisticsKey property table.
- * It has an OSNumber value.
- */
-
-#define kIOBlockStorageDriverStatisticsWritesKey "Operations (Write)"
-
-/*!
- * @defined kIOBlockStorageDriverStatisticsReadRetriesKey
- * @abstract
- * This property describes the number of read retries required since the block
- * storage driver was instantiated. It is one of the statistic entries listed
- * under the top-level kIOBlockStorageDriverStatisticsKey property table.
- * @discussion
- * This property describes the number of read retries required since the block
- * storage driver was instantiated. It is one of the statistic entries listed
- * under the top-level kIOBlockStorageDriverStatisticsKey property table. It
- * has an OSNumber value.
- */
-
-#define kIOBlockStorageDriverStatisticsReadRetriesKey "Retries (Read)"
-
-/*!
- * @defined kIOBlockStorageDriverStatisticsWriteRetriesKey
- * @abstract
- * This property describes the number of write retries required since the block
- * storage driver was instantiated. It is one of the statistic entries listed
- * under the top-level kIOBlockStorageDriverStatisticsKey property table. It
- * has an OSNumber value.
- * @discussion
- * This property describes the number of write retries required since the block
- * storage driver was instantiated. It is one of the statistic entries listed
- * under the top-level kIOBlockStorageDriverStatisticsKey property table. It
- * has an OSNumber value.
- */
-
-#define kIOBlockStorageDriverStatisticsWriteRetriesKey "Retries (Write)"
-
-/*!
- * @defined kIOBlockStorageDriverStatisticsTotalReadTimeKey
- * @abstract
- * This property describes the number of nanoseconds spent performing reads
- * since the block storage driver was instantiated. It is one of the statistic
- * entries listed under the top-level kIOBlockStorageDriverStatisticsKey
- * property table.
- * @discussion
- * This property describes the number of nanoseconds spent performing reads
- * since the block storage driver was instantiated. It is one of the statistic
- * entries listed under the top-level kIOBlockStorageDriverStatisticsKey
- * property table. It has an OSNumber value.
- */
-
-#define kIOBlockStorageDriverStatisticsTotalReadTimeKey "Total Time (Read)"
-
-/*!
- * @defined kIOBlockStorageDriverStatisticsTotalWriteTimeKey
- * @abstract
- * This property describes the number of nanoseconds spent performing writes
- * since the block storage driver was instantiated. It is one of the statistic
- * entries listed under the top-level kIOBlockStorageDriverStatisticsKey
- * property table.
- * @discussion
- * This property describes the number of nanoseconds spent performing writes
- * since the block storage driver was instantiated. It is one of the statistic
- * entries listed under the top-level kIOBlockStorageDriverStatisticsKey
- * property table. It has an OSNumber value.
- */
-
-#define kIOBlockStorageDriverStatisticsTotalWriteTimeKey "Total Time (Write)"
-
-/*!
- * @enum IOMediaState
- * @discussion
- * The different states that getMediaState() can report.
- * @constant kIOMediaStateOffline
- * Media is not available.
- * @constant kIOMediaStateOnline
- * Media is available and ready for operations.
- * @constant kIOMediaStateBusy
- * Media is available, but not ready for operations.
- */
-
-typedef UInt32 IOMediaState;
-
-#define kIOMediaStateOffline 0
-#define kIOMediaStateOnline 1
-#define kIOMediaStateBusy 2
-
-/*
- * Kernel
- */
-
-#if defined(KERNEL) && defined(__cplusplus)
-
-#include <IOKit/storage/IOBlockStorageDevice.h>
-#include <IOKit/storage/IOMedia.h>
-#include <IOKit/storage/IOStorage.h>
-#include <kern/thread_call.h>
-
-/*!
- * @class IOBlockStorageDriver
- * @abstract
- * The IOBlockStorageDriver class is the common base class for generic block
- * storage drivers. It matches and communicates via an IOBlockStorageDevice
- * interface, and connects to the remainder of the storage framework via the
- * IOStorage protocol.
- * @discussion
- * The IOBlockStorageDriver class is the common base class for generic block
- * storage drivers. It matches and communicates via an IOBlockStorageDevice
- * interface, and connects to the remainder of the storage framework via the
- * IOStorage protocol. It extends the IOStorage protocol by implementing the
- * appropriate open and close semantics, deblocking for unaligned transfers,
- * polling for ejectable media, locking and ejection policies, media object
- * creation and teardown, and statistics gathering and reporting.
- *
- * Block storage drivers are split into two parts: the generic driver handles
- * all generic device issues, independent of the lower-level transport
- * mechanism (e.g. SCSI, ATA, USB, FireWire). All storage operations
- * at the generic driver level are translated into a series of generic
- * device operations. These operations are passed via the IOBlockStorageDevice
- * nub to a transport driver, which implements the appropriate
- * transport-dependent protocol to execute these operations.
- *
- * To determine the write-protect state of a device (or media), for
- * example, the generic driver would issue a call to the
- * Transport Driver's reportWriteProtection method. If this were a SCSI
- * device, its transport driver would issue a Mode Sense command to
- * extract the write-protection status bit. The transport driver then
- * reports true or false to the generic driver.
- *
- * The generic driver therefore has no knowledge of, or involvement
- * with, the actual commands and mechanisms used to communicate with
- * the device. It is expected that the generic driver will rarely, if
- * ever, need to be subclassed to handle device idiosyncrasies; rather,
- * the transport driver should be changed via overrides.
- *
- * A generic driver could be subclassed to create a different type of
- * generic device. The generic driver IOCDBlockStorageDriver class is
- * a subclass of IOBlockStorageDriver, adding CD functions.
- */
-
-class IOBlockStorageDriver : public IOStorage
-{
- OSDeclareDefaultStructors(IOBlockStorageDriver);
-
-public:
-
- /*!
- * @enum Statistics
- * @discussion
- * Indices for the different statistics that getStatistics() can report.
- * @constant kStatisticsReads
- * Number of read operations thus far.
- * @constant kStatisticsBytesRead
- * Number of bytes read thus far.
- * @constant kStatisticsTotalReadTime
- * Nanoseconds spent performing reads thus far.
- * @constant kStatisticsLatentReadTime
- * Nanoseconds of latency during reads thus far.
- * @constant kStatisticsReadRetries
- * Number of read retries thus far.
- * @constant kStatisticsReadErrors
- * Number of read errors thus far.
- * @constant kStatisticsWrites
- * Number of write operations thus far.
- * @constant kStatisticsSingleBlockWrites
- * Number of write operations for a single block thus far.
- * @constant kStatisticsBytesWritten
- * Number of bytes written thus far.
- * @constant kStatisticsTotalWriteTime
- * Nanoseconds spent performing writes thus far.
- * @constant kStatisticsLatentWriteTime
- * Nanoseconds of latency during writes thus far.
- * @constant kStatisticsWriteRetries
- * Number of write retries thus far.
- * @constant kStatisticsWriteErrors
- * Number of write errors thus far.
- */
-
- enum Statistics
- {
- kStatisticsReads,
- kStatisticsBytesRead,
- kStatisticsTotalReadTime,
- kStatisticsLatentReadTime,
- kStatisticsReadRetries,
- kStatisticsReadErrors,
-
- kStatisticsWrites,
- kStatisticsSingleBlockWrites,
- kStatisticsBytesWritten,
- kStatisticsTotalWriteTime,
- kStatisticsLatentWriteTime,
- kStatisticsWriteRetries,
- kStatisticsWriteErrors
- };
-
- static const UInt32 kStatisticsCount = kStatisticsWriteErrors + 1;
-
-protected:
-
- struct ExpansionData { /* */ };
- ExpansionData * _expansionData;
-
- OSSet * _openClients;
- OSNumber * _statistics[kStatisticsCount];
-
- /*
- * @struct Context
- * @discussion
- * Context structure for a read/write operation. It describes the block size,
- * and where applicable, a block type and block sub-type, for a data transfer,
- * as well as the completion information for the original request. Note that
- * the block type field is unused in the IOBlockStorageDriver class.
- * @field block.size
- * Block size for the operation.
- * @field block.type
- * Block type for the operation. Unused in IOBlockStorageDriver. The default
- * value for this field is IOBlockStorageDriver::kBlockTypeStandard.
- * @field block.typeSub
- * Block sub-type for the operation. It's definition depends on block.type.
- * Unused in IOBlockStorageDriver.
- * @field original.byteStart
- * Starting byte offset for the data transfer.
- * @param original.buffer
- * Buffer for the data transfer. The size of the buffer implies the size of
- * the data transfer.
- * @param original.completion
- * Completion routine to call once the data transfer is complete.
- */
-
- struct Context
- {
- struct
- {
- UInt32 size;
- UInt8 type;
- UInt8 typeSub[3];
- } block;
-
- struct
- {
- UInt64 byteStart;
- IOMemoryDescriptor * buffer;
- IOStorageCompletion completion;
- } original;
-
- UInt32 reserved[8];
- };
-
- static const UInt8 kBlockTypeStandard = 0x00;
-
- /*
- * Free all of this object's outstanding resources.
- *
- * This method's implementation is not typically overidden.
- */
-
- void free();
-
- /*!
- * @function handleOpen
- * @discussion
- * 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().
- * @param client
- * Client requesting the open.
- * @param options
- * Options for the open. Set to zero.
- * @param access
- * Access level for the open. Set to kIOStorageAccessReader or
- * kIOStorageAccessReaderWriter.
- * @result
- * Returns true if the open was successful, false otherwise.
- */
-
- virtual bool handleOpen(IOService * client,
- IOOptionBits options,
- void * access);
-
- /*!
- * @function handleIsOpen
- * @discussion
- * 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().
- * @param client
- * Client 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.
- */
-
- virtual bool handleIsOpen(const IOService * client) const;
-
- /*!
- * @function handleClose
- * @discussion
- * The handleClose method closes the client's access to this object.
- *
- * This implementation replaces the IOService definition of handleIsOpen().
- * @param client
- * Client requesting the close.
- * @param options
- * Options for the close. Set to zero.
- */
-
- virtual void handleClose(IOService * client, IOOptionBits options);
-
- /*!
- * @function addToBytesTransferred
- * @discussion
- * Update the total number of bytes transferred, the total transfer time,
- * and the total latency time -- used for statistics.
- *
- * This method's implementation is not typically overidden.
- * @param bytesTransferred
- * Number of bytes transferred in this operation.
- * @param totalTime
- * Nanoseconds spent performing this operation.
- * @param latentTime
- * Nanoseconds of latency during this operation.
- * @param isWrite
- * Indicates whether this operation was a write, otherwise is was a read.
- */
-
- virtual void addToBytesTransferred(UInt64 bytesTransferred,
- UInt64 totalTime,
- UInt64 latentTime,
- bool isWrite);
-
- /*!
- * @function incrementErrors
- * @discussion
- * Update the total error count -- used for statistics.
- *
- * This method's implementation is not typically overidden.
- * @param isWrite
- * Indicates whether this operation was a write, otherwise is was a read.
- */
-
- virtual void incrementErrors(bool isWrite);
-
- /*!
- * @function incrementRetries
- * @discussion
- * Update the total retry count -- used for statistics.
- *
- * This method's implementation is not typically overidden.
- * @param isWrite
- * Indicates whether this operation was a write, otherwise is was a read.
- */
-
- virtual void incrementRetries(bool isWrite);
-
- /*!
- * @function allocateContext
- * @discussion
- * Allocate a context structure for a read/write operation.
- * @result
- * Context structure.
- */
-
- virtual Context * allocateContext();
-
- /*!
- * @function deleteContext
- * @discussion
- * Delete a context structure from a read/write operation.
- * @param context
- * Context structure to be deleted.
- */
-
- virtual void deleteContext(Context * context);
-
- /*!
- * @function prepareRequest
- * @discussion
- * The prepareRequest method allocates and prepares state for the transfer.
- *
- * This method is part of a sequence of methods invoked for each read/write
- * request. The first is prepareRequest, which allocates and prepares some
- * context for the transfer; the second is deblockRequest, which aligns the
- * transfer at the media block boundaries; and the third is executeRequest,
- * which implements the actual transfer from the block storage device.
- *
- * This method's implementation is not typically overidden.
- * @param byteStart
- * Starting byte offset for the data transfer.
- * @param buffer
- * Buffer for the data transfer. The size of the buffer implies the size of
- * the data transfer.
- * @param completion
- * Completion routine to call once the data transfer is complete.
- */
-
- virtual void prepareRequest(UInt64 byteStart,
- IOMemoryDescriptor * buffer,
- IOStorageCompletion completion);
-
- /*!
- * @function deblockRequest
- * @discussion
- * The deblockRequest method checks to see if the incoming request rests
- * on the media's block boundaries, and if not, deblocks it. Deblocking
- * involves rounding out the request to the nearest block boundaries and
- * transferring the excess bytes into a scratch buffer.
- *
- * This method is part of a sequence of methods invoked for each read/write
- * request. The first is prepareRequest, which allocates and prepares some
- * context for the transfer; the second is deblockRequest, which aligns the
- * transfer at the media block boundaries; and the third is executeRequest,
- * which implements the actual transfer from the block storage device.
- *
- * This method's implementation is not typically overidden.
- * @param byteStart
- * Starting byte offset for the data transfer.
- * @param buffer
- * Buffer for the data transfer. The size of the buffer implies the size of
- * the data transfer.
- * @param completion
- * Completion routine to call once the data transfer is complete.
- * @param context
- * Additional context information for the data transfer (eg. block size).
- */
-
- virtual void deblockRequest(UInt64 byteStart,
- IOMemoryDescriptor * buffer,
- IOStorageCompletion completion,
- Context * context);
-
- /*!
- * @function executeRequest
- * @discussion
- * Execute an asynchrnous storage request. The request is guaranteed to be
- * block-aligned.
- *
- * This method is part of a sequence of methods invoked for each read/write
- * request. The first is prepareRequest, which allocates and prepares some
- * context for the transfer; the second is deblockRequest, which aligns the
- * transfer at the media block boundaries; and the third is executeRequest,
- * which implements the actual transfer from the block storage device.
- * @param byteStart
- * Starting byte offset for the data transfer.
- * @param buffer
- * Buffer for the data transfer. The size of the buffer implies the size of
- * the data transfer.
- * @param completion
- * Completion routine to call once the data transfer is complete.
- * @param context
- * Additional context information for the data transfer (eg. block size).
- */
-
- virtual void executeRequest(UInt64 byteStart,
- IOMemoryDescriptor * buffer,
- IOStorageCompletion completion,
- Context * context);
-
- /*!
- * @function handleStart
- * @discussion
- * Prepare the block storage driver for operation.
- *
- * This is where a media object needs to be created for fixed media, and
- * optionally for removable media.
- *
- * Note that this method is called from within the start() routine;
- * if this method returns successfully, it should be prepared to accept
- * any of IOBlockStorageDriver's APIs.
- * @param provider
- * This object's provider.
- * @result
- * Returns true on success, false otherwise.
- */
-
- virtual bool handleStart(IOService * provider);
-
- /*!
- * @function handleYield
- * @discussion
- * Stop the block storage driver.
- *
- * This method is called as a result of the kIOMessageServiceIsTerminated
- * or kIOMessageServiceIsRequestingClose provider messages. The argument
- * is passed in as-is from the message. The kIOServiceRequired option is
- * set for the kIOMessageServiceIsTerminated message to indicate that the
- * yield must succeed.
- *
- * This is where the driver should clean up its state in preparation for
- * removal from the system. This implementation issues a synchronize cache
- * operation, if the media is writable, and then ejects the media.
- *
- * Note that this method is called from within the yield() routine.
- *
- * This method is called with the arbitration lock held.
- * @param provider
- * This object's provider.
- */
-
- virtual bool handleYield(IOService * provider,
- IOOptionBits options = 0,
- void * argument = 0);
-
-
- /*!
- * @function getMediaBlockSize
- * @discussion
- * Ask the driver about the media's natural block size.
- * @result
- * Natural block size, in bytes.
- */
-
- virtual UInt64 getMediaBlockSize() const;
-
-public:
-
-///m:2333367:workaround:commented:start
-// using read;
-// using write;
-///m:2333367:workaround:commented:stop
-
- /*
- * Initialize this object's minimal state.
- *
- * This method's implementation is not typically overidden.
- */
-
- virtual bool init(OSDictionary * properties = 0);
-
- /*
- * This method is called once we have been attached to the provider object.
- *
- * This method's implementation is not typically overidden.
- */
-
- virtual bool start(IOService * provider);
-
- /*
- * This method is called as a result of the kIOMessageServiceIsTerminated
- * or kIOMessageServiceIsRequestingClose provider messages. The argument
- * is passed in as-is from the message. The kIOServiceRequired option is
- * set for the kIOMessageServiceIsTerminated message to indicate that the
- * yield must succeed.
- *
- * This method is called with the arbitration lock held.
- *
- * This method's implementation is not typically overidden.
- */
-
- virtual bool yield(IOService * provider,
- IOOptionBits options = 0,
- void * argument = 0);
-
- /*!
- * @function read
- * @discussion
- * The read method is the receiving end for all read requests from the
- * storage framework (through the media object created by this driver).
- *
- * This method kicks off a sequence of three methods for each read or write
- * request. The first is prepareRequest, which allocates and prepares some
- * context for the transfer; the second is deblockRequest, which aligns the
- * transfer at the media block boundaries; and the third is executeRequest,
- * which implements the actual transfer from the block storage device.
- *
- * This method's implementation is not typically overidden.
- * @param client
- * Client requesting the read.
- * @param byteStart
- * Starting byte offset for the data transfer.
- * @param buffer
- * Buffer for the data transfer. The size of the buffer implies the size of
- * the data transfer.
- * @param completion
- * Completion routine to call once the data transfer is complete.
- */
-
- virtual void read(IOService * client,
- UInt64 byteStart,
- IOMemoryDescriptor * buffer,
- IOStorageCompletion completion);
-
- /*!
- * @function write
- * @discussion
- * The write method is the receiving end for all write requests from the
- * storage framework (through the media object created by this driver).
- *
- * This method kicks off a sequence of three methods for each read or write
- * request. The first is prepareRequest, which allocates and prepares some
- * context for the transfer; the second is deblockRequest, which aligns the
- * transfer at the media block boundaries; and the third is executeRequest,
- * which implements the actual transfer from the block storage device.
- *
- * This method's implementation is not typically overidden.
- * @param client
- * Client requesting the write.
- * @param byteStart
- * Starting byte offset for the data transfer.
- * @param buffer
- * Buffer for the data transfer. The size of the buffer implies the size of
- * the data transfer.
- * @param completion
- * Completion routine to call once the data transfer is complete.
- */
-
- virtual void write(IOService * client,
- UInt64 byteStart,
- IOMemoryDescriptor * buffer,
- IOStorageCompletion completion);
-
- virtual IOReturn synchronizeCache(IOService * client);
-
- /*!
- * @function ejectMedia
- * @discussion
- * Eject the media from the device. The driver is responsible for tearing
- * down the media object it created before proceeding with the eject. If
- * the teardown fails, an error should be returned.
- * @result
- * An IOReturn code.
- */
-
- virtual IOReturn ejectMedia();
-
- /*!
- * @function formatMedia
- * @discussion
- * Format the media with the specified byte capacity. The driver is
- * responsible for tearing down the media object and recreating it.
- * @param byteCapacity
- * Number of bytes to format media to.
- * @result
- * An IOReturn code.
- */
-
- virtual IOReturn formatMedia(UInt64 byteCapacity);
-
- /*!
- * @function lockMedia
- * @discussion
- * Lock or unlock the ejectable media in the device, that is, prevent
- * it from manual ejection or allow its manual ejection.
- * @param lock
- * Pass true to lock the media, otherwise pass false to unlock the media.
- * @result
- * An IOReturn code.
- */
-
- virtual IOReturn lockMedia(bool lock);
-
- /*!
- * @function pollMedia
- * @discussion
- * Poll for the presence of media in the device. The driver is responsible
- * for tearing down the media object it created should the media have been
- * removed since the last poll, and vice-versa, creating the media object
- * should new media have arrived since the last poll.
- * @result
- * An IOReturn code.
- */
-
- virtual IOReturn pollMedia();
-
- /*!
- * @function isMediaEjectable
- * @discussion
- * Ask the driver whether the media is ejectable.
- * @result
- * Returns true if the media is ejectable, false otherwise.
- */
-
- virtual bool isMediaEjectable() const;
-
- /*!
- * @function isMediaPollExpensive
- * @discussion
- * Ask the driver whether a pollMedia() would be an expensive operation,
- * that is, one that requires the device to spin up or delay for a while.
- * @result
- * Returns true if polling the media is expensive, false otherwise.
- */
-
- virtual bool isMediaPollExpensive() const;
-
- /*!
- * @function isMediaPollRequired
- * @discussion
- * Ask the driver whether the block storage device requires polling, which is
- * typically required for devices without the ability to asynchronously detect
- * the arrival or departure of the media.
- * @result
- * Returns true if polling the media is required, false otherwise.
- */
-
- virtual bool isMediaPollRequired() const;
-
- virtual bool isMediaWritable() const;
-
- /*!
- * @function getMediaState
- * @discussion
- * Ask the driver about the media's current state.
- * @result
- * An IOMediaState value.
- */
-
- virtual IOMediaState getMediaState() const;
-
- /*!
- * @function getFormatCapacities
- * @discussion
- * Ask the driver 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.
- * @param capacities
- * Buffer that will receive the UInt64 capacity values.
- * @param capacitiesMaxCount
- * Maximum 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.
- */
-
- virtual UInt32 getFormatCapacities(UInt64 * capacities,
- UInt32 capacitiesMaxCount) const;
-
- /*!
- * @function getStatistics
- * @discussion
- * Ask the driver to report its operating statistics.
- *
- * The statistics are each indexed by IOBlockStorageDriver::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.
- * @param statistics
- * Buffer that will receive the UInt64 statistic values.
- * @param statisticsMaxCount
- * Maximum 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.
- */
-
- virtual UInt32 getStatistics(UInt64 * statistics,
- UInt32 statisticsMaxCount) const;
-
- /*!
- * @function getStatistic
- * @discussion
- * Ask the driver to report one of its operating statistics.
- * @param statistic
- * Statistic index (an IOBlockStorageDriver::Statistics index).
- * @result
- * Statistic value.
- */
-
- virtual UInt64 getStatistic(Statistics statistic) const;
-
- /*
- * Generic entry point for calls from the provider. A return value of
- * kIOReturnSuccess indicates that the message was received, and where
- * applicable, that it was successful.
- */
-
- virtual IOReturn message(UInt32 type, IOService * provider, void * argument);
-
- /*
- * Obtain this object's provider. We override the superclass's method to
- * return a more specific subclass of IOService -- IOBlockStorageDevice.
- * This method serves simply as a convenience to subclass developers.
- */
-
- virtual IOBlockStorageDevice * getProvider() const;
-
-protected:
-
- IOLock * _deblockRequestWriteLock;
- thread_call_t _pollerCall;
-
- /*
- * This is the completion routine for the aligned deblocker subrequests.
- * It verifies the success of the just-completed stage, transitions to
- * the next stage, then builds and issues a transfer for the next stage.
- */
-
- static void deblockRequestCompletion(void * target,
- void * parameter,
- IOReturn status,
- UInt64 actualByteCount);
-
- /*
- * This is the completion routine for the prepared request. It updates
- * the driver's statistics, performs some clean up work, then calls the
- * original request's completion routine.
- */
-
- static void prepareRequestCompletion(void * target,
- void * parameter,
- IOReturn status,
- UInt64 actualByteCount);
-
- /*
- * Schedule the poller mechanism.
- */
-
- virtual void schedulePoller();
-
- /*
- * Unschedule the poller mechanism.
- */
-
- virtual void unschedulePoller();
-
- /*
- * This method is the timeout handler for the poller mechanism. It polls
- * for media and reschedules another timeout if there are still no opens.
- */
-
- static void poller(void *, void *);
-
-protected:
-
- /* Device info: */
-
- /*!
- * @var _removable
- * True if the media is removable; False if it is fixed (not removable).
- */
- bool _removable;
-
- /*!
- * @var _ejectable
- * True if the media is ejectable under software control.
- */
- bool _ejectable; /* software-ejectable */
-
- /*!
- * @var _lockable
- * True if the media can be locked in the device under software control.
- */
- bool _lockable; /* software lockable in device */
- /*!
- * @var _pollIsRequired
- * True if we must poll to detect media insertion or removal.
- */
- bool _pollIsRequired;
- /*!
- * @var _pollIsExpensive
- * True if polling is expensive; False if not.
- */
- bool _pollIsExpensive;
-
- /* Media info and states: */
-
- /*!
- * @var _mediaObject
- * A pointer to the media object we have instantiated (if any).
- */
- IOMedia * _mediaObject;
- /*!
- * @var _mediaType
- * Type of the media (can be used to differentiate between the
- * different types of CD media, DVD media, etc).
- */
- UInt32 _mediaType;
- /*!
- * @var _mediaPresent
- * True if media is present in the device; False if not.
- */
- bool _mediaPresent; /* media is present and ready */
- /*!
- * @var _writeProtected
- * True if the media is write-protected; False if not.
- */
- bool _writeProtected;
-
-private:
-
- /*!
- * @var _mediaStateLock
- * A lock used to protect during media checks.
- */
- IOLock * _mediaStateLock;
-
-protected:
-
- /*!
- * @var _mediaBlockSize
- * The block size of the media, in bytes.
- */
- UInt64 _mediaBlockSize;
- /*!
- * @var _maxBlockNumber
- * The maximum allowable block number for the media, zero-based.
- */
- UInt64 _maxBlockNumber;
-
- /*!
- * @var _maxReadByteTransfer
- * The maximum byte transfer allowed for read operations.
- */
- UInt64 _maxReadByteTransfer;
-
- /*!
- * @var _maxWriteByteTransfer
- * The maximum byte transfer allowed for write operations.
- */
- UInt64 _maxWriteByteTransfer;
-
- /*!
- * @function acceptNewMedia
- * @abstract
- * React to new media insertion.
- * @discussion
- * This method logs the media block size and block count, then calls
- * instantiateMediaObject to get a media object instantiated. The
- * media object is then attached above us and registered.
- *
- * This method can be overridden to control what happens when new media
- * is inserted. The default implementation deals with one IOMedia object.
- */
- virtual IOReturn acceptNewMedia(void);
-
- /*!
- * @function constrainByteCount
- * @abstract
- * Constrain the byte count for this IO to device limits.
- * @discussion
- * This function should be called prior to each read or write operation, so that
- * the driver can constrain the requested byte count, as necessary, to meet
- * current device limits. Such limits could be imposed by the device depending
- * on operating modes, media types, or transport prototol (e.g. ATA, SCSI).
- *
- * At present, this method is not used.
- * @param requestedCount
- * The requested byte count for the next read or write operation.
- * @param isWrite
- * True if the operation will be a write; False if the operation will be a read.
- */
- virtual UInt64 constrainByteCount(UInt64 requestedCount,bool isWrite);
-
- /*!
- * @function decommissionMedia
- * @abstract
- * Decommission an existing piece of media that has gone away.
- * @discussion
- * This method wraps a call to terminate, to tear down the stack and
- * the IOMedia object for the media. If "forcible" is true, the media
- * object will be forgotten, and initMediaState will be called. A
- * forcible decommission would occur when an unrecoverable error
- * happens during teardown (e.g. perhaps a client is still open), but
- * we must still forget about the media.
- * @param forcible
- * True to force forgetting of the media object even if terminate reports
- * that there was an active client.
- */
- virtual IOReturn decommissionMedia(bool forcible);
-
- /*!
- * @function instantiateDesiredMediaObject
- * @abstract
- * Create an IOMedia object for media.
- * @discussion
- * This method creates the exact type of IOMedia object desired. It is called by
- * instantiateMediaObject. A subclass may override this one-line method to change
- * the type of media object actually instantiated.
- */
- virtual IOMedia * instantiateDesiredMediaObject(void);
-
- /*!
- * @function instantiateMediaObject
- * @abstract
- * Create an IOMedia object for media.
- * @discussion
- * This method creates an IOMedia object from the supplied parameters. It is a
- * convenience method to wrap the handful of steps to do the job.
- * @param base
- * Byte number of beginning of active data area of the media. Usually zero.
- * @param byteSize
- * Size of the data area of the media, in bytes.
- * @param blockSize
- * Block size of the media, in bytes.
- * @param mediaName
- * Name of the IOMedia object.
- * @result
- * A pointer to the created IOMedia object, or a null on error.
- */
- virtual IOMedia * instantiateMediaObject(UInt64 base,UInt64 byteSize,
- UInt32 blockSize,char *mediaName);
-
- /*!
- * @function recordMediaParameters
- * @abstract
- * Obtain media-related parameters on media insertion.
- * @discussion
- * This method obtains media-related parameters via calls to the
- * Transport Driver's reportBlockSize, reportMaxValidBlock,
- * reportMaxReadTransfer, reportMaxWriteTransfer, and reportWriteProtection
- * methods.
- */
- virtual IOReturn recordMediaParameters(void);
-
- /*!
- * @function rejectMedia
- * @abstract
- * Reject new media.
- * @discussion
- * This method will be called if validateNewMedia returns False (thus rejecting
- * the new media. A vendor may choose to override this method to control behavior
- * when media is rejected.
- *
- * The default implementation simply calls ejectMedia.
- */
- virtual void rejectMedia(void); /* default ejects */
-
- /*!
- * @function validateNewMedia
- * @abstract
- * Verify that new media is acceptable.
- * @discussion
- * This method will be called whenever new media is detected. Return true to accept
- * the media, or false to reject it (andcall rejectMedia). Vendors might override
- * this method to handle password-protection for new media.
- *
- * The default implementation always returns True, indicating media is accepted.
- */
- virtual bool validateNewMedia(void);
-
- /* --- Internally used methods. --- */
-
- /*
- * @group
- * Internally Used Methods
- * @discussion
- * These methods are used internally, and will not generally be modified.
- */
-
- /*!
- * @function checkForMedia
- * @abstract
- * Check if media has newly arrived or disappeared.
- * @discussion
- * This method does most of the work in polling for media, first
- * calling the block storage device's reportMediaState method. If
- * reportMediaState reports no change in the media state, kIOReturnSuccess
- * is returned. If the media state has indeed changed, a call is made to
- * mediaStateHasChanged to act on the event.
- */
- virtual IOReturn checkForMedia(void);
-
- /*!
- * @function getDeviceTypeName
- * @abstract
- * Return the desired device name.
- * @discussion
- * This method returns a string, used to compare the
- * kIOBlockStorageDeviceTypeKey of our provider. This method is called from
- * probe.
- *
- * The default implementation of this method returns
- * kIOBlockStorageDeviceTypeGeneric.
- */
- virtual const char * getDeviceTypeName(void);
-
- /*!
- * @function initMediaState
- * @abstract
- * Initialize media-related instance variables.
- * @discussion
- * Called when media is not present, this method marks the device state
- * as not having media present, not spun up, and write-enabled.
- */
- virtual void initMediaState(void);
-
- /*!
- * @function mediaStateHasChanged
- * @abstract
- * React to a new media insertion or a media removal.
- * @discussion
- * This method is called on a media state change, that is, an arrival
- * or removal. If media has just become available, calls are made to
- * recordMediaParameters and acceptNewMedia. If media has just gone
- * away, a call is made to decommissionMedia, with the forcible
- * parameter set to true. The forcible teardown is needed to enforce
- * the disappearance of media, regardless of interested clients.
- */
- virtual IOReturn mediaStateHasChanged(IOMediaState state);
-
- /*
- * @endgroup
- */
-
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 0);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 1);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 2);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 3);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 4);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 5);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 6);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 7);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 8);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 9);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 10);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 11);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 12);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 13);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 14);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 15);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 16);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 17);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 18);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 19);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 20);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 21);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 22);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 23);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 24);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 25);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 26);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 27);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 28);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 29);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 30);
- OSMetaClassDeclareReservedUnused(IOBlockStorageDriver, 31);
-};
-
-#endif /* defined(KERNEL) && defined(__cplusplus) */
-
-#endif /* !_IOBLOCKSTORAGEDRIVER_H */
projects / apple / xnu.git / blobdiff