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

Member Functions

commitAGPMemory

public:

virtual IOReturn commitAGPMemory( IOMemoryDescriptor * memory,
 IOByteCount agpOffset,
 IOOptionBits options = 0 );

Makes the memory described by the IOMemoryDescriptor object addressable by AGP by entering its pages into the GART array, given an offset into AGP space supplied by the caller (usually allocated by the AGP range allocator). It is the callers responsibility to prepare non-kernel pageable memory before calling this method, with IOMemoryDescriptor::prepare.

Parameters

Name	Description
memory	A IOMemoryDescriptor object describing the memory to add to the GART.
agpOffset	An offset into AGP space that the caller has allocated - usually allocated by the AGP range allocator.
options	None currently defined - pass zero.

createAGPSpace

public:

virtual IOReturn createAGPSpace( IOOptionBits options,
 IOPhysicalAddress * address, 
 IOPhysicalLength * length );

This method should be called by the driver for the AGP master device to set the size of the space and enable AGP transactions. It will destroy any AGP space currently allocated.

Parameters

Name	Description
options	No options are currently defined, pass zero.
address	The physical range allocated for the AGP space is passed back to the caller.
length	An in/out parameter - the caller sets the devices maximum AGP addressing and the actual size created is passed back.

destroyAGPSpace

public:

virtual IOReturn destroyAGPSpace( void );

This method should be called by the driver to shutdown AGP transactions and release resources.

getAGPRangeAllocator

public:

virtual IORangeAllocator * getAGPRangeAllocator( void );

To allocate ranges in AGP space, obtain a range allocator for the space with this method. It is retained while the space is created (until destroyAGPSpace is called) and should not be released by the caller.

getAGPStatus

public:

virtual IOOptionBits getAGPStatus( IOOptionBits which = kIOAGPDefaultStatus );

Returns state bits for the AGP bus. Only one type of status is currently defined.

Parameters

Name	Description
which	Type of status - only kIOAGPDefaultStatus is currently valid.

releaseAGPMemory

public:

virtual IOReturn releaseAGPMemory( IOMemoryDescriptor * memory, 
 IOByteCount agpOffset );

Makes the memory described by the IOMemoryDescriptor object unaddressable by AGP by removing its pages from the GART array, given an offset into AGP space supplied by the caller (usually allocated by the AGP range allocator). It is the callers responsibility to complete non-kernel pageable memory before calling this method, with IOMemoryDescriptor::complete.

Parameters

Name	Description
memory	A IOMemoryDescriptor object describing the memory to remove from the GART.
agpOffset	An offset into AGP space that the caller has allocated - usually allocated by the AGP range allocator.

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

Typedefs

statevalue

typedef  enum  stateValues  stateValue;

const  bool  kSync  =  true;  /*  type  info  for  requests  awaiting  power  */
const  bool  kAsync  =  false;

};

Shorthand for enum StateValues.

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

Member Functions

RWCompletion

protected:

virtual void RWCompletion(struct context *cx) = 0;

A subclass must implement the read-write completion, called upon completion of an IO started by doAsyncReadWrite.

Parameters

Name	Description
cx	A pointer to the context structure for the completing command.

allocateContext

protected:

virtual struct context * allocateContext(void);

allocateInquiryBuffer

protected:

virtual IOReturn allocateInquiryBuffer(UInt8 **buf,UInt32 size);

Parameters

Name	Description
buf	A pointer for the returned buffer pointer.
size	The requested size of the buffer, in bytes.

allocateReadCapacityBuffer

protected:

virtual IOReturn allocateReadCapacityBuffer(UInt8 **buf,UInt8 size);

Parameters

Name	Description
buf	A pointer for the returned buffer pointer.
size	The requested size of the buffer, in bytes.

allocateTempBuffer

protected:

virtual IOReturn allocateTempBuffer(UInt8 **buf,UInt32 size);

Parameters

Name	Description
buf	A pointer for the returned buffer pointer.
size	The requested size of the buffer, in bytes.

createReadCdb

protected:

virtual UInt32 createReadCdb(
 UInt8 *cdb, /* in */
 UInt32 *cdbLength, /* out */
 UInt32 block, /* in */
 UInt32 nblks, /* in */
 UInt32 *maxAutoSenseLength, /* out */
 UInt32 *timeoutSeconds); /* out */

Override this to control the cdb created for a read operation. The default implementation creates a 10-byte read command with disconnect allowed, 8-byte autosense, and a 2-second timeout.

Parameters

Name	Description
cdb	A pointer to the CDB bytes.
cdbLength	The length of the CDB in bytes.
block	The device block to be read.
nblks	The number of blocks to be transferred.
maxAutoSenseLength	The maximum size of the autosense data, in bytes. A value of zero will disable autosense.
timeoutSeconds	The command timeout in seconds.

createWriteCdb

protected:

virtual UInt32 createWriteCdb(
 UInt8 *cdb, /* in */
 UInt32 *cdbLength, /* out */
 UInt32 block, /* in */
 UInt32 nblks, /* in */
 UInt32 *maxAutoSenseLength, /* out */
 UInt32 *timeoutSeconds); /* out */

Override this to control the cdb created for a write operation. The default implementation creates a 10-byte write command with disconnect allowed, 8-byte autosense, and a 2-second timeout.

Parameters

Name	Description
cdb	A pointer to the CDB bytes.
cdbLength	The length of the CDB in bytes.
block	The device block to be written.
nblks	The number of blocks to be transferred.
maxAutoSenseLength	The maximum size of the autosense data, in bytes. A value of zero will disable autosense.
timeoutSeconds	The command timeout in seconds.

deleteContext

protected:

virtual void deleteContext(struct context *cx);

This method also issues a "release" for the IO buffer and/or lock, if any.

Parameters

Name	Description
cx	A pointer to the context structure to be deleted.

deleteInquiryBuffer

protected:

virtual void deleteInquiryBuffer(UInt8 *buf,UInt32 size);

Parameters

Name	Description
buf	A pointer to the buffer.
size	The requested size of the buffer, in bytes.

deleteReadCapacityBuffer

protected:

virtual void deleteReadCapacityBuffer(UInt8 *buf,UInt32 len);

Parameters

Name	Description
buf	A pointer to the buffer.
len	The requested size of the buffer, in bytes.

deleteTempBuffer

protected:

virtual void deleteTempBuffer(UInt8 *buf,UInt32 len);

Parameters

Name	Description
buf	A pointer to the buffer.
len	The requested size of the buffer, in bytes.

dequeueCommands

protected:

virtual void dequeueCommands(void);

This method is called when a command is queued (from queueCommand), when a call completes (from RWCompletion), and when the device power level changes. All commands for which the device power level is proper are immediately dequeued.

Queued synchronous commands are simply "awakened" by unlocking a lock. The originating thread then continues and issues the command. Asynchronous commands are immediately dispatched via a call to standardAsyncReadWriteExecute.

deviceTypeMatches

public:

virtual bool deviceTypeMatches(UInt8 inqBuf[],UInt32 inqLen) = 0;

This method must be implemented by a device-specific subclass.

Parameters

Name	Description
inqBuf	A pointer to the SCSI inquiry data for the device.
inqLen	The size of the data in the inquiry buffer.

doInquiry

protected:

virtual IOReturn doInquiry(UInt8 *inqBuf,UInt32 maxLen,UInt32 *actualLen);

This method issues a SCSI Inquiry command to the device, to obtain the result in the supplied buffer. The method first issues an inquiry with a 5-byte length, to obtain the full length of the devices inquiry data. The second Inquiry command is issued to get the full inquiry data (limited to maxLen, of course).

Parameters

Name	Description
inqBuf	A pointer to the buffer.
maxLen	The maximum number of bytes the buffer can contain.
actualLen	A pointer to the returned byte count actually transferred.

doReadCapacity

protected:

virtual IOReturn doReadCapacity(UInt64 *blockSize,UInt64 *maxBlock);

The default implementation of this method issues a standard SCSI Read Capacity command. The block size and maximum valid block are extracted from the returned data in an endian-neutral way.

Parameters

Name	Description
blockSize	A pointer to the returned block size value.
maxBlock	A pointer to the returned maximum block number.

executeCdb

public:

virtual IOReturn executeCdb(struct cdbParams *params);

This method is provided to allow developers to issue arbitrary commands to the device (via the Transport Driver). Expected uses might include vendor-specific commands to support device-based password-protection, or for other vendor features.

This method may not be supported by all Transport Drivers. For example, ATA devices do not have a CDB concept; those Transport Drivers will return kIOReturnUnsupported.

Parameters

Name	Description
params	See IOHDTypes.h for the layout of this data structure.

genericCompletion

public:

virtual void genericCompletion(struct context *cx);

This method handles completion of a SCSI command. It implements a simple state machine to handle a Unit Attention condition on a command.

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. *

* If a Unit Attention condition occurs, we set the state to kHandlingUnitAttention and call handleUnitAttention to do whatever is necessary to clear the condition. Eventually, handleUnitAttention resets the state to kDoneHandlingUnitAttention, which will allow the state machine to reissue the original command.

If we are already processing a Unit Attention, then genericCompletion increments a step counter and calls handleUnitAttention. The step counter allows handleUnitAttention to issue multiple SCSI commands to clear the condition. The handleUnitAttention method is called repeatedly, until the state is set to kDoneHandlingUnitAttention.

If this operation is a normal asynchronous read or write (usually started by standardAsyncReadWrite, though this is not required), then a call is made to RWCompletion, followed by deletion of the context structure for the command. RWCompletion is implemented by the subclass of IOBasicSCSI, for example in IOSCSIHDDrive.

Parameters

Name	Description
cx	A pointer to the context structure for the command.

getAdditionalDeviceInfoString

public:

virtual char * getAdditionalDeviceInfoString(void);

getBlockSize

protected:

virtual UInt64 getBlockSize(void);

This method obtains the block size from the Read-Capacity data. If RC data is not yet cached, a call is made to doReadCapacity to obtain the data.

getExecuteCDBPowerState

protected:

virtual UInt32 getExecuteCDBPowerState(void) = 0;

getInquiryPowerState

protected:

virtual UInt32 getInquiryPowerState(void) = 0;

getProductString

public:

virtual char * getProductString(void);

getReadCapacityPowerState

protected:

virtual UInt32 getReadCapacityPowerState(void) = 0;

getReadWritePowerState

protected:

virtual UInt32 getReadWritePowerState(void) = 0;

getReportWriteProtectionPowerState

protected:

virtual UInt32 getReportWriteProtectionPowerState(void) = 0;

getRevisionString

public:

virtual char * getRevisionString(void);

getVendorString

public:

virtual char * getVendorString(void);

handleUnitAttention

protected:

virtual void handleUnitAttention(struct context *cx);

Override this to perform any special processing required when a Unit-Attention condition is detected. The cx->step value starts at 1 and is incremented as each subsequent command is executed. HandleUnitAttention is then called again duirng the command completion, until cx->state is changed to kDoneHandlingUnitAttention. This repeated calling behavior allows handleUnitAttention to issue several commands to the device to recover from the Unit-Attention condition. Note that since handleUnitAttention is called on the SCSI completion thread, it must not issue blocking operations, but should instead call simpleAsyncIO.

The default implementation merely sets the state to kDoneHandlingUnitAttention, to allow the original command to be reissued.

Parameters

Name	Description
cx	Pointer to context for the current command.

powerTickle

protected:

virtual bool powerTickle(UInt32 desiredState) = 0;

A subclass must implement powerTickle, which is called when we desire power to execute a command. PowerTickle may handle generic or a subclass-expanded set of power states. The implementation will usually relay the call to the Power Management subsystem function activityTickle. For a device without power management capability, the implementation should always return True.

Parameters

Name	Description
desiredState	The desired device power level.

probe

public:

virtual IOService * probe(IOService * provider,SInt32 * score);

This method is responsible for matching the device type. It calls doInquiry to issue a SCSI Inquiry command to the device, then calls deviceTypeMatches to ensure that the device type matches the expected type. If the device type matches, then the Vendor, Product, and Revision strings are copied from the inquiry data, and "this" is returned. If the device type does not match, NULL is returned.

The default implementation ignores the score parameter, though that parameter is passed to the superclass probe method.

queueCommand

protected:

virtual void queueCommand(struct context *cx,bool isSync,UInt32 desiredPower);

This method is called prior to issuing any IO command, so that each command can be enqueued awaiting its desired device power level. After queuing the command, a call is made to dequeueCommands to attempt to dequeue any available command that can be executed (including the one just queued). Putting commands into the queue ensures that the proper sequence is maintained.

Parameters

Name	Description
cx	The context for the command being queued.
isSync	True if the command is synchronous; False if the command is asynchronous.
desiredPower	The device power level needed before the command can execute.

reportBlockSize

public:

virtual IOReturn reportBlockSize(UInt64 *blockSize);

This method returns the block size for the media. The default implementation obtains the block size from the SCSI Read Capacity command. Since the result of the Read Capacity is used by this method and reportMaxValidBlock, this method either returns a cached value or calls doReadCapacity to issue the command and cache both values.

