Functions



RWCompletion

Abstract: Handle a C callback for an IO completion.
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.


acceptNewMedia

Abstract: React to new media insertion.
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.


allocateContext

Abstract: Allocate a context structure for use with the current async operation.
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.


checkForMedia

Abstract: Check if media has newly arrived or disappeared.
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.


constrainByteCount

Abstract: Constrain the byte count for this IO to device limits.
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.

Parameters

NameDescription
requestedCountThe requested byte count for the next read or write operation.
isWriteTrue if the operation will be a write; False if the operation will be a read.

constructMediaProperties

Abstract: Create properties related to the media.
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.


decommissionMedia

Abstract: Decommission an existing piece of media that has gone away.
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.

Parameters

NameDescription
forcibleTrue to force forgetting of the media object even if tearDown reports that there was an active client.

deleteContext

Abstract: Delete a context structure.
protected:

virtual void deleteContext(struct IOHDDrive::context *cx);

This method also issues a "release" for the IO buffer, if any.

Parameters

NameDescription
cxA pointer to the context structure to be deleted.

ejectMedia

Abstract: Eject the media.
public:

virtual IOReturn ejectMedia(void);


executeRequest

Abstract: Start an asynchronous read or write operation.
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.

Parameters

NameDescription
byteStartThe starting byte offset of the data transfer.
bufferThe data buffer for the operation. A pointer to an IOMemoryDescriptor.
completionThe completion information for an asynchronous read or write operation.

formatMedia

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

virtual IOReturn formatMedia(UInt64 byteCapacity);

Parameters

NameDescription
byteCapacityThe requested final byte capacity for the formatted media.

getDeviceTypeName

Abstract: Return the desired device name.
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.


getFormatCapacities

Abstract: Return the allowable formatting byte capacities.
public:

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

This function returns the supported byte capacities for the device.

Parameters

NameDescription
capacitiesPointer for returning the list of capacities.
capacitiesMaxCountThe number of capacity values returned in "capacities."

getMediaBlockSize

Abstract: Return the block size for the device, in bytes.
public:

virtual UInt64 getMediaBlockSize(void) const;


getMediaState

Abstract: Return the state of media in the device.
public:

virtual IODrive::IOMediaState getMediaState(void) const;


handleStart

Abstract: Handle startup functionality after superclass is ready.
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.

Parameters

NameDescription
providerA pointer to our provider.

handleStop

Abstract: Handle clean up functionality before driver is unloaded.
public:

virtual void handleStop(IOService * provider);

If the media is writable, this method issues a Synchronize Cache operation. Then the media is ejected.

Parameters

NameDescription
providerA pointer to our provider.

initMediaStates

Abstract: Initialize media-related instance variables.
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.


instantiateDesiredMediaObject

Abstract: Create an IOMedia object for media.
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.


instantiateMediaObject

Abstract: Create an IOMedia object for media.
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.

Parameters

NameDescription
mediaA pointer to the created IOMedia object.
baseByte number of beginning of active data area of the media. Usually zero.
byteSizeSize of the data area of the media, in bytes.
blockSizeBlock size of the media, in bytes.
isWholeMediaTrue indicates the IOMedia object represents the entire media; False indicates the IOMedia object represents a portion of the entire media.
mediaNameName of the IOMedia object.

isMediaEjectable

Abstract: Report whether the media is removable or not.
public:

virtual bool isMediaEjectable(void) const;

Result: True indicates the media can be ejected by software; False indicates it cannot.

isMediaPollExpensive

Abstract: Report whether polling for media is expensive.
public:

virtual bool isMediaPollExpensive(void) const;

Result: True indicates the media poll is expensive; False indicates polling is cheap.

isMediaPollRequired

Abstract: Report whether device must be polled to determine media state.
public:

virtual bool isMediaPollRequired(void) const;

Result: True indicates that polling is required; False indicates that no polling is needed.

lockMedia

Abstract: Lock or unlock the media in the device.
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.

Parameters

NameDescription
lockTrue indicates the media should be locked in the device; False indicates the media should be unlocked.

pollMedia

Abstract: Poll for media insertion/removal.
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.


probe

Abstract: Probe for proper client Transport Driver.
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.


recordAdditionalMediaParameters

Abstract: Record any additional media parameters as necessary.
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.


recordMediaParameters

Abstract: Obtain media-related parameters on media insertion.
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.


rejectMedia

Abstract: Reject new media.
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.


setProvider

Abstract: Store the provider pointer.
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).

Parameters

NameDescription
providerA pointer to our provider.

showStats

Abstract: Print debugging statistics.
protected:

virtual bool showStats(void);

This method prints debugging statistics maintained by the class.

Present statistics include counts of up and down calls.

Result: True indicates statistics should be printed; False indicates no printing desired.

tearDown

Abstract: Tear down the stack above this object when media goes away.
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.

Parameters

NameDescription
mediaA pointer to the IOMedia object from which to initiate teardown.

validateNewMedia

Abstract: Verify that new media is acceptable.
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)