IOFireWireLocalIsochPortInterface

Declared In:

Overview

FireWire user client local isochronous port object.

Discussion

Represents a FireWire isochronous talker or listener within the local machine. Isochronous transfer is controlled by an associated DCL (Data Stream Control Language) program, which is similar to a hardware DMA program but is hardware agnostic. DCL programs can be written using the IOFireWireDCLCommandPoolInterface object.

This interface contains all methods of IOFireWireIsochPortInterface and IOFireWireLocalIsochPortInterface. This interface will contain all v2 methods of IOFireWireLocalIsochPortInterface when instantiated as v2 or newer.

Transfer buffers for the local isoch port must all come from a single allocation made with vm_allocate() or mmap(..., MAP_ANON ).

Calling vm_deallocate() on the buffers before deallocating a local isoch port object may result in a deadlock.

Note: Calling Release() on the local isoch port may not immediately release the isoch port; so it may not be safe to call vm_deallocate() on your transfer buffers. To guarantee the port has been release, run the isochronous runloop until the port is finalized (it has processed any pending callbacks). The finalize callback will be called when the port is finalized. Set the finalize callback using SetFinalizeCallback().


Functions

AllocatePort

The method is called when the port should configure its associated hardware to prepare to send or receive isochronous data on the channel number and at the speed specified.

GetRefCon

Get reference value associated with this port.

GetSupported

The method is called to determine which FireWire isochronous channels and speed this port supports.

ModifyJumpDCL

Change the jump target label of a jump DCL.

ModifyTransferPacketDCL

Modify the transfer size of a transfer packet DCL (send or receive)

ModifyTransferPacketDCLBuffer

NOT IMPLEMENTED. Modify the transfer size of a transfer packet DCL (send or receive)

ModifyTransferPacketDCLSize

Modify the transfer size of a transfer packet DCL (send or receive)

PrintDCLProgram

Display the contents of a DCL program.

ReleasePort

The method is called to release the hardware after the channel has been stopped.

SetFinalizeCallback

Set the finalize callback for a local isoch port

SetRefCon

Set reference value associated with this port.

Start

The method is called when the port is to begin talking or listening.

Stop

The method is called when the port is to stop talking or listening.

AllocatePort

The method is called when the port should configure its associated hardware to prepare to send or receive isochronous data on the channel number and at the speed specified. 

IOReturn ( *AllocatePort) (
    IOFireWireLibIsochPortRef self,
    IOFWSpeed speed,
    UInt32 chan );
Parameters
self

The isoch port interface to use.

speed

Channel speed

chan

Channel number (-63)

Return Value

Return kIOReturnSuccess on success, other return any other IOReturn error code.

Discussion

This method is called by the channel object to which a port has been added. Subclasses of IOFireWireIsochPortInterface override this method to support specific hardware. Do not call this method directly.

GetRefCon

Get reference value associated with this port. 

void* ( *GetRefCon) (
    IOFireWireLibIsochPortRef self);
Parameters
self

The isoch port interface to use.

Return Value

The port refcon value.

Discussion

Set the reference value with SetRefCon()

GetSupported

The method is called to determine which FireWire isochronous channels and speed this port supports. 

IOReturn ( *GetSupported) (
    IOFireWireLibIsochPortRef self,
    IOFWSpeed *maxSpeed,
    UInt64 *chanSupported );
Parameters
self

The isoch port interface to use.

maxSpeed

A pointer to an IOFWSpeed which should be filled with the maximum speed this port can talk or listen.

chanSupported

A pointer to a UInt64 which should be filled with a bitmask representing the FireWire bus isochonous channels on which the port can talk or listen. Set '1' for supported, '' for unsupported.

Return Value

Return kIOReturnSuccess on success, other return any other IOReturn error code.

Discussion

This method is called by the channel object to which a port has been added. Subclasses of IOFireWireIsochPortInterface override this method to support specific hardware. Do not call this method directly.

ModifyJumpDCL

Change the jump target label of a jump DCL. 

IOReturn ( *ModifyJumpDCL)(
    IOFireWireLibLocalIsochPortRef self,
    DCLJump *inJump,
    DCLLabel *inLabel);
Parameters
self

The local isoch port interface to use.

inJump

The jump DCL to modify.

inLabel

The label to jump to.

Return Value

kIOReturnSuccess on success. Will return an error if 'inJump' does not point to a valid jump DCL or 'inLabel' does not point to a valid label DCL.

Discussion

Use this function to change the flow of a DCL program. Works whether the DCL program is currently running or not.

ModifyTransferPacketDCL

Modify the transfer size of a transfer packet DCL (send or receive) 

IOReturn ( *ModifyTransferPacketDCL)(
    IOFireWireLibLocalIsochPortRef self,
    DCLTransferPacket *inDCL,
    void *buffer,
    IOByteCount size );
Parameters
self

The local isoch port interface to use.

inDCL

A pointer to the DCL to modify.

buffer

The new buffer to or from data will be transferred.

size

The new size of data to be transferred.

Return Value

Returns kIOReturnSuccess on success. Will return an error if 'size' is too large or 'inDCL' does not point to a valid transfer packet DCL, or the range specified by [buffer, buffer+size] is not in the range of memory locked down for this program.