Parameters

Name	Description
blockSize	Pointer to returned block size value.

reportEjectability

public:

virtual IOReturn reportEjectability(bool *isEjectable);

This method reports whether the media is ejectable under software control. The default implementation always reports that removable media is ejectable.

This method should only be called if the media is known to be removable.

Parameters

Name	Description
isEjectable	Pointer to returned result. True indicates the media is ejectable, False indicates the media cannot be ejected under software control.

reportLockability

public:

virtual IOReturn reportLockability(bool *isLockable);

This method reports whether the media can be locked under software control, to prevent the user from removing the media manually, e.g. by pressing a button on the drive. This method is only called by the generic driver when the media is known to be removable. The default implementation always returns true.

This method should only be called if the media is known to be removable.

Parameters

Name	Description
isLockable	Pointer to returned result. True indicates the media can be locked in place; False indicates the media cannot be locked by software.

reportMaxReadTransfer

public:

virtual IOReturn reportMaxReadTransfer(UInt64 blocksize,UInt64 *max);

Some devices impose a maximum data transfer size. Because this limit may be determined by the size of a block-count field in a command, the limit may depend on the block size of the transfer. The default implementation reports blocksize * 65536, which is the maximum number of bytes that can be transferred in a SCSI command with a standard 16-bit block count field.

Parameters

Name	Description
blockSize	The block size desired for the transfer.
max	Pointer to returned result.

reportMaxValidBlock

public:

virtual IOReturn reportMaxValidBlock(UInt64 *maxBlock);

This method reports the maximum allowable block number. The default implementation obtains the block number from the SCSI Read Capacity command. Since the result of the Read Capacity is used by this method and reportBlockSize, this method either returns a cached value or calls doReadCapacity to issue the command and cache both values.

Parameters

Name	Description
maxBlock	Pointer to returned result

reportMaxWriteTransfer

public:

virtual IOReturn reportMaxWriteTransfer(UInt64 blocksize,UInt64 *max);

Some devices impose a maximum data transfer size. Because this limit may be determined by the size of a block-count field in a command, the limit may depend on the block size of the transfer. The default implementation reports blocksize * 65536, which is the maximum number of bytes that can be transferred in a SCSI command with a standard 16-bit block count field.

Parameters

Name	Description
blockSize	The block size desired for the transfer.
max	Pointer to returned result.

reportPollRequirements

public:

virtual IOReturn reportPollRequirements(bool *pollRequired,bool *pollIsExpensive);

This method reports whether the device must be polled to detect media insertion, and whether a poll is expensive to perform.

The term "expensive" typically implies a device that must be spun-up to detect media, as on a PC floppy. Most devices can detect media inexpensively.

The default implementation of this method always reports an inexpensive poll (pollIsExpensive = false), and that all removable media must be polled.

Parameters

Name	Description
pollRequired	Pointer to returned result. True indicates that polling is required; False indicates that polling is not required to detect media.
pollIsExpensive	Pointer to returned result. True indicates that the polling operation is expensive; False indicates that the polling operation is cheap.

reportRemovability

public:

virtual IOReturn reportRemovability(bool *isRemovable);

This method reports whether the media is removable, but it does not provide detailed information regarding software eject or lock/unlock capability.

The default implementation of this method examines the cached Inquiry data to determine if media is removable. If the RMB bit (0x80 of Inquiry data byte 1) is set, the media is removable. If there is no Inquiry data, the media is reported to be nonremovable.

This method also sets the instance variable _removable.

Parameters

Name	Description
isRemovable	Pointer to returned result. True indicates that the media is removable; False indicates the media is not removable.

reportWriteProtection

public:

virtual IOReturn reportWriteProtection(bool *isWriteProtected);

The default implementation of this method issues a SCSI Mode Sense command to test the WP bit( 0x80 of byte 2 of the Mode Sense Header data). A request is made for Mode Sense Page 1, though any valid page will return a header. If the bit is set, the media is considered write-protected.

Parameters

Name	Description
isWriteProtected	Pointer to returned result. True indicates that the media is write-protected (it cannot be written); False indicates that the media is not write-protected (it is permissible to write).

simpleSynchIO

protected:

virtual IOReturn simpleSynchIO(struct context *cx);

This method issues a single SCSI command and waits for the command to complete. The SCSI command must already be set up in the context structure.

Parameters

Name	Description
cx	A pointer to the context structure for the command.

standardAsyncReadWrite

protected:

virtual IOReturn standardAsyncReadWrite(IOMemoryDescriptor *buffer,
 UInt32 block,UInt32 nblks,
 gdCompletionFunction action,
 IOService *target,void *param);

This method starts an asynchronous read or write operation. No incoming parameters are validated. The default implementation calls createReadCdb or createWriteCdb, then issues a SCSI command to IOSCSIDevice. If the command is accepted, then the completion will be called at some future time.

Parameters

Name	Description
buffer	An IOMemoryDescriptor describing the data-transfer buffer. The data direction is contained in the IOMemoryDescriptor. Responsiblity for releasing the descriptor rests with the caller.
block	The starting block number of the data transfer.
nblks	The integral number of blocks to be transferred.
action	The C function called upon completion of the data transfer.
target	The C++ class "this" pointer, passed as an argument to "action."
param	This value is passed as an argument to "action." It is not validated or modified.

standardAsyncReadWriteExecute

protected:

virtual IOReturn standardAsyncReadWriteExecute(struct context *cx);

Parameters

Name	Description
cx	A pointer to the context structure for the command.

standardSyncReadWrite

protected:

virtual IOReturn standardSyncReadWrite(IOMemoryDescriptor *buffer,UInt32 block,UInt32 nblks);

Perform a synchronous read or write operation.

Parameters

Name	Description
buffer	An IOMemoryDescriptor describing the data-transfer buffer. The data direction is contained in the IOMemoryDescriptor. Responsiblity for releasing the descriptor rests with the caller.
block	The starting block number of the data transfer.
nblks	The integral number of blocks to be transferred.

stringFromState

protected:

virtual char * stringFromState(stateValue state);

Used for debugging.

Parameters

Name	Description
state	The state to be converted to a string description.

Member Data

_inqBuf

protected:

 UInt8 * _inqBuf; /* the Inquiry data buffer */

 /*!
 * @var _inqBufSize
 * The size of the inquiry data buffer, in bytes.
 */
 UInt32 _inqBufSize; /* size of the buffer */

 /*!
 * @var _inqLen
 * The number of valid bytes of inquiry data.
 */
 UInt32 _inqLen; /* valid bytes in buffer */
 
 /*!
 * @var _vendor
 * The Vendor Name string from the inquiry data, null-terminated.
 */
 char _vendor[9]; /* info from Inquiry data */

 /*!
 * @var _product
 * The Product Name string from the inquiry data, null-terminated.
 */
 char _product[17];

 /*!
 * @var _rev
 * The Product Revision string from the inquiry data, null-terminated.
 */
 char _rev[5];

 /* Since we get both of these items from the same command, we
 * just cache both values if we get either call, so we only
 * have to issue the command once.
 */

 /*!
 * @var _readCapDone
 * True if we have issued a Read-Capacity command to obtain the
 * values for _maxBlock and _blockSize.
 */
 bool _readCapDone;

 /*!
 * @var _removable
 * True if the media is removable; False if the media is fixed.
 */
 bool _removable;

 /*!
 * @var _maxBlock
 * The highest valid block on the media, relative to zero.
 */
 UInt64 _maxBlock;

 /*!
 * @var _blockSize
 * The block size of the media in bytes.
 */
 UInt64 _blockSize;

 /* The queue of pending requests awaiting power: */

 /*!
 * @struct queue
 * @discussion
 * A data structure for a queue.
 * @field head
 * A pointer to the head item.
 * @field tail
 * A pointer to the tail item.
 * @field lock
 * A lock used to protect the queue during changes.
 */
 /*!
 * @var _powerQueue
 * A queue structure containing operations queued awaiting power level.
 */
 struct queue {
 struct context * head;
 struct context * tail;
 IOLock * lock;
 } _powerQueue;
 
};

A pointer to the allocate Inquiry Data buffer.

_provider

protected:

 IOSCSIDevice * _provider;

A pointer to our provider.

completion

