Mac Dev Center Right arrow

Mac OS X Reference Library Right arrow

Drivers, Kernel, & Hardware: User-Space Device Access Right arrow

I/O Kit Framework Reference

IOFireWireCompareSwapCommandInterface_v3

Declared In:

IOFireWireLib.h

Overview

Description forthcoming

Functions

Cancel: Cancel command execution
DidLock: Was the last lock operation successful?
GetAckCode: Gets the most recently received ack code for this transaction.
GetBuffer: Set the command refCon value and callback handler, and submit the command to FireWire for execution.
GetRefCon: Gets the refcon associated with this command
GetResponseCode: Gets the most recently received response code for this transaction.
GetStatus: Return command completion status.
GetTargetAddress: Get command target address.
GetTransferredBytes: Return number of bytes transferred by this command object when it last completed execution.
IsExecuting: Is this command object currently executing?
Locked: Get the 32-bit value returned on the last compare swap operation.
Locked64: Get the 64-bit value returned on the last compare swap operation.
SetBuffer: Set the buffer where read data should be stored.
SetCallback: Set the completion handler to be called once the command completes asynchronous execution .
SetFlags: Set flags governing this command's execution.
SetGeneration: Set FireWire bus generation for which the command object shall be valid. If the failOnReset attribute has been set, the command will only be considered for execution during the bus generation specified by this function.
SetMaxPacket: Set the maximum size in bytes of packets transferred by this command.
SetMaxPacketSpeed: Gets the most recently received ack code for this transaction.
SetMaxRetryCount: Sets the maximum number of retries for this command.
SetRefCon: Set the user refCon value. This is the user defined value that will be passed in the refCon argument to the completion function.
SetTarget: Set command target address
SetTimeoutDuration: Sets the duration of the timeout for this command.
SetValues: Set values for 32-bit compare swap operation. Calling this function will make the command object perform 32-bit compare swap transactions on the bus. To perform 64-bit compare swap operations, use the SetValues64() call, below.
SetValues64: Set values for 64-bit compare swap operation. Calling this function will make the command object perform 64-bit compare swap transactions on the bus. To perform 32-bit compare swap operations, use the SetValues() call, above.
Submit
SubmitWithRefconAndCallback: Set the command refCon value and callback handler, and submit the command to FireWire for execution.

Cancel

Cancel command execution

IOReturn ( *Cancel)(
    IOFireWireLibCommandRef self,
    IOReturn reason);

Parameters

self: The command object interface of interest

Return Value

An IOReturn result code

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

DidLock

Was the last lock operation successful?

Boolean ( *DidLock)(
    IOFireWireLibCompareSwapCommandV3Ref self);

Parameters

self: The command object interface of interest

Return Value

Returns true if the last lock operation performed by this command object was successful, false otherwise.

Discussion

Available in v2 and newer.

GetAckCode

Gets the most recently received ack code for this transaction.

UInt32 ( *GetAckCode)(
    IOFireWireLibCommandRef self );

Parameters

self: A reference to the command

Return Value

The FireWire ack code.

GetBuffer

Set the command refCon value and callback handler, and submit the command to FireWire for execution.

void ( *GetBuffer)(
    IOFireWireLibCommandRef self,
    UInt32 *outSize,
    void **outBuf);

Parameters

self: The command object interface of interest

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	NO
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	NO
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	NO
	`kIOFireWireWriteQuadletCommandInterfaceID`	NO
	`kIOFireWireCompareSwapCommandInterfaceID`	NO
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

GetRefCon

Gets the refcon associated with this command

void * ( *GetRefCon)(
    IOFireWireLibCommandRef self );

Parameters

self: A reference to the command

Return Value

void

GetResponseCode

Gets the most recently received response code for this transaction.

UInt32 ( *GetResponseCode)(
    IOFireWireLibCommandRef self );

Parameters

self: A reference to the command

Return Value

The FireWire response code.

GetStatus

Return command completion status.

IOReturn ( *GetStatus)(
    IOFireWireLibCommandRef self);

Parameters

self: The command object interface of interest

Return Value

An IOReturn error code indicating the completion error (if any) returned the last time this command object was executed

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

GetTargetAddress

Get command target address.

void ( *GetTargetAddress)(
    IOFireWireLibCommandRef self,
    FWAddress *outAddr);