Discussion

Allows you to modify transfer packet DCLs after they have been compiled and while the DCL program is still running. The transfer size can be set to any size less than or equal to the size set when the DCL program was compiled (including 0).

Availability: IOFireWireLocalIsochPortInterface_v3 and newer.

ModifyTransferPacketDCLBuffer

NOT IMPLEMENTED. Modify the transfer size of a transfer packet DCL (send or receive) 

IOReturn ( *ModifyTransferPacketDCLBuffer)(
    IOFireWireLibLocalIsochPortRef self,
    DCLTransferPacket *inDCL,
    void *buffer );
Parameters
self

The local isoch port interface to use.

inDCL

A pointer to the DCL to modify.

buffer

The new buffer to or from data will be transferred.

Return Value

Returns kIOReturnSuccess on success. Will return an error if the range specified by [buffer, buffer+size] is not in the range of memory locked down for this program.

Discussion

NOT IMPLEMENTED. Allows you to modify transfer packet DCLs after they have been compiled and while the DCL program is still running. The buffer can be set to be any location within the range of buffers specified when the DCL program was compiled (including 0).

Availability: IOFireWireLocalIsochPortInterface_v3 and newer.

ModifyTransferPacketDCLSize

Modify the transfer size of a transfer packet DCL (send or receive) 

IOReturn ( *ModifyTransferPacketDCLSize)(
    IOFireWireLibLocalIsochPortRef self,
    DCLTransferPacket *inDCL,
    IOByteCount size );
Parameters
self

The local isoch port interface to use.

inDCL

A pointer to the DCL to modify.

size

The new size of data to be transferred.

Return Value

Returns kIOReturnSuccess on success. Will return an error if 'size' is too large for this program.

Discussion

Allows you to modify transfer packet DCLs after they have been compiled and while the DCL program is still running. The transfer size can be set to any size less than or equal to the size set when the DCL program was compiled (including 0).

Availability: IOFireWireLocalIsochPortInterface_v2 and newer.

PrintDCLProgram

Display the contents of a DCL program. 

void ( *PrintDCLProgram)(
    IOFireWireLibLocalIsochPortRef self,
    const DCLCommand* inProgram,
    UInt32 inLength);
Parameters
self

The local isoch port interface to use.

inProgram

A pointer to the first DCL of the program to display.

inLength

The length (in DCLs) of the program.

ReleasePort

The method is called to release the hardware after the channel has been stopped. 

IOReturn ( *ReleasePort) (
    IOFireWireLibIsochPortRef self );
Parameters
self

The isoch port interface to use.

Return Value

Return kIOReturnSuccess on success, other return any other IOReturn error code.

Discussion

This method is called by the channel object to which a port has been added. Subclasses of IOFireWireIsochPortInterface override this method to support specific hardware. Do not call this method directly.

SetFinalizeCallback

Set the finalize callback for a local isoch port 

IOReturn ( *SetFinalizeCallback)(
    IOFireWireLibLocalIsochPortRef self,
    IOFireWireLibIsochPortFinalizeCallback finalizeCallback );
Parameters
self

The local isoch port interface to use.

finalizeCallback

The finalize callback.

Return Value

Returns true if this isoch port has no more pending callbacks and does not need any more runloop time.

Discussion

When Stop() is called on a LocalIsochPortInterface, there may or may not be isoch callbacks still pending for this isoch port. The port must be allowed to handle any pending callbacks, so the isoch runloop should not be stopped until a port has handled all pending callbacks. The finalize callback is called after the final callback has been made on the isoch runloop. After this callback is sent, it is safe to stop the isoch runloop.

You should not access the isoch port after the finalize callback has been made; it may be released immediately after this callback is sent.

Availability: IOFireWireLocalIsochPortInterface_v4 and newer.

SetRefCon

Set reference value associated with this port. 

void ( *SetRefCon) (
    IOFireWireLibIsochPortRef self,
    void *inRefCon);
Parameters
self

The isoch port interface to use.

inRefCon

The new reference value.

Discussion

Retrieve the reference value with GetRefCon()

Start

The method is called when the port is to begin talking or listening. 

IOReturn ( *Start) (
    IOFireWireLibIsochPortRef self );
Parameters
self

The isoch port interface to use.

Return Value

Return kIOReturnSuccess on success, other return any other IOReturn error code.

Discussion

This method is called by the channel object to which a port has been added. Subclasses of IOFireWireIsochPortInterface override this method to support specific hardware. Do not call this method directly.

Stop

The method is called when the port is to stop talking or listening. 

IOReturn ( *Stop) (
    IOFireWireLibIsochPortRef self );
Parameters
self

The isoch port interface to use.

Return Value

Return kIOReturnSuccess on success, other return any other IOReturn error code.

Discussion

This method is called by the channel object to which a port has been added. Subclasses of IOFireWireIsochPortInterface override this method to support specific hardware. Do not call this method directly.

Member Data

revision
version

revision

UInt32 revision;
Discussion

Interface revision

version

UInt32 version;
Discussion

Interface revision

 

Did this document help you? Yes It's good, but... Not helpful...

 

Last Updated: 2009-10-15