public:

  *  @struct  context
  *  @discussion
  *  The  context  structure  contains  all  persistent  information  needed  for  a
  *  synchronous  or  asynchronous  IO  operation.
  *  @field  completion
  *  The  completion  information  for  an  asynchronous  read  or  write  operation.
  *  @field  state
  *  The  current  state  of  the  operation.
  *  @field  step
  *  The  current  step  value,  if  we  are  handling  a  Unit  Attention.
  *  @field  originalContext
  *  A  pointer  to  the  context  for  the  command  that  caused  the  Unit  Attention
  *  condition.
  *  @field  scsireq
  *  A  pointer  to  the  IOSCSIRequest  object.
  *  @field  memory
  *  The  data  buffer  for  the  operation.  A  pointer  to  an  IOMemoryDescriptor.
  *  @field  scsiresult
  *  A  pointer  to  the  IOSCSIResult  object.
  *  @field  desiredPower
  *  The  desired  power  level  for  the  operation  to  execute.
  *  @field  isSync
  *  True  if  synchronous;  False  if  asynchronous.
  *  @field  next
  *  A  pointer  to  a  context  structure,  used  as  a  queue  forward-link.
  *  @field  sync
  *  A  syncer  used  to  block  a  thread  awaiting  a  power  level,  or  for  completion
  *  of  a  synchronous  operation.
  */
  struct  context  {

  /*  Completion  information  for  our  client,  used  only  for  async  operations.
  *  Typically  this  information  will  only  be  used  by  subclasses.
  */

  struct  {
  gdCompletionFunction  action;  /*  function  to  call  */
  IOService  *target;  /*  client  object  ("this")  */
  void  *param;  /*  client's  parameter  */
  }  completion;

Fields

Name	Description
action	The C function called upon completion of the operation.
target	The C++ class pointer, passed to tha action function.
param	A value passed to the action function. This value is not touched.

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

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

Member Functions

checkForWork

protected:

virtual bool checkForWork();

commandGate

public:

static IOCommandGate *commandGate(OSObject *owner, Action action = 0);

init

public:

virtual bool init(OSObject *owner, Action action = 0);

Initialiser for IOCommandGate operates only on newly 'newed' objects. Shouldn't be used to re-init an existing instance.

Parameters

Name	Description
owner	Owner of this, newly created, instance of the IOCommandGate. This argument will be used as the first parameter in the action callout.
action	Pointer to a C function that is called whenever a client of the IOCommandGate calls runCommand. NB Can be a C++ member function but caller must cast the member function to $link IOCommandGate::Action and they will get a compiler warning. Defaults to zero, see $link IOEventSource::setAction.

runAction

public:

virtual IOReturn runAction(Action action,
 void *arg0 = 0, void *arg1 = 0,
 void *arg2 = 0, void *arg3 = 0);

Client function that causes the given action to be called in a single threaded manner. Beware the work-loop's gate is recursive and command gates can cause direct or indirect re-entrancy. When the executing on a client's thread runCommand will sleep until the work-loop's gate opens for execution of client actions, the action is single threaded against all other work-loop event sources.

Parameters

Name	Description
action	Pointer to function to be executed in work-loop context.
arg0	Parameter for action of command gate, defaults to 0.
arg1	Parameter for action of command gate, defaults to 0.
arg2	Parameter for action of command gate, defaults to 0.
arg3	Parameter for action of command gate, defaults to 0.

runCommand

public:

virtual IOReturn runCommand(void *arg0 = 0, void *arg1 = 0,
 void *arg2 = 0, void *arg3 = 0);

Client function that causes the current action to be called in a single threaded manner. Beware the work-loop's gate is recursive and command gates can cause direct or indirect re-entrancy. When the executing on a client's thread runCommand will sleep until the work-loop's gate opens for execution of client actions, the action is single threaded against all other work-loop event sources.

Parameters

Name	Description
arg0	Parameter for action of command gate, defaults to 0.
arg1	Parameter for action of command gate, defaults to 0.
arg2	Parameter for action of command gate, defaults to 0.
arg3	Parameter for action of command gate, defaults to 0.

Member Data

Action

public:typedef IOReturn (*Action)(OSObject *owner, void *arg0, void *arg1, void *arg2, void *arg3);

Type and arguments of callout C function that is used when a runCommand is executed by a client. Cast to this type when you want a C++ member function to be used. Note the arg1 - arg3 parameters are straight pass through from the runCommand to the action callout.

Parameters

Name	Description
owner	Target of the function, can be used as a refcon. The owner is set during initialisation of the IOCommandGate instance. Note if a C++ function was specified this parameter is implicitly the first paramter in the target member function's parameter list.
arg0	Argument to action from run operation.
arg1	Argument to action from run operation.
arg2	Argument to action from run operation.
arg3	Argument to action from run operation.

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

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

Member Functions

arrayFromList

public:

static OSArray * arrayFromList(
 InitElement list[],
 IOItemCount count );

This method creates IODeviceMemory instances for each physical range passed in a IODeviceMemory::InitElement array. Each element consists of a physical address, length and tag value for the IODeviceMemory. The instances are returned as a created OSArray.

Parameters

Name	Description
list	An array of IODeviceMemory::InitElement structures.
count	The number of elements in the list.

withRange

public:

static IODeviceMemory * withRange( 
 IOPhysicalAddress start,
 IOPhysicalLength length );

This method creates IODeviceMemory instance for one physical range passed as a physical address and length. It just calls IOMemoryDescriptor::withPhysicalAddress.

Parameters

Name	Description
address	The physical address of the first byte in the memory.
withLength	The length of memory.

withRange

public:

static IODeviceMemory * withSubRange( 
 IODeviceMemory * of,
 IOPhysicalAddress offset,
 IOPhysicalLength length );

This method creates IODeviceMemory instance for a subset of an existing IODeviceMemory range, passed as a physical address offset and length. It just calls IOMemoryDescriptor::withSubRange.

Parameters

Name	Description
of	The parent IODeviceMemory of which a subrange is to be used for the new descriptor, which will be retained by the subrange IODeviceMemory.
offset	A byte offset into the parent's memory.
length	The length of the subrange.

Member Data

InitElement

public:

  struct  InitElement  {
  IOPhysicalAddress  start;
  IOPhysicalLength  length;
  IOOptionBits  tag;
  };

Fields

Name	Description
start	First physical address in the range.
length	Length of the range.
tag	32-bit value not interpreted by IODeviceMemory or IOMemoryDescriptor, for use by the bus family.

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

#defines

kIODriveStatistics

kIODriveStatistics is a property of IODrive objects. It is an OSDictionary.

#define kIODriveStatistics "Statistics"

The kIODirectionStatistics property contains a table of statistics describing drive operations. All the different statistics are grouped under this table.

kIODriveStatisticsBytesRead

kIODriveStatisticsBytesRead is one of the statistic entries listed under the kIODriveStatistics property of IODrive objects. It is an OSNumber.

#define kIODriveStatisticsBytesRead "Bytes (Read)"

The kIODriveStatisticsBytesRead property describes the number of bytes read since the drive object was instantiated.

kIODriveStatisticsBytesWritten

kIODriveStatisticsBytesWritten is one of the statistic entries listed under the kIODriveStatistics property of IODrive objects. It is an OSNumber.

#define kIODriveStatisticsBytesWritten "Bytes (Write)"

The kIODriveStatisticsBytesWritten property describes the number of bytes written since the drive object was instantiated.

kIODriveStatisticsLatentReadTime

kIODriveStatisticsLatentReadTime is one of the statistic entries listed under the kIODriveStatistics property of IODrive objects. It is an OSNumber.

#define kIODriveStatisticsLatentReadTime "Latency Time (Read)"

The kIODriveStatisticsLatentReadTime property describes the number of nanoseconds of latency during reads since the drive object was instantiated.

kIODriveStatisticsLatentWriteTime

kIODriveStatisticsLatentWriteTime is one of the statistic entries listed under the kIODriveStatistics property of IODrive objects. It is an OSNumber.

#define kIODriveStatisticsLatentWriteTime "Latency Time (Write)"

The kIODriveStatisticsLatentWriteTime property describes the number of nanoseconds of latency during writes since the drive object was instantiated.

kIODriveStatisticsReadErrors

kIODriveStatisticsReadErrors is one of the statistic entries listed under the kIODriveStatistics property of IODrive objects. It is an OSNumber.

#define kIODriveStatisticsReadErrors "Errors (Read)"

The kIODriveStatisticsReadErrors property describes the number of read errors encountered since the drive object was instantiated.

kIODriveStatisticsReadRetries

kIODriveStatisticsReadRetries is one of the statistic entries listed under the kIODriveStatistics property of IODrive objects. It is an OSNumber.

#define kIODriveStatisticsReadRetries "Retries (Read)"

The kIODriveStatisticsReadRetries property describes the number of read retries required since the drive object was instantiated.

kIODriveStatisticsReads

kIODriveStatisticsReads is one of the statistic entries listed under the kIODriveStatistics property of IODrive objects. It is an OSNumber.

#define kIODriveStatisticsReads "Operations (Read)"

The kIODriveStatisticsReads property describes the number of read operations processed since the drive object was instantiated.

kIODriveStatisticsTotalReadTime

kIODriveStatisticsTotalReadTime is one of the statistic entries listed under the kIODriveStatistics property of IODrive objects. It is an OSNumber.

#define kIODriveStatisticsTotalReadTime "Total Time (Read)"

The kIODriveStatisticsTotalReadTime property describes the number of nanoseconds spent performing reads since the drive object was instantiated.

kIODriveStatisticsTotalWriteTime

kIODriveStatisticsTotalWriteTime is one of the statistic entries listed under the kIODriveStatistics property of IODrive objects. It is an OSNumber.

#define kIODriveStatisticsTotalWriteTime "Total Time (Write)"

The kIODriveStatisticsTotalWriteTime property describes the number of nanoseconds spent performing writes since the drive object was instantiated.

kIODriveStatisticsWriteErrors

kIODriveStatisticsWriteErrors is one of the statistic entries listed under the kIODriveStatistics property of IODrive objects. It is an OSNumber.

#define kIODriveStatisticsWriteErrors "Errors (Write)"

The kIODriveStatisticsWriteErrors property describes the number of write errors encountered since the drive object was instantiated.

kIODriveStatisticsWriteRetries

kIODriveStatisticsWriteRetries is one of the statistic entries listed under the kIODriveStatistics property of IODrive objects. It is an OSNumber.

#define kIODriveStatisticsWriteRetries "Retries (Write)"

The kIODriveStatisticsWriteRetries property describes the number of write retries required since the drive object was instantiated.

kIODriveStatisticsWrites

kIODriveStatisticsWrites is one of the statistic entries listed under the kIODriveStatistics property of IODrive objects. It is an OSNumber.

#define kIODriveStatisticsWrites "Operations (Write)"

The kIODriveStatisticsWrites property describes the number of write operations processed since the drive object was instantiated.

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

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

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.

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

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.

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.

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

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.

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

Name	Description
byteCapacity	Number of bytes to format media to.

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

Name	Description
capacities	Buffer that will receive the UInt64 capacity values.
capacitiesMaxCount	Maximum number of capacity values that can be held in the buffer.

getMediaBlockSize

protected:

virtual inline UInt64 getMediaBlockSize() const = 0;

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

getMediaState

public:

virtual IOMediaState getMediaState() const = 0;

Ask the drive about the media's current state.

getStatistic

public:

virtual UInt64 getStatistic(Statistics statistic) const;

Ask the drive to report one of its operating statistics.

Parameters

Name	Description
statistic	Statistic index (an IODrive::Statistics index).

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

Name	Description
statistics	Buffer that will receive the UInt64 statistic values.
statisticsMaxCount	Maximum number of statistic values that can be held in the buffer.

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

Name	Description
client	Client requesting the close.
options	Options 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

Name	Description
client	Client to check the open state of. Set to zero to check the open state of all clients.

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

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.

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

Name	Description
provider	This object's provider.

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

Name	Description
provider	This 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

Name	Description
isWrite	Indicates 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

Name	Description
isWrite	Indicates 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.

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.

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.

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

Name	Description
lock	Pass true to lock the media, otherwise pass false to unlock the media.

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.

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

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.

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

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.

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

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.

Member Data

IOMediaState

public:

  enum  IOMediaState
  {
  kMediaOffline,
  kMediaOnline,
  kMediaBusy
  };

The different states that getMediaState() can report.

Constants

Name	Description
kMediaOffline	Media is not available.
kMediaOnline	Media is available and ready for operations.
kMediaBusy	Media 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

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)

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

Member Functions

allocateNetworkInterface

protected:

virtual IONetworkInterface * allocateNetworkInterface();

Allocates and returns a new IOEthernetInterface instance. The controller class from each family must implement this method inherited from IONetworkController to return the corresponding interface object when attachNetworkInterface() is called. Subclasses of IOEthernetController (Ethernet drivers) would have little need to override this implementation.

enablePacketFilters

protected:

virtual IOReturn enablePacketFilters(UInt32 filters,
 UInt32 * activeFiltersP);

Called by interface object to change the set of packet filters that should be enabled by the controller. The implementation in IOEthernetController will trap any changes to multicast or promiscuous filters and convert the changes into a filter mode for setMulticastMode() and setPromiscuousMode() methods. This is done strictly as a convenience for drivers, which may choose to override this method to handle the filter changes directly. Unicast and Broadcast filters are assumed to be always enabled, and no driver intervention is required.

Parameters

Name	Description
filters	Each bit set indicates a particular filter that should be enabled. Filter bits that are not turned on must be disabled.
activeFiltersP	Updated by this method to reflect the real set of active filters. Ideally, it should be the same as the set specified by the first argument.

free

protected:

virtual void free();

Frees the IOEthernetController instance.

getFamilyFeatureSet

public:

virtual UInt32 getFamilyFeatureSet() const;

Get the Ethernet feature sets supported by the controller. Ethernet controller drivers may override this method and return a mask of supported feature sets.

getHardwareAddress

protected:

virtual IOReturn getHardwareAddress(enet_addr_t * addr) = 0;

Get the controller's hardware address. Ethernet drivers must implement this method, by reading the address from hardware and writing it to the buffer provided.

Parameters

Name	Description
addr	Pointer to a enet_addr_t where the hardware address should be written to.

getPacketFilters

protected:

virtual IOReturn getPacketFilters(UInt32 * filtersP);

Returns all the packet filters supported by the controller. See IONetworkController for the list of packet filters. This method will perform a bitwise OR of kIOPacketFilterUnicast, kIOPacketFilterBroadcast, kIOPacketFilterMulticast, kIOPacketFilterPromiscuous, and write the result using the provided pointer. Drivers that support a different set of filters should override this method.

Parameters

Name	Description
filtersP	Pointer to an integer that shall be updated by this method to contain the set of supported filters.

init

public:

virtual bool init(OSDictionary * properties);

Initialize an IOEthernetController instance.

Parameters

Name	Description
properties	A property dictionary.

publishCapabilities

protected:

virtual bool publishCapabilities();

Publish Ethernet specific properties to the property table. For instance, getHardwareAddress() is called to fetch the hardware address. This method is called by the superclass and should not be called by drivers.

requestHandler

public:

virtual IOReturn requestHandler(OSObject * sender,
 UInt32 request,
 void * arg0 = 0,
 void * arg1 = 0,
 void * arg2 = 0,
 void * arg3 = 0);

Overrides the requestHandler() inherited from IONetworkController to handle Ethernet specific requests sent from our clients. Requests not handled are passed to the superclass.

Parameters

Name	Description
sender	The sender of the request.
request	The request type.
arg0	Request argument.
arg1	Request argument.
arg2	Request argument.
arg3	Request argument.

setHardwareAddress

protected:

virtual IOReturn setHardwareAddress(const enet_addr_t * addr);

Called when a client wishes to change the station address used by the controller's hardware filter. Implementation of this method is optional.

Parameters

Name	Description
addr	Pointer to a enet_addr_t containing the new Ethernet address.

setMulticastList

protected:

virtual IOReturn setMulticastList(enet_addr_t * addrs, UInt count);

Called when the list of multicast addresses in the interface object attached to the controller is changed. Drivers that supports multicasting should override this method and update the hardware filter using the provided address list. A count of the number of addresses in the list is also provided. This count will be zero when the list becomes empty. Perfect multicast filtering is preferred if supported by the hardware. If the number of multicast addresses in the list exceed the limit imposed by the hardware, or if perfect filtering is not supported, then ideally the hardware should be programmed to perform imperfect filtering, perhaps through a hash table built by the driver. This method may be called only if getPacketFilters() reports that kIOPacketFilterMulticast is supported.

Parameters

Name	Description
addrs	Pointer to a list of multicast addresses.
count	The number of multicast addresses in the list. May be zero if the list becomes empty.

setMulticastMode

protected:

virtual IOReturn setMulticastMode(IOEnetMulticastMode mode);

Called by enablePacketFilters() when the controller's multicast filter mode should be changed. See IOEnetMulticastMode for the list of defined modes.

Parameters

Name	Description
mode	The multicast filter should be programmed to the mode specified.

setPromiscuousMode

protected:

virtual IOReturn setPromiscuousMode(IOEnetPromiscuousMode mode);

Called by enablePacketFilters() when the controller's promiscuous filter mode should be changed. See IOEnetPromiscuousMode for the list of defined modes.

Parameters

Name	Description
mode	The promiscuous filter should be programmed to the mode specified.

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

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

Member Functions

controllerDidOpen

protected:

virtual bool controllerDidOpen(IONetworkController * controller);

This method will be called by our superclass after a network controller has accepted an open from this interface. IOEthernetInterface uses this method to qualify the controller and to cache certain controller properties, such as its hardware address, and its set of supported packet filters.

Parameters

Name	Description
controller	The controller object.

controllerWillClose

protected:

virtual void controllerWillClose(IONetworkController * controller);

When the last close from our client is received, the interface object will close its controller. But before the controller is closed, this method will be called by our superclass to perform any necessary cleanup. IOEthernetInterface will ensure that the controller is disabled before it is closed.

Parameters

Name	Description
controller	The currently opened controller object.

free

protected:

virtual void free();

Frees the IOEthernetInterface instance. The memory allocated for the arpcom structure is released.

getIfnet

protected:

virtual struct ifnet * getIfnet() const;

This method returns a pointer to an ifnet structure maintained by the family specific interface. IOEthernetInterface allocates an arpcom structure during initialization, and returns a pointer to this structure when this method is called.

getNamePrefix

public:

virtual const char * getNamePrefix() const;

The name of the interface advertised to the network layer is generated by concatenating the string returned by this method, and an integer unit number assigned by an external entity.

init

public:

virtual bool init(OSDictionary * properties = 0);

Initialize an IOEthernetInterface instance.

Parameters

Name	Description
properties	A property dictionary.

initIfnet

protected:

virtual bool initIfnet(struct ifnet * ifp);

Initialize the ifnet structure. The argument specified is a pointer to an ifnet structure obtained through getIfnet(). IOEthernetInterface will initialize this structure in a manner that is appropriate for Ethernet interfaces, then call super::initIfnet() to allow the superclass to perform family independent initialization.

Parameters

Name	Description
ifp	Pointer to the ifnet structure to be initialized.

performCommand

protected:

virtual SInt performCommand(IONetworkController * controller,
 UInt32 cmd,
 void * arg0,
 void * arg1);

The handler for ioctl commands sent from the network stack. Commands not handled by this method are passed to our superclass. The ioctl commands handled are SIOCSIFADDR, SIOCSIFFLAGS, SIOCADDMULTI, and SIOCDELMULTI.

Parameters

Name	Description
controller	Our controller object.
cmd	The command code.
arg0	Command argument.
arg1	Command argument.

publishParameters

public:

virtual void publishParameters(OSDictionary * dict) const;

Add Ethernet specific IONetworkParameter objects to the dictionary provided.

Parameters

Name	Description
dict	A dictionary containing IONetworkParameter objects.

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

Typedefs

IODot3CollEntry

typedef  struct  {
  UInt32  collFrequencies[16];
}  IODot3CollEntry;

Collision statistics structure.

Fields

Name	Description
collFrequencies	dot3StatsCollFrequencies.

IODot3RxExtraEntry

typedef  struct  {
  UInt32  overruns;
  UInt32  watchdogTimeouts;
  UInt32  frameTooShorts;
  UInt32  collisionErrors;
  UInt32  phyErrors;
  UInt32  timeouts;
  UInt32  interrupts;
  UInt32  resets;
  UInt32  resourceErrors;
}  IODot3RxExtraEntry;

Extra receiver statistics not defined by RFC1650.

Fields

Name	Description
overruns	receiver overruns.
watchdogTimeouts	watchdog timer expirations.
frameTooShorts	runt frames.
collisionErrors	frames damages by late collision.
phyErrors	PHY receive errors.
timeouts	receiver timeouts.
interrupts	receiver interrupts.
resets	receiver resets.
resourceErrors	receiver resource shortages.

IODot3RxExtraEntry

typedef  struct  {
  UInt32  underruns;
  UInt32  jabbers;
  UInt32  phyErrors;
  UInt32  timeouts;
  UInt32  interrupts;
  UInt32  resets;
  UInt32  resourceErrors;
}  IODot3TxExtraEntry;

Extra transmitter statistics not defined by RFC1650.

Fields

Name	Description
underruns	transmit underruns.
jabbers	jabber events.
phyErrors	PHY transmit errors.
timeouts	transmitter timeouts.
interrupts	transmitter interrupts.
resets	transmitter resets.
resourceErrors	transmitter resource shortages.

IODot3StatsEntry

typedef  struct  {
  UInt32  alignmentErrors;
  UInt32  fcsErrors;
  UInt32  singleCollisionFrames;
  UInt32  multipleCollisionFrames;
  UInt32  sqeTestErrors;
  UInt32  deferredTransmissions;
  UInt32  lateCollisions;
  UInt32  excessiveCollisions;
  UInt32  internalMacTransmitErrors;
  UInt32  carrierSenseErrors;
  UInt32  frameTooLongs;
  UInt32  internalMacReceiveErrors;
  UInt32  etherChipSet;
  UInt32  missedFrames;
}  IODot3StatsEntry;

Ethernet MIB statistics structure.

Fields

Name	Description
alignmentErrors	dot3StatsAlignmentErrors.
fcsErrors	dot3StatsFCSErrors.
singleCollisionFrames	dot3StatsSingleCollisionFrames.
multipleCollisionFrames	dot3StatsMultipleCollisionFrames.
sqeTestErrors	dot3StatsSQETestErrors.
deferredTransmissions	dot3StatsDeferredTransmissions.
lateCollisions	dot3StatsLateCollisions.
excessiveCollisions	dot3StatsExcessiveCollisions.
internalMacTransmitErrors	dot3StatsInternalMacTransmitErrors.
carrierSenseErrors	dot3StatsCarrierSenseErrors.
frameTooLongs	dot3StatsFrameTooLongs.
internalMacReceiveErrors	dot3StatsInternalMacReceiveErrors.
etherChipSet	dot3StatsEtherChipSet.
missedFrames	dot3StatsMissedFrames (not in RFC1650).

IOEthernetStats

typedef  struct  {
  IODot3StatsEntry  dot3StatsEntry;
  IODot3CollEntry  dot3CollEntry;
  IODot3RxExtraEntry  dot3RxExtraEntry;
  IODot3TxExtraEntry  dot3TxExtraEntry;  
}  IOEthernetStats;

Aggregate Ethernet statistics structure.

Fields

Name	Description
dot3StatsEntry	IODot3StatsEntry statistics group.
dot3CollEntry	IODot3CollEntry statistics group.
dot3RxExtraEntry	IODot3RxExtraEntry statistics group.
dot3TxExtraEntry	IODot3TxExtraEntry statistics group.

#defines

kIOEthernetStatsKey

#define kIOEthernetStatsKey "IOEthernetStatsKey"

Defines the name of an IONetworkParameter that contains an IOEthernetStats.

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

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

Member Functions

checkForWork

protected:

virtual bool checkForWork() = 0;

This function will be called to request a subclass to check it's internal state for any work to do and then to call out the owner/action.

disable

public:

virtual void disable();

A subclass implementation is expected to respect the enabled state when checkForWork is called.

enable

public:

virtual void enable();

A subclass implementation is expected to respect the enabled state when checkForWork is called. Calling this function will cause the work-loop to be signalled so that a checkForWork is performed.

getAction

public:

virtual IOEventSource::Action getAction() const;

getNext

protected:

virtual IOEventSource *getNext() const;

getWorkLoop

public:

virtual IOWorkLoop *getWorkLoop() const;

init

protected:

virtual bool init(OSObject *owner, IOEventSource::Action action = 0);

Parameters

Name	Description
owner	Owner of this instance of an event source. Used as the first parameter of the action callout. Owner will generally be an OSObject it doesn't have to be as no member functions will be called directly in it. It can just be a refcon for a client routine.
action	Pointer to C call out function. Action is a pointer to a C function that gets called when this event source has outstanding work. It will usually be called by the checkForWork member function. The first parameter of the action call out will always be the owner, this allows C++ member functions to be used as actions. Defaults to 0.

isEnabled

public:

virtual bool isEnabled() const;

onThread

public:

virtual bool onThread() const;

setAction

public:

virtual void setAction(IOEventSource::Action action);

Parameters

Name	Description
action	Pointer to a C function of type IOEventSource::Action.

setNext

protected:

virtual void setNext(IOEventSource *next);

Parameters

Name	Description
next	Pointer to another IOEventSource instance.

setWorkLoop

protected:

virtual void setWorkLoop(IOWorkLoop *workLoop);

Parameters

Name	Description
workLoop	Target work-loop of this event source instance. A subclass of IOWorkLoop that at least reacts to signalWorkAvailable() and onThread functions.

Member Data

Action

public:typedef void (*Action)(OSObject *owner, ...);

Placeholder type for C++ function overloading discrimination. As the all event sources require an action and it has to be stored somewhere and be of some type, this is that type.

Parameters

Name	Description
owner	Target of the function, can be used as a refcon. The owner is set during initialisation. Note if a C++ function was specified this parameter is implicitly the first paramter in the target member function's parameter list.

action

protected:

 Action action;

The action method called when an event has been delivered

enabled

protected:

 bool enabled;

Is this event source enabled to deliver requests to the work-loop.

eventChainNext

protected:

 IOEventSource *eventChainNext;

The next event source in the event chain. nil at end of chain.

owner

protected:

 OSObject *owner;

The owner object called when an event has been delivered.

refcon

protected:

 void *refcon;

What ever the client wants to do, see $link setRefcon.

workLoop

protected:

 IOWorkLoop *workLoop;

What is the work-loop for this event source.

#defines

IOEventSourceAction

#define IOEventSourceAction IOEventSource::Action

Backward compatibilty define for the old non-class scoped type definition. See $link IOEventSource::Action

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

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

Member Functions

disableInterruptOccurred

public:

virtual void disableInterruptOccurred(void *self, IOService *prov, int ind);

filterInterruptEventSource

public:

static IOFilterInterruptEventSource * filterInterruptEventSource(OSObject *owner,
 IOInterruptEventSource::Action action,
 Filter filter,
 IOService *provider,
 int intIndex = 0);

Parameters

Name	Description
owner	Owner/client of this event source.
action	'C' Function to call when something happens.
filter	'C' Function to call when interrupt occurs.
provider	Service that provides interrupts.
intIndex	Defaults to 0.

getFilterAction

public:

virtual Filter getFilterAction() const;

init

public:

virtual bool init(OSObject *owner,
 IOInterruptEventSource::Action action,
 Filter filter,
 IOService *provider,
 int intIndex = 0);

Parameters

Name	Description
owner	Owner/client of this event source.
action	'C' Function to call when something happens.
filter	'C' Function to call in primary interrupt context.
provider	Service that provides interrupts.
intIndex	Interrupt source within provider. Defaults to 0.

normalInterruptOccurred

public:

virtual void normalInterruptOccurred(void *self, IOService *prov, int ind);

Member Data

Filter

public:typedef bool (*Filter)(OSObject *, IOFilterInterruptEventSource *);

C Function pointer to a routine to call when an interrupt occurs.

Parameters

Name	Description
owner	Pointer to the owning/client instance.
sender	Where is the interrupt comming from.

filterAction

protected:

 Filter filterAction;

Filter callout

#defines

IOFilterInterruptAction

#define IOFilterInterruptAction IOFilterInterruptEventSource::Filter

Backward compatibilty define for the old non-class scoped type definition. See $link IOFilterInterruptSource::Filter

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

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

Member Functions

RWCompletion

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

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

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

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

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

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.

constructMediaProperties

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

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

Name	Description
forcible	True to force forgetting of the media object even if tearDown reports that there was an active client.

deleteContext

protected:

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

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

Parameters

Name	Description
cx	A pointer to the context structure to be deleted.

ejectMedia

public:

virtual IOReturn ejectMedia(void);

executeRequest

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

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.

formatMedia

public:

virtual IOReturn formatMedia(UInt64 byteCapacity);

Parameters

Name	Description
byteCapacity	The requested final byte capacity for the formatted media.

getDeviceTypeName

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

public:

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

This function returns the supported byte capacities for the device.

Parameters

Name	Description
capacities	Pointer for returning the list of capacities.
capacitiesMaxCount	The number of capacity values returned in "capacities."

getMediaBlockSize

public:

virtual UInt64 getMediaBlockSize(void) const;

getMediaState

public:

virtual IODrive::IOMediaState getMediaState(void) const;

handleStart

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

Name	Description
provider	A pointer to our provider.

handleStop

public:

virtual void handleStop(IOService * provider);

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

Parameters

Name	Description
provider	A pointer to our provider.

initMediaStates

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

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

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

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.

isMediaEjectable

public:

virtual bool isMediaEjectable(void) const;

isMediaPollExpensive

public:

virtual bool isMediaPollExpensive(void) const;

isMediaPollRequired

public:

virtual bool isMediaPollRequired(void) const;

lockMedia

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

Name	Description
lock	True indicates the media should be locked in the device; False indicates the media should be unlocked.

pollMedia

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

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

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

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

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

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

Name	Description
provider	A pointer to our provider.

showStats

protected:

virtual bool showStats(void);

This method prints debugging statistics maintained by the class.

Present statistics include counts of up and down calls.

tearDown

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

Name	Description
media	A pointer to the IOMedia object from which to initiate teardown.

validateNewMedia

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.

Member Data

_ejectable