Parameters

self: The command object interface of interest
outAddr: A pointer to an FWAddress to contain the function result.

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	NO

GetTransferredBytes

Return number of bytes transferred by this command object when it last completed execution.

UInt32 ( *GetTransferredBytes)(
    IOFireWireLibCommandRef self);

Parameters

self: The command object interface of interest

Return Value

A UInt32 containing the bytes transferred value

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

IsExecuting

Is this command object currently executing?

const Boolean (*IsExecuting)(IOFireWireLibCommandRef self);

Parameters

self: The command object interface of interest

Return Value

Returns true if the command object is executing.

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

Locked

Get the 32-bit value returned on the last compare swap operation.

IOReturn ( *Locked)(
    IOFireWireLibCompareSwapCommandV3Ref self,
    UInt32 *oldValue);

Parameters

self: The command object interface of interest
oldValue: A pointer to contain the value returned by the target of this command on the last compare swap operation

Return Value

Returns kIOReturnBadArgument if the last compare swap operation performed was 64-bit.

Discussion

Available in v2 and newer.

Locked64

Get the 64-bit value returned on the last compare swap operation.

IOReturn ( *Locked64)(
    IOFireWireLibCompareSwapCommandV3Ref self,
    UInt64 *oldValue);

Parameters

self: The command object interface of interest
oldValue: A pointer to contain the value returned by the target of this command on the last compare swap operation

Return Value

Returns kIOReturnBadArgument if the last compare swap performed was 32-bit.

Discussion

Available in v2 and newer.

SetBuffer

Set the buffer where read data should be stored.

void ( *SetBuffer)(
    IOFireWireLibCommandRef self,
    UInt32 size,
    void *buf);

Parameters

self: The command object interface of interest
size: Size in bytes of the receive buffer.
buf: A pointer to the receive buffer.

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	NO
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	NO
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	NO
	`kIOFireWireWriteQuadletCommandInterfaceID`	NO
	`kIOFireWireCompareSwapCommandInterfaceID`	NO
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

SetCallback

Set the completion handler to be called once the command completes asynchronous execution .

void ( *SetCallback)(
    IOFireWireLibCommandRef self,
    IOFireWireLibCommandCallback inCallback);

Parameters

self: The command object interface of interest
inCallback: A callback handler. Passing nil forces the command object to execute synchronously.

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

SetFlags

Set flags governing this command's execution.

void ( *SetFlags)(
    IOFireWireLibCommandRef self,
    UInt32 inFlags);

Parameters

self

The command object interface of interest

inFlags

A UInt32 with bits set corresponding to the flags that should be set for this command object. The following values may be used:

kFWCommandNoFlags -- all flags off
kFWCommandInterfaceForceNoCopy -- data sent by this command should always be received/sent directly from the buffer set with SetBuffer(). Whatever data is in the buffer when the command is submitted will be used.
kFWCommandInterfaceForceCopyAlways -- data will always be copied out of the command object data buffer when SetBuffer() is called, up to a maximum allowed size (kFWUserCommandSubmitWithCopyMaxBufferBytes). This can result in faster data transfer. Changes made to the data buffer contents after calling SetBuffer() will be ignored; SetBuffer() should be called whenever the data buffer contents change.
kFWCommandInterfaceSyncExecute -- Setting this flag causes the command object to execute synchronously. The calling context will block until the command object has completed execution or an error occurs. Using synchronous execution can avoid kernel transitions associated with asynchronous completion and often remove the need for a state machine.
kFWCommandInterfaceForceBlockRequest -- Setting this flag causes read and write transactions to use block request packets even if the payload is 4 bytes. If this flag is not set 4 byte transactions will occur using quadlet transactions.

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	NO
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	NO
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	NO
	`kIOFireWireWriteQuadletCommandInterfaceID`	NO
	`kIOFireWireCompareSwapCommandInterfaceID`	NO
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

Set FireWire bus generation for which the command object shall be valid. If the failOnReset attribute has been set, the command will only be considered for execution during the bus generation specified by this function.

void ( *SetGeneration)(
    IOFireWireLibCommandRef self,
    UInt32 generation);

Parameters

self: The command object interface of interest
generation: A bus generation. The current bus generation can be obtained from IOFireWireDeviceInterface::GetBusGeneration().

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

