public:
virtual void RWCompletion(struct IOHDDrive::context *cx);
This method must be public so we can reach it from the C-language callback "glue" routine. It should not be called from outside this class.
protected:
virtual IOReturn acceptNewMedia(void);
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.
protected:
virtual struct IOHDDrive::context *allocateContext(void);
A context structure is only needed for asynchronous read or write operations, to contain information used to complete the request with the client.
protected:
virtual IOReturn checkForMedia(void);
This method does most of the work in polling for media, first calling the Transport Driver's reportMediaState method. If reportMediaState reports no change in the media state, kIOReturnSuccess is returned. 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.
public:
virtual UInt64 constrainByteCount(UInt64 requestedCount,bool isWrite);
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.
Name Description requestedCount The requested byte count for the next read or write operation. isWrite True if the operation will be a write; False if the operation will be a read.
protected:
virtual OSDictionary *constructMediaProperties(void);
This function creates a set of properties to express media properties.
This function is presently called by recordMediaParameters, but it does nothing.
protected:
virtual IOReturn decommissionMedia(bool forcible);
This method wraps a call to tearDown, to tear down the stack and the IOMedia object for the media. If "forcible" is true, the media object will be forgotten, and initMediaStates 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.
Name Description forcible True to force forgetting of the media object even if tearDown reports that there was an active client.
protected:
virtual void deleteContext(struct IOHDDrive::context *cx);
This method also issues a "release" for the IO buffer, if any.
Name Description cx A pointer to the context structure to be deleted.
public:
virtual IOReturn ejectMedia(void);
protected:
virtual void executeRequest(UInt64 byteStart, IOMemoryDescriptor * buffer, IOStorageCompletion completion);
This method is the main entry to start an asynchronous read or write operation. All IO operations must be block aligned and a multiple of the device block size. After some validations, the request is passed to the Transport Driver's doAsyncReadWrite method. The completion from the operation is set to call RWCompletion, by way of the gc_glue C function.
Name Description byteStart The starting byte offset of the data transfer. buffer The data buffer for the operation. A pointer to an IOMemoryDescriptor. completion The completion information for an asynchronous read or write operation.
public:
virtual IOReturn formatMedia(UInt64 byteCapacity);
Name Description byteCapacity The requested final byte capacity for the formatted media.
protected:
virtual const char * getDeviceTypeName(void);
This method returns a string, used to compare the kDeviceTypeProperty of
our provider. This method is called from probe.
The default implementation of this method returns kDeviceTypeHardDisk.
public:
virtual UInt32 getFormatCapacities(UInt64 * capacities, UInt32 capacitiesMaxCount) const;
This function returns the supported byte capacities for the device.
Name Description capacities Pointer for returning the list of capacities. capacitiesMaxCount The number of capacity values returned in "capacities."
public:
virtual UInt64 getMediaBlockSize(void) const;
public:
virtual IODrive::IOMediaState getMediaState(void) const;
public:
virtual bool handleStart(IOService * provider);
This function obtains device description strings (e.g. Vendor name), prints a message describing the device, and then obtains all removable-media information (if the device is removable.) Finally, a check for media is performed.
Name Description provider A pointer to our provider.
public:
virtual void handleStop(IOService * provider);
If the media is writable, this method issues a Synchronize Cache operation. Then the media is ejected.
Name Description provider A pointer to our provider.
protected:
virtual void initMediaStates(void);
Called when media is not present, this method marks the drive state as not having media present, not spun up, and write-enabled.
protected:
virtual IOMedia * instantiateDesiredMediaObject(void);
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.
protected:
virtual IOReturn instantiateMediaObject(IOMedia **media,UInt64 base,UInt64 byteSize,UInt32 blockSize, bool isWholeMedia,char *mediaName);
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.
Name Description media A pointer to the created IOMedia object. base Byte number of beginning of active data area of the media. Usually zero. byteSize Size of the data area of the media, in bytes. blockSize Block size of the media, in bytes. isWholeMedia True indicates the IOMedia object represents the entire media; False indicates the IOMedia object represents a portion of the entire media. mediaName Name of the IOMedia object.
Result: True indicates the media can be ejected by software; False indicates it cannot.public:
virtual bool isMediaEjectable(void) const;
Result: True indicates the media poll is expensive; False indicates polling is cheap.public:
virtual bool isMediaPollExpensive(void) const;
Result: True indicates that polling is required; False indicates that no polling is needed.public:
virtual bool isMediaPollRequired(void) const;
public:
virtual IOReturn lockMedia(bool lock);
This method may be used to lock the media in the device, thus preventing the user
from removing the media manually.
This method only makes sense if it is known that the device supports locking.
Name Description lock True indicates the media should be locked in the device; False indicates the media should be unlocked.
public:
virtual IOReturn pollMedia(void);
This method is called periodically by the superclass, if isMediaPollRequired has previously reported True. We are responsible for reacting to new media insertion, or to existing media being removed.
public:
virtual IOService * probe(IOService * provider,SInt32 * score);
This method first verifies that our provider is of class IOHDDriveNub, then checks that the provider's property "kDeviceTypeProperty" matches what we expect. Failure of either test causes a return of NULL.
protected:
virtual IOReturn recordAdditionalMediaParameters(void);
This method is called by recordMediaParameters() when media is detected. The default implementation does nothing and returns kIOReturnSuccess. A subclass may override this method to record additional parameters.
protected:
virtual IOReturn recordMediaParameters(void);
This method obtains media-related parameters via calls to the Transport Driver's reportBlockSize, reportMaxValidBlock, reportMaxReadTransfer, reportMaxWriteTransfer, and reportWriteProtection methods.
protected:
virtual void rejectMedia(void); /* default ejects */
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.
protected:
virtual bool setProvider(IOService * provider);
This method uses IODynamicCast to verify that the provider is of
the proper class type. The default implementation checks for a nub
of type IOHDDriveNub.
This method would be overridden for a new generic driver subclass. For
example, a generic CD driver would need to accept a different provider
class (e.g. IOCDDriveNub instead of IOHDDriveNub).
Name Description provider A pointer to our provider.
protected:
virtual bool showStats(void);
This method prints debugging statistics maintained by the class.
Present statistics include counts of up and down calls.
protected:
virtual IOReturn tearDown(IOService *media);
This method calls media->terminate, and if that succeeds, issues a release on the media object, followed by a call to initMediaStates.
Name Description media A pointer to the IOMedia object from which to initiate teardown.
protected:
virtual bool validateNewMedia(void);
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.
© 2000 Apple Computer, Inc. (Last Updated 2/23/2000)