ADC Home > Reference Library > Reference > Hardware & Drivers > I/O Kit Framework Reference

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

ModifyJumpDCL: Changes the jump target label of a jump DCL.
ModifyTransferPacketDCL: Modifies the transfer size of a transfer packet DCL (send or receive).
ModifyTransferPacketDCLBuffer: NOT IMPLEMENTED. Modifies the transfer size of a transfer packet DCL (send or receive).
ModifyTransferPacketDCLSize: Modifies the transfer size of a transfer packet DCL (send or receive).
PrintDCLProgram: Displays the contents of a DCL program.
SetFinalizeCallback: Sets the finalize callback for a local isoch port.

ModifyJumpDCL

Changes 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

Returns 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

Modifies 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 later.

ModifyTransferPacketDCLBuffer

NOT IMPLEMENTED. Modifies 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 later.

ModifyTransferPacketDCLSize

Modifies 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

Availability: IOFireWireLocalIsochPortInterface_v2 and later.

PrintDCLProgram

Displays 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: Returns the length (in DCLs) of the program.

SetFinalizeCallback

Sets the finalize callback for a local isoch port.

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

Parameters

self: The local isoch port interface to use.
finalizeCalback: 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 later.

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2009-02-23