SetMaxPacket

Set the maximum size in bytes of packets transferred by this command.

IOReturn ( *SetMaxPacket)(
    IOFireWireLibCommandRef self,
    IOByteCount maxPacketSize);

Parameters

self: The command object interface of interest
maxPacketSize: Size in bytes of largest packet that should be transferred by this command.

Return Value

An IOReturn result code indicating whether or not the command was successfully submitted

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	NO
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	NO
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	NO
	`kIOFireWireWriteQuadletCommandInterfaceID`	NO
	`kIOFireWireCompareSwapCommandInterfaceID`	NO
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

SetMaxPacketSpeed

Gets the most recently received ack code for this transaction.

void ( *SetMaxPacketSpeed)(
    IOFireWireLibCommandRef self,
    IOFWSpeed speed );

Parameters

self: A reference to the command
speed: the desired maximum packet speed

Return Value

void

SetMaxRetryCount

Sets the maximum number of retries for this command.

void ( *SetMaxRetryCount)(
    IOFireWireLibCommandRef self,
    UInt32 count );

Parameters

self: A reference to the command
count: The number of retires

Return Value

void

SetRefCon

Set the user refCon value. This is the user defined value that will be passed in the refCon argument to the completion function.

void ( *SetRefCon)(
    IOFireWireLibCommandRef self,
    void *refCon);

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

SetTarget

Set command target address

void ( *SetTarget)(
    IOFireWireLibCommandRef self,
    const FWAddress* addr);

Parameters

self: The command object interface of interest
addr: A pointer to an FWAddress.

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	NO

SetTimeoutDuration

Sets the duration of the timeout for this command.

void ( *SetTimeoutDuration)(
    IOFireWireLibCommandRef self,
    UInt32 duration );

Parameters

self: A reference to the command
duration: A timeout value in microseconds

Return Value

void

SetValues

Set values for 32-bit compare swap operation. Calling this function will make the command object perform 32-bit compare swap transactions on the bus. To perform 64-bit compare swap operations, use the SetValues64() call, below.

void ( *SetValues)(
    IOFireWireLibCompareSwapCommandV3Ref self,
    UInt32 cmpVal,
    UInt32 newVal);

Parameters

self: The command object interface of interest
cmpVal: The value expected at the address targeted by this command object
newVal: The value to be written at the address targeted by this command object

Discussion

Available in v2 and newer.

SetValues64

Set values for 64-bit compare swap operation. Calling this function will make the command object perform 64-bit compare swap transactions on the bus. To perform 32-bit compare swap operations, use the SetValues() call, above.

void ( *SetValues64)(
    IOFireWireLibCompareSwapCommandV3Ref self,
    UInt64 cmpVal,
    UInt64 newVal);

Parameters

self: The command object interface of interest
cmpVal: The value expected at the address targeted by this command object
newVal: The value to be written at the address targeted by this command object

Discussion

Available in v2 and newer.

Submit

IOReturn ( *Submit)(
    IOFireWireLibCommandRef self);

Discussion

Description forthcoming

SubmitWithRefconAndCallback

Set the command refCon value and callback handler, and submit the command to FireWire for execution.

IOReturn ( *SubmitWithRefconAndCallback)(
    IOFireWireLibCommandRef self,
    void *refCon,
    IOFireWireLibCommandCallback inCallback);

Parameters

self: The command object interface of interest

Return Value

An IOReturn result code indicating whether or not the command was successfully submitted

Discussion

Availability: (for interfaces obtained with ID)

	`kIOFireWireReadCommandInterfaceID`	YES
	`kIOFireWireReadCommandInterfaceID_v2`	YES
	`kIOFireWireWriteCommandInterfaceID`	YES
	`kIOFireWireWriteCommandInterfaceID_v2`	YES
	`kIOFireWireReadQuadletCommandInterfaceID`	YES
	`kIOFireWireWriteQuadletCommandInterfaceID`	YES
	`kIOFireWireCompareSwapCommandInterfaceID`	YES
	`kIOFireWireAsyncStreamCommandInterfaceID`	YES

Member Data

revision
version

revision

UInt32 revision;

Discussion

Interface version.

version

UInt32 version;

Discussion

Interface version.

Last Updated: 2009-10-15