protected:

 bool _ejectable; /* software-ejectable */

 /*!
 * @var _lockable
 * True if the media can be locked in the device under software control.
 */
 bool _lockable; /* software lockable in drive */
 /*!
 * @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;

 /* Async IO statistics, usually only useful for debugging. These counters show
 * outstanding IO operations and completions.
 */

 /*!
 * @struct stats
 * A data structure to contain debugging statistics. Each field is a count.
 * @field clientReceived
 * Requests received from our client.
 * @field providerSent
 * Requests sent to our provider.
 * @field providerReject
 * Client requests we rejected without sending to our provider.
 * @field providerCompletionsRcvd
 * Completion calls that have arrived from our provider. 
 * @field clientCompletionsSent
 * Completion calls that have been made to our client.
 * @field clientCompletionsDone
 * Completion calls to the client that have come back to us.
 * This count MUST match clientCompletionsSent!
 */
 /*!
 * @var stats
 * The stats structure.
 */
 struct stats { /* executeRequest & completion counts */
 int clientReceived; /* requests received from client */
 int providerSent; /* requests sent to provider */
 int providerReject; /* provider requests rejected */
 int providerCompletionsRcvd; /* completions received from provider */
 int clientCompletionsSent; /* completions sent to client */
 int clientCompletionsDone; /* client completions made it back to us */
 } _stats;
 
 /* Media info and states: */

 /*!
 * @var _mediaObject
 * A pointer to the media object we have instantiated (if any).
 */
 IOMedia * _mediaObject;
 /*!
 * @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;
 
 /*!
 * @var _mediaStateLock
 * A lock used to protect during media checks.
 */
 IOLock * _mediaStateLock;

 /*!
 * @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;
};

True if the media is ejectable under software control.

_provider

protected:

 IOHDDriveNub * _provider;

A pointer to our provider.

_removable

protected:

 bool _removable;

True if the media is removable; False if it is fixed (not removable).

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

#defines

kDeviceTypeHardDisk A character string used for nub matching.

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

Member Functions

doAsyncReadWrite

public:

virtual IOReturn doAsyncReadWrite(IOMemoryDescriptor *buffer,
 UInt32 block,UInt32 nblks,
 gdCompletionFunction action,
 IOService *target,void *param) = 0;

Parameters

Name	Description
buffer	An IOMemoryDescriptor describing the data-transfer buffer. The data direction is contained in the IOMemoryDescriptor. Responsiblity for releasing the descriptor rests with the caller.
block	The starting block number of the data transfer.
nblks	The integral number of blocks to be transferred.
action	The C function called upon completion of the data transfer.
target	The C++ class "this" pointer, passed as an argument to "action."
param	This value is passed as an argument to "action." It is not validated or modified.

doEjectMedia

public:

virtual IOReturn doEjectMedia(void) = 0;

doFormatMedia

public:

virtual IOReturn doFormatMedia(UInt64 byteCapacity) = 0;

The specified byte capacity must be one supported by the device. Supported capacities can be obtained by calling doGetFormatCapacities.

Parameters

Name	Description
byteCapacity	The byte capacity to which the device is to be formatted, if possible.

doGetFormatCapacities

public:

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

This function returns the supported byte capacities for the device.

Parameters

Name	Description
capacities	Pointer for returning the list of capacities.
capacitiesMaxCount	The number of capacity values returned in "capacities."

doLockUnlockMedia

public:

virtual IOReturn doLockUnlockMedia(bool doLock) = 0;

This method should only be called if the media is known to be removable.

Parameters

Name	Description
doLock	True to lock the media, False to unlock.

doSyncReadWrite

public:

virtual IOReturn doSyncReadWrite(IOMemoryDescriptor *buffer,
 UInt32 block,UInt32 nblks) = 0;

Parameters

Name	Description
buffer	An IOMemoryDescriptor describing the data-transfer buffer. The data direction is contained in the IOMemoryDescriptor. Responsiblity for releasing the descriptor rests with the caller.
block	The starting block number of the data transfer.
nblks	The integral number of blocks to be transferred.

doSynchronizeCache

public:

virtual IOReturn doSynchronizeCache(void) = 0;

This method should only be called if the media is writable.

executeCdb

public:

virtual IOReturn executeCdb(struct cdbParams *params) = 0;

This method is provided to allow developers to issue arbitrary commands to the device (via the Transport Driver). Expected uses would include vendor-specific commands to effect password-protection, or for other vendor features.

This method may not be supported by all Transport Drivers. For example, ATA devices do not have a CDB concept; those Transport Drivers will return kIOReturnUnsupported.

Parameters

Name	Description
params	See IOHDTypes.h for the layout of this data structure.

getAdditionalDeviceInfoString

public:

virtual char * getAdditionalDeviceInfoString(void) = 0;

getProductString

public:

virtual char * getProductString(void) = 0;

getRevisionString

public:

virtual char * getRevisionString(void) = 0;

getVendorString

public:

virtual char * getVendorString(void) = 0;

init

public:

virtual bool init(OSDictionary * properties);

This function is overridden so that IOHDDriveNub can set a property, used by IOHDDrive for matching. Since the concrete subclass of IOHDDriveNub can be of any class type, the property is used for matching.

This function is usually not overridden by developers.

reportBlockSize

public:

virtual IOReturn reportBlockSize(UInt64 *blockSize) = 0;

Parameters

Name	Description
blockSize	Pointer to returned block size value.

reportEjectability

public:

virtual IOReturn reportEjectability(bool *isEjectable) = 0;

This method should only be called if the media is known to be removable.

Parameters

Name	Description
isEjectable	Pointer to returned result. True indicates the media is ejectable, False indicates the media cannot be ejected under software control.

reportLockability

public:

virtual IOReturn reportLockability(bool *isLockable) = 0;

This method should only be called if the media is known to be removable.

Parameters

Name	Description
isLockable	Pointer to returned result. True indicates the media can be locked in place; False indicates the media cannot be locked by software.

reportMaxReadTransfer

public:

virtual IOReturn reportMaxReadTransfer(UInt64 blockSize,UInt64 *max) = 0;

Some devices impose a maximum data transfer size. Because this limit may be determined by the size of a block-count field in a command, the limit may depend on the block size of the transfer.

Parameters

Name	Description
blockSize	The block size desired for the transfer.
max	Pointer to returned result.

reportMaxValidBlock

public:

virtual IOReturn reportMaxValidBlock(UInt64 *maxBlock) = 0;

Parameters

Name	Description
maxBlock	Pointer to returned result

reportMaxWriteTransfer

public:

virtual IOReturn reportMaxWriteTransfer(UInt64 blockSize,UInt64 *max) = 0;

Some devices impose a maximum data transfer size. Because this limit may be determined by the size of a block-count field in a command, the limit may depend on the block size of the transfer.

Parameters

Name	Description
blockSize	The block size desired for the transfer.
max	Pointer to returned result.

reportMediaState

public:

virtual IOReturn reportMediaState(bool *mediaPresent,bool *changedState) = 0;

This method reports whether we have media in the drive or not, and whether the state has changed from the previously reported state.

A result of kIOReturnSuccess is always returned if the test for media is successful, regardless of media presence. The mediaPresent result should be used to determine whether media is present or not. A return other than kIOReturnSuccess indicates that the Transport Driver was unable to interrogate the device. In this error case, the outputs mediaState and changedState will *not* be stored.

Parameters

Name	Description
mediaPresent	Pointer to returned media state. True indicates media is present in the device; False indicates no media is present.
changedState	Pointer to returned result. True indicates a change of state since prior calls, False indicates that the state has not changed.

reportPollRequirements

public:

virtual IOReturn reportPollRequirements(bool *pollRequired,
 bool *pollIsExpensive) = 0;

This method reports whether the device must be polled to detect media insertion, and whether a poll is expensive to perform.

The term "expensive" typically implies a device that must be spun-up to detect media, as on a PC floppy. Most devices can detect media inexpensively.

Parameters

Name	Description
pollRequired	Pointer to returned result. True indicates that polling is required; False indicates that polling is not required to detect media.
pollIsExpensive	Pointer to returned result. True indicates that the polling operation is expensive; False indicates that the polling operation is cheap.

reportRemovability

public:

virtual IOReturn reportRemovability(bool *isRemovable) = 0;

This method reports whether the media is removable, but it does not provide detailed information regarding software eject or lock/unlock capability.

Parameters

Name	Description
isRemovable	Pointer to returned result. True indicates that the media is removable; False indicates the media is not removable.

reportWriteProtection

public:

virtual IOReturn reportWriteProtection(bool *isWriteProtected) = 0;

Parameters

Name	Description
isWriteProtected	Pointer to returned result. True indicates that the media is write-protected (it cannot be written); False indicates that the media is not write-protected (it is permissible to write).

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

Typedefs

gdCompletionFunction

typedef void (*gdCompletionFunction)( 
            IOService	*target,
            void	*param,
            UInt64	actualByteCount,
            IOReturn	result);

Type and arguments of callout C function that is used to complete an asynchronous IO operation.

Parameters

Name	Description
target	The target C function to be called.
param	A parameter passed to the target C function. It is not validated or changed.
actualByteCount	The actual byte count transferred in the operation.
result	The kIOReturn value from the operation

Structs

cdbParams

struct  cdbParams  {
  UInt32  cdbLength;
  UInt8  cdb[16];
  UInt32  senseLength;
  UInt32  actualSenseLength;
  IOMemoryDescriptor  *  senseBuffer;
  UInt32  timeoutSeconds;
  UInt32  dataLength;
  UInt32  actualDataLength;
  IOMemoryDescriptor  *  dataBuffer;
  UInt8  status;
};

Data provided by a client to an executeCDB operation.

Fields

Name	Description
cdbLength	The length of the command bytes (cdb), in bytes.
cdb	The actual command bytes to be sent to the device. These are not checked by the driver.
senseLength	The requested maximum sense length, in bytes.
actualSenseLength	The actual number of sense bytes transferred. If the driver does not support autosense, this field will always return zero.
senseBuffer	The buffer for the sense data. This buffer must have already been prepared for IO by the caller. The buffer must contain the data direction.
timeoutSeconds	The timeout for the command, in seconds.
dataLength	The requested number of data bytes to transfer with the command, or zero if no data is to be transferred.
actualDataLength	The actual number of data bytes transferred.
dataBuffer	The buffer for the data. This buffer must have already been prepared for IO by the caller. The buffer must contain the data direction.
status	The status reported by the device at command completion. The contents of thisfield will depend on the type of transport (e.g. SCSI, ATAPI, etc). Some drivers may not support the return of status information and will zero this field.

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

Functions

HIDCloseReportDescriptor

extern OSStatus HIDCloseReportDescriptor(HIDPreparsedDataRef preparsedDataRef);

Parameters

Name	Description
hidReportDescriptor	Contains a pointer to the actual HID report descriptor from the USB device's firmware
preparsedDataRef	Preparsed data reference for the report that is returned by the HIDOpenReportDescriptor function. After making a call to the HIDCloseReportDescriptor function, the preparsedDataRef is invalid and should not be used.

HIDGetButtonCaps

extern OSStatus HIDGetButtonCaps(HIDReportType reportType,
 HIDButtonCapsPtr buttonCaps,
 UInt32 * buttonCapsSize,
 HIDPreparsedDataRef preparsedDataRef);

Parameters

Name	Description
reportType	Specifies the type of report for which to retrieve the scaled value. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport
buttonCaps	Points to a caller-allocated buffer that will contain, on return, an array of HIDButtonCaps structures. The structures contain information for all buttons that meet the search criteria
buttonCapsSize	Contains the size of the buttonCaps array passed in to the function and is set to the number of elements actually placed in the array after the call completes.
preparsedDataRef	Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

HIDGetButtons

extern OSStatus HIDGetButtons(HIDReportType reportType,
 UInt32 collection,
 HIDUsageAndPagePtr usageList,
 UInt32 * usageListSize,
 HIDPreparsedDataRef preparsedDataRef,
 void * report,
 ByteCount reportLength);

Parameters

Name	Description
reportType	Specifies the type of report, provided in the report parameter, from which to retrieve the buttons. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport or kHIDFeatureReport
collection	Optionally specifies the link collection identifier used to retrieve only specific button states. If this value is non-zero, only the buttons that are part of the given collection are returned.
usageList	On return, points to a caller-allocated buffer that contains the usages of all the buttons that are pressed.
usageListSize	Is the size, in array elements, of the buffer provided in the usageList parameter. On return, this parameter contains the number of button states that were set by this routine. If the error kHIDBufferToSmallErr was returned, this parameter contains the number of array elements required to hold all button data requested. The maximum number of buttons that can ever be returned for a given type of report can be obtained by calling the HIDMaxUsageListLength function.
preparsedDataRef	Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function
report	Points to the caller-allocated buffer that contains the device report data.
reportLength	Specifies the length, in bytes, of the report data provided in the report parameter.

HIDGetButtonsOnPage

extern OSStatus HIDGetButtonsOnPage(HIDReportType reportType,
 HIDUsage usagePage,
 UInt32 collection,
 HIDUsage * usageList,
 UInt32 * usageListSize,
 HIDPreparsedDataRef preparsedDataRef,
 void * report,
 ByteCount reportLength);

Parameters

Name	Description
reportType	Specifies the type of report, provided in the report parameter, from which to retrieve the buttons. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport or kHIDFeatureReport.
usagePage	Specifies the usage page of the buttons for which to retrieve the current state.
collection	Optionally specifies the link collection identifier used to retrieve only specific button states. If this value is non-zero, only the buttons that are part of the given collection are returned.
usageList	On return, points to a caller-allocated buffer that contains the usages of all the buttons that are perssed and belong to the usage page specified in the usagePage parameter.
usageListSize	Is the size, in array elements, of the buffer provided in the usageList parameter. On return, this parameter contains the number of button states that were set by this routine. If the error kHIDBufferTooSmallErr was returned, this parameter contains the number of array elements required to hold all button data requested. The maximum number of buttons that can ever be returned for a given type of report can be obtained by calling the HIDMaxUsageListLength function.
preparsedDataRef	Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function
report	Points to the caller-allocated buffer that contains the device report data
reportLength	Specifies the size, in bytes, of the report data provided in the report parameter

HIDGetCaps

extern OSStatus HIDGetCaps(HIDPreparsedDataRef preparsedDataRef,
 HIDCapsPtr capabilities);

Parameters

Name	Description
preparsedDataRef	Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function
capabilities	Points to a caller allocated buffer, that upon return contains the parsed capability information for this HID device.

HIDGetCollectionNodes

extern OSStatus HIDGetCollectionNodes(HIDCollectionNodePtr collectionNodes,
 UInt32 * collectionNodesSize,
 HIDPreparsedDataRef preparsedDataRef);

The length of the buffer required, in array elements, for an entire collection node array is found in the HIDCaps structure member numberCollectionNodes. You obtain the HIDCaps information by calling the HIDGetCaps function. For information on the relationships of link collections described by the data returned from this routine, see the descripton of the HIDCollectionNode structure.

Parameters

Name	Description
collectionNodes	Points to a caller-allocated array of HIDCollectionNode structures in which this routine returns an entry for each collection within the top level collection. A collection is a group of corresponding HID descriptors containing input, output, and feature items that have some common relationship to one another. For example, a pointer collection contains items for x and y position data, and button data.
collectionNodesSize	On input, specifies the length in array elements of the buffer provided at collectionNodes. On output, this parameter is set to the number of entries in the collectionNodes array that were initialized.
preparsedDataRef	Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

HIDGetScaledUsageValue

extern OSStatus HIDGetScaledUsageValue(HIDReportType reportType,
 HIDUsage usagePage,
 UInt32 collection,
 HIDUsage usage,
 SInt32 * usageValue,
 HIDPreparsedDataRef preparsedDataRef,
 void * report,
 ByteCount reportLength);

Clients who which to obtain all capabilities for a usage that contains multiple data items for a single usage that corresponds to a HID byte array, must call the HIDGetUsageValueArray function.

Parameters

Name	Description
reportType	Specifies the type of report for which to retrieve the scaled value. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.
usagePage	Specifies the usage page of the value to be retrieved.
collection	Optionally specifies the link collection identifier of the value to be retrieved.
usage	Specifies the usage of the scaled value to be retrieved.
usageValue	Points to a variable, that on return from this routine holds the scaled value retrieved from the device report.
preparsedDataRef	Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function
report	Points to the caller-allocated buffer that contains the device report data
reportLength	Specifies the length, in bytes, of the report data provided at report

HIDGetSpecificButtonCaps

extern OSStatus HIDGetSpecificButtonCaps(HIDReportType reportType,
 HIDUsage usagePage,
 UInt32 collection,
 HIDUsage usage,
 HIDButtonCapsPtr buttonCaps,
 UInt32 * buttonCapsSize,
 HIDPreparsedDataRef preparsedDataRef);

The HIDGetSpecificButtonCaps function retrieves capability data for buttons that meet a given search criteria, as opposed to the HIDGetButtonCaps function which returns the capability data for all buttons on the device. Calling this routine specifying zero for usagePage, usage and collection is equivalent to calling the HIDGetButtonCaps function.

Parameters

Name	Description
reportType	Specifies the type of report for which to retrieve the button capabilities. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.
usagePage	Specifies a usage page identifier to use as a search criteria. If this parameter is non-zero, then only buttons that specify this usage page will be retrieved.
collection	Specifies a link collection identifier to use as a search criteria. If this parameter is non-zero, then only buttons that are part of the specified link collection are retrieved.
usage	Specifies a usage identifier to use as a search criteria. If this parameter is non-zero, then only buttons that match the value specified are retrieved.
buttonCaps	Points to a caller-allocated buffer that will contain, on return, an array of HIDButtonCaps structures. The structures contain information for all buttons that meet the search criteria.
buttonCapsLength	On input, specifies the length, in array elements, of the buffer provided in the buttonCaps parameter. On output, this parameter is set to the actual number of elements that were returned by the function call, in the buffer provided in the buttonCaps parameter, if the routine completed without error. The correct length necessary to retrieve the button capabilities can be found in the capability data returned for the device by the HIDGetCaps function.
preparsedDataRef	Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

HIDGetSpecificValueCaps

extern OSStatus HIDGetSpecificValueCaps(HIDReportType reportType,
 HIDUsage usagePage,
 UInt32 collection,
 HIDUsage usage,
 HIDValueCapsPtr valueCaps,
 UInt32 * valueCapsSize,
 HIDPreparsedDataRef preparsedDataRef);

The HIDGetSpecificValueCaps function retrieves capability data for values that meet given search criteria, as opposed to the HIDGetValueCaps function, which returns the capability data for all values on the device. Calling this routine with a value of zero for usagePage, usage and collection parameters is equivalent to calling the HIDGetValueCaps function.

Parameters

Name	Description
reportType	Specifies the type of report for which to retrieve the value capabilities. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport or kHIDFeatureReport.
usagePage	Specifies a usage page identifier to use as a search criteria. If this parameter is non-zero, then only values that specify this usage page will be retrieved.
collection	Specifies a link collection identifier to use as a search criteria. If this parameter is non-zero, then only values that are part of this link collection will be retrieved.
usage	Specifies a usage identifier to use as a search criteria. If this parameter is non-zero, then only values that specify this usage will be retrieved.
valueCaps	Points to a caller-allocated buffer that will contain, on return, an array of HIDValueCaps structures that contain information for all values that meet the search criteria.
valueCapsLength	Specifies the length on input, in array elements, of the buffer provided in the valueCaps parameter. On output, this parameter is set to the actual number of elements that were returned by this function call, in the buffer provided in the valueCaps parameter, if the routine completed without error. The correct length necessary to retrieve the value capabilities can be found in the capability data returned for the device from the HIDGetCaps function.
preparsedDataRef	Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

HIDGetUsageValue

extern OSStatus HIDGetUsageValue(HIDReportType reportType,
 HIDUsage usagePage,
 UInt32 collection,
 HIDUsage usage,
 SInt32 * usageValue,
 HIDPreparsedDataRef preparsedDataRef,
 void * report,
 ByteCount reportLength);

The HIDGetUsageValue function does not sign the value. To have the sign bit automatically applied, use the HIDGetScaledUsageValue function instead. For manually assigning the sign bit, the position of the sign bit can be found in the HIDValueCaps structure for this value. Clients who wish to obtain all data for a usage that contains multiple data items for a single usage, corresponding to a HID byte array, must call the HIDGetUsageValueArray function instead.

Parameters

Name	Description
reportType	Specifies the type of report, provided in report, from which to retrieve the value. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.
usagePage	Specifies the usage page of the value to retrieve.
collection	Optionally specifies the link collection identifier of the value to be retrieved.
usage	Specifies the usage of the value to be retrieved.
usageValue	Points to a variable, that on return from this routine holds the value retrieved from the device report.
preparsedDataRef	Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function
report	Points to the caller-allocated buffer that contains the device report data.
reportLength	Specifies the size, in bytes, of the report data provided in the report parameter.

HIDGetUsageValueArray

extern OSStatus HIDGetUsageValueArray(HIDReportType reportType,
 HIDUsage usagePage,
 UInt32 collection,
 HIDUsage usage,
 Byte * usageValueBuffer,
 ByteCount usageValueBufferSize,
 HIDPreparsedDataRef preparsedDataRef,
 void * report,
 ByteCount reportLength);

When the HIDGetUsageValueArray function retrieves the data, it fills in the buffer in little-endian order beginning with the least significant bit of the data for this usage. The data is filled in without regard to byte alignment and is shifted such that the least significant bit is placed as the 1st bit of the given buffer.

Parameters

Name	Description
reportType	Specifies the type of report, provided in report, from which to retrieve the value. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.
usagePage	Specifies the usage page of the data to be retrieved.
collection	Optionally specifies the link collection identifier of the data to be retrieved.
usage	Specifies the usage identifier of the value to be retrieved.
usageValueBuffer	Points to a caller-allocated buffer that contains, on output, the data from the device. The correct length for this buffer can be found by multiplying the reportCount and bitSize fields of the HIDValueCaps structure for the value and rounding the resulting value up to the nearest byte.
usageValueBufferSize	Specifies the size, in bytes, of the buffer in the usageValueBuffer parameter.
preparsedDataRef	Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function
report	Points to the caller-allocated buffer that contains the device report data.
reportLength	Specifies the size, in bytes, of the report data provided in report.

HIDGetValueCaps

extern OSStatus HIDGetValueCaps(HIDReportType reportType,
 HIDValueCapsPtr valueCaps,
 UInt32 * valueCapsSize,
 HIDPreparsedDataRef preparsedDataRef);

The HIDGetValueCaps function retrieves the capability data for all values in a top level collection without regard for the usage, usage page or collection of the value. To retrieve value capabilities for a specific usage, usage page or collection, use the HIDGetSpecificValueCaps function.

Parameters

Name	Description
reportType	Specifies the type of report for which to retrieve the value capabilities. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.
valueCaps	On return, points to a caller-allocated buffer that contains an array of HIDValueCaps structures containing information for all values in the top level collection.
valueCapsSize	On input, specifies the size in array elements of the buffer provided in the valueCaps parameter. On output, this parameter is set to the actual number of elements that were returned in the buffer provided in the valueCaps parameter, if the function completed without error. The correct length necessary to retrieve the value capabilities can be found in the capability data returned for the device by the HIDGetCaps function.
preparsedDataRef	Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

HIDMaxUsageListLength

extern UInt32 HIDMaxUsageListLength(HIDReportType reportType,
 HIDUsage usagePage,
 HIDPreparsedDataRef preparsedDataRef);

Parameters

Name	Description
reportType	Specifies the type of report for which to get a maximum usage count. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.
usagePage	Optionally specifies the usage page identifier to use as a search criteria. If this parameter is zero, the function returns the number of buttons for the entire top-level collection regardless of the actual value of the usage page.
preparsedDataRef	Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function

HIDOpenReportDescriptor

extern OSStatus HIDOpenReportDescriptor(void * hidReportDescriptor,
 ByteCount descriptorLength,
 HIDPreparsedDataRef * preparsedDataRef,
 UInt32 flags);

When the parsed information is no longer needed, clients should call the HIDCloseReportDescriptor function.

Parameters

Name	Description
hidReportDescriptor	Contains a pointer to the actual HID report descriptor from the USB device's firmware
descriptorLength	The length of the HID report descriptor
preparsedDataRef	Preparsed data reference to be used for subsequent function calls
flags	Flags for this runction are kHIDFlag_StrictErrorChecking = 0x00000001

HIDSetButton

extern OSStatus HIDSetButton(HIDReportType reportType,
 HIDUsage usagePage,
 UInt32 collection,
 HIDUsage usage,
 HIDPreparsedDataRef preparsedDataRef,
 void * report,
 ByteCount reportLength);

Parameters

Name	Description
reportType	Specifies the type of report. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.
usagePage	Specifies the usage page identifier of the value to be set in the report.
collection	Optionally specifies the link collection identifier to distinguish between buttons. If this parameter is zero, it is ignored.
usage	Points to a caller-allocated buffer that contains the button data to be set in the report in the report parameter.
preparsedDataRef	Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function
report	Points to the caller-allocated buffer that contains the device report data.
reportLength	Specifies the size, in bytes, of the report data provided in the report parameter.

HIDSetButtons

extern OSStatus HIDSetButtons(HIDReportType reportType,
 HIDUsage usagePage,
 UInt32 collection,
 HIDUsage * usageList,
 UInt32 * usageListSize,
 HIDPreparsedDataRef preparsedDataRef,
 void * report,
 ByteCount reportLength);

Parameters

Name	Description
reportType	Specifies the type of repor. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.
usagePage	Specifies the usage page identifier of the value to be set in the report.
collection	Optionally specifies the link collection identifier to distinguish between buttons. If this parameter is zero, it is ignored.
usageList	Points to a caller-allocated buffer that contains an array of button data to be set in the report in the report parameter.
usageListSize	Specifies the size, in array elements, of the buffer provided in the usageList parameter. If an error is returned by a call to this function, the usageListLength parameter contains the location in the array provided in the usageList parameter where the error was encountered. All array entries encountered prior to the error location were successfully set in the report provided in the report parameter.
preparsedDataRef	Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function
report	Points to the caller-allocated buffer that contains the device report data.
reportLength	Specifies the size, in bytes, of the report data provided in the report parameter.

HIDSetScaledUsageValue

extern OSStatus HIDSetScaledUsageValue(HIDReportType reportType,
 HIDUsage usagePage,
 UInt32 collection,
 HIDUsage usage,
 SInt32 usageValue,
 HIDPreparsedDataRef preparsedDataRef,
 void * report,
 ByteCount reportLength);

The HIDSetScaledUsageValue function automatically handles the setting of the signed bit in the data to be sent to the device.

Parameters

Name	Description
reportType	Specifies the type of report. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.
usagePage	Specifies the usage page identifier of the value to be set in the report.
collection	Optionally specifies the link collection identifier to distinguish between values that have the same usage page and usage identifiers. If this parameter is zero, it will be ignored.
usage	Specifies the usage identifier of the value to be set in the report.
usageValue	Specifies the physical, or scaled, value to be set in the value for the given report.
preparsedDataRef	Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function
report	Points to the caller-allocated buffer that contains the device report data.
Specifies	the length, in bytes of the report data specified in the report parameter.

HIDSetUsageValue

extern OSStatus HIDSetUsageValue(HIDReportType reportType,
 HIDUsage usagePage,
 UInt32 collection,
 HIDUsage usage,
 SInt32 usageValue,
 HIDPreparsedDataRef preparsedDataRef,
 void * report,
 ByteCount reportLength);

The HIDSetUsageVlaue function does not automatically handle the sign bit. Clients must either manually set the sign bit, at the position provided in the HIDValueCaps structure for this value, or call the HIDSetScaledUsageValue function.

Parameters

Name	Description
reportType	Specifies the type of report. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.
usagePage	Specifies the usage page identifier of the value to be set in the report.
collection	Optionally specifies the link collection identifier to distinguish between values that have the same usage page and usage identifiers. If this parameter is zero, it is ignored.
usage	Specifies the usage identifier of the value to be set in the report.
usageValue	Specifies the data that is to be set in the value for the given report.
preparsedDataRef	Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function
report	Points to the caller-allocated buffer that contains the device report data.
reportLength	Specifies the size, in bytes, of the report data provided in the report parameter.

HIDSetUsageValueArray

extern OSStatus HIDSetUsageValueArray(HIDReportType reportType,
 HIDUsage usagePage,
 UInt32 collection,
 HIDUsage usage,
 Byte * usageValueBuffer,
 ByteCount usageValueBufferLength,
 HIDPreparsedDataRef preparsedDataRef,
 void * report,
 ByteCount reportLength);

The HIDSetUsageValue function does not automatically handle the sign bit. Clients must either manually set the sign bit, at the position provided in the HIDValueCaps structure for this value, or call the HIDSetScaledUsageValue function.

Parameters

Name	Description
reportType	Specifies the type of report. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport.
usagePage	Specifies the usage page identifier of the value to be set in the report.
collection	Optionally specifies the link collection identifier to distinguish between values that have the same usage page and usage identifiers. If this parameter is zero, it is ignored.
usage	Specifies the usage identifier of the value to be set in the report.
usageValueBuffer	Points to a caller-allocated buffer that contains, on output, the data from the device. The correct length for this buffer can be found by multiplying the reportCount and bitSize fields of the HIDValueCaps structure for this value and rounding the resulting value up to the nearest byte.
usageValueBufferLength	Specifies the size, in bytes, of the buffer in the usageValueBuffer parameter.
preparsedDataRef	Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function
report	Points to the caller-allocated buffer that contains the device report data.
reportLength	Specifies the size, in bytes, of the report data provided in the report parameter.

HIDUsageListDifference

extern OSStatus HIDUsageListDifference(HIDUsage * previousUsageList,
 HIDUsage * currentUsageList,
 HIDUsage * breakUsageList,
 HIDUsage * makeUsageList,
 UInt32 usageListsSize);

Parameters

Name	Description
previousUsageList	Points to the older button list to be used for comparison.
currentUsageList	Points to the newer button list to be used for comparison.
breakUsageList	On return, points to a caller-allocated buffer that contains the buttons set in the older list, specified in the previousUsageList parameter, but not set in the new list, specified in the currentUsageList parameter.
makeUsageList	On return, points to a caller-allocated buffer that contains the buttons set in the new list, specified in the currentUsageList parameter, but not set in the old list, specified in the previousUsageList parameter.
usageListsLength	Specifies the length, in array elements, of the buffers provided in the currentUsageList and previousUssageList parameters.

Typedefs

HIDCaps

struct  HIDCaps
{
  HIDUsage  usage;
  HIDUsage  usagePage;
  ByteCount  inputReportByteLength;
  ByteCount  outputReportByteLength;
  ByteCount  featureReportByteLength;
  UInt32  numberCollectionNodes;
  UInt32  numberInputButtonCaps;
  UInt32  numberInputValueCaps;
  UInt32  numberOutputButtonCaps;
  UInt32  numberOutputValueCaps;
  UInt32  numberFeatureButtonCaps;
  UInt32  numberFeatureValueCaps;
};
typedef  struct  HIDCaps  HIDCaps,  *  HIDCapsPtr;

This structure holds the parsed capabilities and data maximums returned for a device by the HIDGetCaps function.

Fields

Name	Description
usage	Specifies the specific class of functionality that this device provides. This value is dependent and specific to the value provided in the usagePage field. For example, a keyboard could have a usagePage of kHIDUsagePage_Generic and a usage of kHIDUsage_Generic_Keyboard.
usagePage	Specifies the usage page identifier for this top level collection.
inputReportByteLength	Specifies the maximum length, in bytes, of an input report for this device, including the report ID which is unilaterally prepended to the device data.
outputReportByteLength	Specifies the maximum length, in bytes, of an output report for this device, including the report ID which is unilaterally prepended to the device data.
featureReportByteLength	Specifies the maximum length, in bytes, of a feature report for this device, including the report ID which is unilaterally prepended to the device data.
numberCollectionNodes	Specifies the number of HIDCollectionNode structures that are returned for this top level collection by the HIDGetConnectionNodes function.
numberInputButtonCaps	Specifies the number of input buttons.
numberInputValueCaps	Specifies the number of input values.
numberOutputButtonCaps	Specifies the number of output buttons.
numberOutputValueCaps	Specifies the number of output values
numberFeatureButtonCaps	Specifies the number of feature buttons.
numberFeatureValueCaps	Specifies the number of feature values.

HIDUsageAndPage

struct  HIDUsageAndPage
{
  HIDUsage  usage;
  HIDUsage  usagePage;
};
typedef  struct  HIDUsageAndPage  HIDUsageAndPage,  *HIDUsageAndPagePtr;

Clients use the HIDUSageAndPage structure with the HIDGetButtonsEx function to obtain both the usage page and usage identifiers of each button that is down.

Fields

Name	Description
usage	Specifies the usage identifier within the usage page specified by usagePage of a button that is down.
usagePage	Specifies the usage page identifier of a button that is down.

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

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

Member Functions

checkForWork

protected:

virtual bool checkForWork();

This function called when the work-loop is ready to check for any work to do and then to call out the owner/action.

disable

public:

virtual void disable();

A subclass implementation is expected to respect the enabled state when checkForWork is called.

disableInterruptOccurred

public:

virtual void disableInterruptOccurred(void *, IOService *nub, int ind);

Parameters

Name	Description
nub	Where did the interrupt originate from
ind	What is this interrupts index within 'nub'.

enable

public:

virtual void enable();

A subclass implementation is expected to respect the enabled state when checkForWork is called. Calling this function will cause the work-loop to be signalled so that a checkForWork is performed.

free

protected:

virtual void free();

getAutoDisable

public:

virtual bool getAutoDisable() const;

getIntIndex

public:

virtual int getIntIndex() const;

getProvider

public:

virtual const IOService *getProvider() const;

init

public:

virtual bool init(OSObject *owner,
 Action action,
 IOService *provider = 0,
 int intIndex = 0);

Parameters

Name	Description
owner	Owning client of the new event source.
action	'C' Function to call when something happens.
provider	IOService that represents the interrupt source. Defaults to 0. When no provider is defined the event source assumes that the client will in some manner call the interruptOccured method explicitly. This will start the ball rolling for safe delivery of asynchronous event's into the driver.
intIndex	The index of the interrupt within the provider's interrupt sources. Defaults to 0, i.e. the first interrupt in the provider.

interruptEventSource

public:

static IOInterruptEventSource * interruptEventSource(OSObject *owner,
 Action action,
 IOService *provider = 0,
 int intIndex = 0);

Parameters

Name	Description
owner	Owning client of the new event source.
action	'C' Function to call when something happens.
provider	IOService that represents the interrupt source. Defaults to 0. When no provider is defined the event source assumes that the client will in some manner call the interruptOccured method explicitly. This will start the ball rolling for safe delivery of asynchronous event's into the driver.
intIndex	The index of the interrupt within the provider's interrupt sources. Defaults to 0, i.e. the first interrupt in the provider.

interruptOccurred

public:

virtual void interruptOccurred(void *, IOService *nub, int ind);

Parameters

Name	Description
nub	Where did the interrupt originate from
ind	What is this interrupts index within 'nub'.

normalInterruptOccurred

public:

virtual void normalInterruptOccurred(void *, IOService *nub, int ind);

Parameters

Name	Description
nub	Where did the interrupt originate from
ind	What is this interrupts index within 'nub'.

Member Data

Action

public:typedef void (*Action)(OSObject *, IOInterruptEventSource *, int count);

'C' pointer prototype of functions that are called in a single threaded context when an interrupt occurs.

Parameters

Name	Description
owner	Pointer to client instance.
sender	Pointer to generation interrupt event source.
count	Number of interrupts seen before delivery.

autoDisable

protected:

 bool autoDisable;

Do we need to automatically disable the interrupt source when we take an interrupt, i.e. we are level triggered.

consumerCount

protected:

 unsigned int consumerCount;

Current count of produced interrupts that the owner has been informed of.

explicitDisable

protected:

 bool explicitDisable;

Has the user expicitly disabled this event source, if so then do not overide their request when returning from the callout

intIndex

protected:

 int intIndex;

producerCount

protected:

 volatile unsigned int producerCount;

Current count of produced interrupts that have been received.

provider

protected:

 IOService *provider;

IOService that provides interrupts for delivery.

#defines

IOInterruptEventAction

#define IOInterruptEventAction IOInterruptEventSource::Action

Backward compatibilty define for the old non-class scoped type definition. See $link IOInterruptEventSource::Action

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

Functions

Debugger

void Debugger(const char * reason);

This function freezes the kernel and enters the builtin debugger. It may not be possible to exit the debugger without a second machine.

Parameters

Name	Description
reason	A C-string to describe why the debugger is being entered.

IOCreateThread

IOThread IOCreateThread(IOThreadFunc function, void *argument);

This function creates a kernel thread, and passes the caller supplied argument to the new thread.

Parameters

Name	Description
function	A C-function pointer where the thread will begin execution.
argument	Caller specified data to be passed to the new thread.

IODelay

void IODelay(unsigned microseconds);

This function spins to delay for at least the number of specified microseconds. Since the CPU is busy spinning no time is made available to other processes; this method of delay should be used only for short periods. Also, the AbsoluteTime based APIs of kern/clock.h provide finer grained and lower cost delays.

Parameters

Name	Description
microseconds	The integer number of microseconds to spin wait.

IOExitThread

volatile void IOExitThread();

This function destroys the currently running thread, and does not return.

IOFlushProcessorCache

IOReturn IOFlushProcessorCache( task_t task, IOVirtualAddress address,
 IOByteCount length );

This function flushes the processor cache of an already mapped memory range. Note in most cases it is preferable to use IOMemoryDescriptor::prepare and complete to manage cache coherency since they are aware of the architecture's requirements. Flushing the processor cache is not required for coherency in most situations.

Parameters

Name	Description
task	Task the memory is mapped into.
address	Virtual address of the memory.
length	Length of the range to set.

IOFree

void IOFree(void * address, vm_size_t size);

This function frees memory allocated with IOMalloc, it may block and so should not be called from interrupt level or while a simple lock is held.

Parameters

Name	Description
address	Pointer to the allocated memory.
size	Size of the memory allocated.

IOFreeAligned

void IOFreeAligned(void * address, vm_size_t size);

This function frees memory allocated with IOMallocAligned, it may block and so should not be called from interrupt level or while a simple lock is held.

Parameters

Name	Description
address	Pointer to the allocated memory.
size	Size of the memory allocated.

IOFreeContiguous

void IOFreeContiguous(void * address, vm_size_t size);

This function frees memory allocated with IOMallocContiguous, it may block and so should not be called from interrupt level or while a simple lock is held.

Parameters

Name	Description
address	Virtual address of the allocated memory.
size	Size of the memory allocated.

IOLog

void IOLog(const char *format, ...)
__attribute__((format(printf, 1, 2)));

This function allows a driver to log diagnostic information to the screen during verbose boots, and to a log file found at /var/log/system.log. IOLog should not be called from interrupt context.

Parameters

Name	Description
format	A printf() style format string (see printf() documentation).
other	arguments described by the format string.

IOMalloc

void * IOMalloc(vm_size_t size);

This is a general purpose utility to allocate memory in the kernel. There are no alignment guarantees given on the returned memory, and alignment may vary depending on the kernel configuration. This function may block and so should not be called from interrupt level or while a simple lock is held.

Parameters

Name	Description
size	Size of the memory requested.

IOMallocAligned

void * IOMallocAligned(vm_size_t size, vm_offset_t alignment);

This is a utility to allocate memory in the kernel, with an alignment restriction which is specified as a byte count. This function may block and so should not be called from interrupt level or while a simple lock is held.

Parameters

Name	Description
size	Size of the memory requested.
alignment	Byte count of the alignment for the memory. For example, pass 256 to get memory allocated at an address with bit 0-7 zero.

IOMallocContiguous

void * IOMallocContiguous(vm_size_t size, vm_size_t alignment,
 IOPhysicalAddress * physicalAddress);

This is a utility to allocate memory in the kernel, with an alignment restriction which is specified as a byte count, and will allocate only physically contiguous memory. The request may fail if memory is fragmented, and may cause large amounts of paging activity. This function may block and so should not be called from interrupt level or while a simple lock is held.

Parameters

Name	Description
size	Size of the memory requested.
alignment	Byte count of the alignment for the memory. For example, pass 256 to get memory allocated at an address with bits 0-7 zero.
physicalAddress	IOMallocContiguous returns the physical address of the allocated memory here, if physicalAddress is a non-zero pointer.

IOSetProcessorCacheMode

IOReturn IOSetProcessorCacheMode( task_t task, IOVirtualAddress address,
 IOByteCount length, IOOptionBits cacheMode );

This function sets the cache mode of an already mapped & wired memory range. Note this may not be supported on I/O mappings or shared memory - it is far preferable to set the cache mode as mappings are created with the IOMemoryDescriptor::map method.

Parameters

Name	Description
task	Task the memory is mapped into.
address	Virtual address of the memory.
length	Length of the range to set.
cacheMode	A constant from IOTypes.h, kIOMapDefaultCache to inhibit the cache in I/O areas, kIOMapCopybackCache in general purpose RAM. kIOMapInhibitCache, kIOMapWriteThruCache, kIOMapCopybackCache to set the appropriate caching.

IOSleep

void IOSleep(unsigned milliseconds);

This function blocks the calling thread for at least the number of specified milliseconds, giving time to other processes.

Parameters

Name	Description
milliseconds	The integer number of milliseconds to wait.

IOThreadSelf

This function returns the current thread (a pointer to the currently active osfmk thread_shuttle).

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

Functions

IOLockAlloc

IOLock * IOLockAlloc( void );

Allocates an osfmk mutex in general purpose memory, and initilizes it. Mutexes are general purpose blocking mutual exclusion locks, supplied by osfmk/kern/lock.h. This function may block and so should not be called from interrupt level or while a simple lock is held.

IOLockFree

void IOLockFree( IOLock * lock);

Frees a lock allocated with IOLockAlloc. Any blocked waiters will not be woken.

Parameters

Name	Description
lock	Pointer to the allocated lock.

IOLockLock

static __inline__ void IOLockLock( IOLock * lock)
{
 _mutex_lock(lock);

Lock the mutex. If the lock is held by any thread, block waiting for its unlock. This function may block and so should not be called from interrupt level or while a simple lock is held. Locking the mutex recursively from one thread will result in deadlock.

Parameters

Name	Description
lock	Pointer to the allocated lock.

IOLockTryLock

static __inline__ boolean_t IOLockTryLock( IOLock * lock)
{
 return(_mutex_try(lock));

Lock the mutex if it is currently unlocked, and return true. If the lock is held by any thread, return false.

Parameters

Name	Description
lock	Pointer to the allocated lock.

IOLockUnlock

static __inline__ void IOLockUnlock( IOLock * lock)
{
 mutex_unlock(lock);

Unlock the mutex and wake any blocked waiters. Results are undefined if the caller has not locked the mutex. This function may block and so should not be called from interrupt level or while a simple lock is held.

Parameters

Name	Description
lock	Pointer to the allocated lock.

IORWLockAlloc

IORWLock * IORWLockAlloc( void );

Allocates an initializes an osfmk lock_t in general purpose memory, and initilizes it. Read/write locks provide for multiple readers, one exclusive writer, and are supplied by osfmk/kern/lock.h. This function may block and so should not be called from interrupt level or while a simple lock is held.

IORWLockFree

void IORWLockFree( IORWLock * lock);

Frees a lock allocated with IORWLockAlloc. Any blocked waiters will not be woken.

Parameters

Name	Description
lock	Pointer to the allocated lock.

IORWLockRead

static __inline__ void IORWLockRead( IORWLock * lock)
{
 lock_read( lock);

Lock the lock for read, allowing multiple readers when there are no writers. If the lock is held for write, block waiting for its unlock. This function may block and so should not be called from interrupt level or while a simple lock is held. Locking the lock recursively from one thread, for read or write, can result in deadlock.

Parameters

Name	Description
lock	Pointer to the allocated lock.

IORWLockUnlock

static __inline__ void IORWLockUnlock( IORWLock * lock)
{
 lock_done( lock);

Undo one call to IORWLockRead or IORWLockWrite. Results are undefined if the caller has not locked the lock. This function may block and so should not be called from interrupt level or while a simple lock is held.

Parameters

Name	Description
lock	Pointer to the allocated lock.

IORWLockWrite

static __inline__ void IORWLockWrite( IORWLock * lock)
{
 lock_write( lock);

Lock the lock for write, allowing one writer exlusive access. If the lock is held for read or write, block waiting for its unlock. This function may block and so should not be called from interrupt level or while a simple lock is held. Locking the lock recursively from one thread, for read or write, can result in deadlock.

Parameters

Name	Description
lock	Pointer to the allocated lock.

IORecursiveLockAlloc

IORecursiveLock * IORecursiveLockAlloc( void );

Allocates a recursive lock in general purpose memory, and initilizes it. Recursive locks function identically to osfmk mutexes but allow one thread to lock more than once, with balanced unlocks.

IORecursiveLockFree

void IORecursiveLockFree( IORecursiveLock * lock);

Frees a lock allocated with IORecursiveLockAlloc. Any blocked waiters will not be woken.

Parameters

Name	Description
lock	Pointer to the allocated lock.

IORecursiveLockHaveLock

boolean_t IORecursiveLockHaveLock( const IORecursiveLock * lock);

If the lock is held by the calling thread, return true, otherwise the lock is unlocked, or held by another thread and false is returned.

Parameters

Name	Description
lock	Pointer to the allocated lock.

IORecursiveLockLock

void IORecursiveLockLock( IORecursiveLock * lock);

Lock the recursive lock. If the lock is held by another thread, block waiting for its unlock. This function may block and so should not be called from interrupt level or while a simple lock is held. The lock may be taken recursively by the same thread, with a balanced number of calls to IORecursiveLockUnlock.

Parameters

Name	Description
lock	Pointer to the allocated lock.

IORecursiveLockTryLock

boolean_t IORecursiveLockTryLock( IORecursiveLock * lock);

Lock the lock if it is currently unlocked, or held by the calling thread, and return true. If the lock is held by another thread, return false. Successful calls to IORecursiveLockTryLock should be balanced with calls to IORecursiveLockUnlock.

Parameters

Name	Description
lock	Pointer to the allocated lock.

IORecursiveLockUnlock

void IORecursiveLockUnlock( IORecursiveLock * lock);

Undo one call to IORecursiveLockLock, if the lock is now unlocked wake any blocked waiters. Results are undefined if the caller does not balance calls to IORecursiveLockLock with IORecursiveLockUnlock. This function may block and so should not be called from interrupt level or while a simple lock is held.

Parameters

Name	Description
lock	Pointer to the allocated lock.

IOSimpleLockAlloc

IOSimpleLock * IOSimpleLockAlloc( void );

Allocates an initializes an osfmk simple lock in general purpose memory, and initilizes it. Simple locks provide non-blocking mutual exclusion for synchronization between thread context and interrupt context, or for multiprocessor synchronization, and are supplied by osfmk/kern/simple_lock.h. This function may block and so should not be called from interrupt level or while a simple lock is held.

IOSimpleLockFree

void IOSimpleLockFree( IOSimpleLock * lock );

Frees a lock allocated with IOSimpleLockAlloc.

Parameters

Name	Description
lock	Pointer to the lock.

IOSimpleLockInit

void IOSimpleLockInit( IOSimpleLock * lock );

Initialize an embedded osfmk simple lock, to the unlocked state.

Parameters

Name	Description
lock	Pointer to the lock.

IOSimpleLockLock

static __inline__ void IOSimpleLockLock( IOSimpleLock * lock )
{
 simple_lock( lock );

Lock the simple lock. If the lock is held, spin waiting for its unlock. Simple locks disable preemption, cannot be held across any blocking operation, and should be held for very short periods. When used to synchronize between interrupt context and thread context they should be locked with interrupts disabled - IOSimpleLockLockDisableInterrupt() will do both. Locking the lock recursively from one thread will result in deadlock.

Parameters

Name	Description
lock	Pointer to the lock.

IOSimpleLockLockDisableInterrupt

static __inline__ IOInterruptState IOSimpleLockLockDisableInterrupt( IOSimpleLock * lock )
{
 IOInterruptState state = ml_set_interrupts_enabled( false );

Lock the simple lock. If the lock is held, spin waiting for its unlock. Simple locks disable preemption, cannot be held across any blocking operation, and should be held for very short periods. When used to synchronize between interrupt context and thread context they should be locked with interrupts disabled - IOSimpleLockLockDisableInterrupt() will do both. Locking the lock recursively from one thread will result in deadlock.

Parameters

Name	Description
lock	Pointer to the lock.

IOSimpleLockTryLock

static __inline__ boolean_t IOSimpleLockTryLock( IOSimpleLock * lock )
{
 return( simple_lock_try( lock ) );

Lock the simple lock if it is currently unlocked, and return true. If the lock is held, return false. Successful calls to IOSimpleLockTryLock should be balanced with calls to IOSimpleLockUnlock.

Parameters

Name	Description
lock	Pointer to the lock.

IOSimpleLockUnlock

static __inline__ void IOSimpleLockUnlock( IOSimpleLock * lock )
{
 simple_unlock( lock );

Unlock the lock, and restore preemption. Results are undefined if the caller has not locked the lock.

Parameters

Name	Description
lock	Pointer to the lock.

IOSimpleLockUnlockEnableInterrupt

static __inline__ void IOSimpleLockUnlockEnableInterrupt( IOSimpleLock * lock,
 IOInterruptState state )
{
 simple_unlock( lock );

Unlock the lock, and restore preemption and interrupts to the state as they were when the lock was taken. Results are undefined if the caller has not locked the lock.

Parameters

Name	Description
lock	Pointer to the lock.
state	The interrupt state returned by IOSimpleLockLockDisableInterrupt()

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

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

Member Functions

getPhysicalSegments

public:

UInt getPhysicalSegments(struct mbuf * packet,
 struct IOPhysicalSegment * vector,
 UInt numVectorSegments = 0);

Parameters

Name	Description
packet	The mbuf packet.
vector	Pointer to an array of IOPhysicalSegments for the output physical scatter/gather list.
numVectorSegments	Maximum number of IOPhysicalSegments accepted.

getPhysicalSegmentsWithCoalesce

public:

UInt getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
 struct IOPhysicalSegment * vector,
 UInt numVectorSegments = 0);

Generate a big endian physical scatter/gather list from a given mbuf. Coalesce mbuf chain when the number of segments in the scatter/gather list exceeds numVectorSegments.

Parameters

Name	Description
packet	The mbuf packet.
vector	Pointer to an array of IOPhysicalSegments for the output physical scatter/gather list.
numVectorSegments	Maximum number of IOPhysicalSegments accepted.

withSpecification

public:

static IOMBufBigMemoryCursor * withSpecification(UInt maxSegmentSize,
 UInt maxNumSegments);

Parameters

Name	Description
maxSegmentSize	Maximum allowable size for one segment.
maxNumSegments	Maximum number of segments.

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

Member Functions

getPhysicalSegments

public:

UInt getPhysicalSegments(struct mbuf * packet,
 struct IODBDMADescriptor *vector,
 UInt numVectorSegments = 0);

Parameters

Name	Description
packet	The mbuf packet.
vector	Pointer to an array of IODBDMADescriptor for the output list.
numVectorSegments	Maximum number of IODBDMADescriptors accepted.

getPhysicalSegmentsWithCoalesce

public:

UInt getPhysicalSegmentsWithCoalesce(struct mbuf * packet,
 struct IODBDMADescriptor * vector,
 UInt numVectorSegments = 0);