Mac Dev Center Mac OS X Reference Library Drivers, Kernel, & Hardware: User-Space Device Access I/O Kit Framework Reference

IOFireWireNuDCLPoolInterface

Declared In:

IOFireWireLibIsoch.h

Overview

Use this interface to build NuDCL-based DCL programs.

Functions

AllocateReceivePacket: Allocate a ReceivePacket NuDCL and append it to the program
AllocateReceivePacket_v: Allocate a ReceivePacket NuDCL and append it to the program
AllocateSendPacket: Allocate a SendPacket NuDCL and append it to the program.
AllocateSendPacket_v: Allocate a SendPacket NuDCL and append it to the program.
AllocateSkipCycle: Allocate a SkipCycle NuDCL and append it to the program.
AppendDCLRanges: Add a memory range to the scatter gather list of a NuDCL
AppendDCLUpdateList
CopyDCLUpdateList
CountDCLRanges: Returns number of buffers for a NuDCL
FindDCLNextDCL: Get the next pointer for a NuDCL
GetDCLBranch: Get the branch pointer for a NuDCL
GetDCLCallback: Get callback for a NuDCL
GetDCLFlags
GetDCLRanges: Get the scatter-gather list for a NuDCL
GetDCLRefcon
GetDCLs: Returns the pool's DCL program as a CFArray of NuDCLRef's.
GetDCLSize: Returns number of bytes to be transferred by a NuDCL
GetDCLSkipBranch
GetDCLSkipCallback
GetDCLSkipRefcon
GetDCLSpan: Returns a virtual range spanning lowest referenced buffer address to highest
GetDCLStatusPtr: Get the status pointer for a NuDCL.
GetDCLSyncBits
GetDCLTagBits
GetDCLTimeStampPtr: Get the time stamp pointer for a NuDCL.
GetDCLUserHeaderPtr
GetProgram: Finds the first DCL in the pool not preceeded by any other DCL.
GetUserHeaderMaskPtr
PrintDCL
PrintProgram
RemoveDCLUpdateList
SetCurrentTagAndSync: Set current tag and sync bits
SetDCLBranch: Set the branch pointer for a NuDCL
SetDCLCallback: Set the callback for a NuDCL
SetDCLFlags
SetDCLRanges: Set the scatter gather list for a NuDCL
SetDCLRefcon
SetDCLSkipBranch
SetDCLSkipCallback
SetDCLSkipRefcon
SetDCLStatusPtr: Set the status pointer for a NuDCL
SetDCLSyncBits
SetDCLTagBits
SetDCLTimeStampPtr: Set the time stamp pointer for a NuDCL
SetDCLUpdateList
SetDCLUserHeaderPtr: Set a user specified header for a send NuDCL
SetDCLWaitControl

AllocateReceivePacket

Allocate a ReceivePacket NuDCL and append it to the program

NuDCLReceivePacketRef ( *AllocateReceivePacket)(
    IOFireWireLibNuDCLPoolRef self,
    CFMutableSetRef saveBag,
    UInt8 headerBytes,
    UInt32 numBuffers,
    IOVirtualRange *buffers );

Parameters

self: The NuDCL pool to use.
headerBytes: Number of bytes of isochronous header to receive with the data. Valid values are 0, 4, and 8.
saveBag: The allocated DCL can be added to a CFBag for easily setting DCL update lists. Pass a CFMutableSetRef to add the allocated DCL to a CFBag; pass NULL to ignore. SaveBag is unmodified on failure.
numBuffers: The number of virtual ranges in 'buffers'.
buffers: An array of virtual memory ranges containing the packet contents. The array is copied into the DCL.

Return Value

Returns an NuDCLReceivePacketRef on success or 0 on failure.

Discussion

The ReceivePacket DCL receives an isochronous packet from the bus. One DCL runs per bus cycle. If receiving isochronous headers, an update must be run before the isochronous header is valid.

Receive DCLs can be modified using other functions of IOFireWireLibNuDCLPool.

AllocateReceivePacket_v

Allocate a ReceivePacket NuDCL and append it to the program

NuDCLReceivePacketRef ( *AllocateReceivePacket_v)(
    IOFireWireLibNuDCLPoolRef self,
    CFMutableSetRef saveBag,
    UInt8 headerBytes,
    IOVirtualRange *firstRange,
    ... );

Parameters

self: The NuDCL pool to use.
saveBag: The allocated DCL can be added to a CFBag for easily setting DCL update lists. Pass a CFMutableSetRef to add the allocated DCL to a CFBag; pass NULL to ignore. SaveBag is unmodified on failure.
headerBytes: Number of bytes of isochronous header to receive with the data. Valid values are 0, 4, and 8.
firstRange: The first buffer to be transmitted. Follow with additional ranges; terminate with NULL.

Return Value

Returns an NuDCLReceivePacketRef on success or 0 on failure.

Discussion

Same as AllocateReceivePacket but ranges are passed as a NULL-terminated vector of IOVirtualRange's

AllocateSendPacket

Allocate a SendPacket NuDCL and append it to the program.

NuDCLSendPacketRef ( *AllocateSendPacket)(
    IOFireWireLibNuDCLPoolRef self,
    CFMutableSetRef saveBag,
    UInt32 numBuffers,
    IOVirtualRange *buffers );

Parameters

self: The NuDCL pool to use.
saveBag: The allocated DCL can be added to a CFBag for easily setting DCL update lists. Pass a CFMutableSetRef to add the allocated DCL to a CFBag; pass NULL to ignore. SaveBag is unmodified on failure.
numBuffers: The number of virtual ranges in 'buffers'.
buffers: An array of virtual memory ranges containing the packet contents. The array is copied into the DCL.

Return Value

Returns an NuDCLSendPacketRef on success or 0 on failure.

Discussion

The SendPacket DCL sends an isochronous packet on the bus. One DCL runs per bus cycle. The isochronous header is automatically generated, but can be overriden. An update must be run to regenerate the isochronous header. The sync and tag fields of allocated DCLs default to 0, unless If SetCurrentTagAndSync has been called.

Send DCLs can be modified using other functions of IOFireWireLibNuDCLPool.

AllocateSendPacket_v

Allocate a SendPacket NuDCL and append it to the program.

NuDCLSendPacketRef ( *AllocateSendPacket_v)(
    IOFireWireLibNuDCLPoolRef self,
    CFMutableSetRef saveBag,
    IOVirtualRange *firstRange,
    ... );

Parameters

self: The NuDCL pool to use.
saveBag: The allocated DCL can be added to a CFBag for easily setting DCL update lists. Pass a CFMutableSetRef to add the allocated DCL to a CFBag; pass NULL to ignore. SaveBag is unmodified on failure.
firstRange: The first buffer to be transmitted. Follow with additional ranges; terminate with NULL.

Return Value

Returns an NuDCLSendPacketRef on success or 0 on failure.

Discussion

Same as AllocateSendPacket but ranges are passed as a NULL-terminated vector of IOVirtualRange's

AllocateSkipCycle

Allocate a SkipCycle NuDCL and append it to the program.

NuDCLSkipCycleRef ( *AllocateSkipCycle)(
    IOFireWireLibNuDCLPoolRef self );

Parameters

self: The NuDCL pool to use.

Return Value

Returns an NuDCLSkipCycleRef on success or 0 on failure.

Discussion

The SkipCycle DCL causes the DCL program to "sends" an empty cycle.

AppendDCLRanges

Add a memory range to the scatter gather list of a NuDCL

IOReturn ( *AppendDCLRanges) (
    NuDCLRef dcl,
    UInt32 numRanges,
    IOVirtualRange *range );

Parameters

dcl: The DCL to modify
range: A IOVirtualRange to add to this DCL buffer list. Do not pass NULL.

Return Value

Returns an IOReturn error code.

Discussion

This change will apply immediately to a non-running DCL program. To apply the change to a running program use IOFireWireLocalIsochPortInterface::Notify()

Applies: NuDCLSendPacketRef, NuDCLReceivePacketRef

AppendDCLUpdateList

IOReturn ( *AppendDCLUpdateList)(
    NuDCLRef dcl,
    NuDCLRef updateDCL );

Discussion

Description forthcoming

CopyDCLUpdateList

CFSetRef ( *CopyDCLUpdateList)(
    NuDCLRef dcl );

Discussion

Description forthcoming

CountDCLRanges

Returns number of buffers for a NuDCL

UInt32 ( *CountDCLRanges) (
    NuDCLRef dcl );

Parameters

dcl: The DCL to query

Return Value

Returns number of ranges in DCLs scatter-gather list

Discussion

Applies: NuDCLSendPacketRef, NuDCLReceivePacket

FindDCLNextDCL

Get the next pointer for a NuDCL

NuDCLRef ( *FindDCLNextDCL)(
    IOFireWireLibNuDCLPoolRef self,
    NuDCLRef dcl );

Parameters

dcl: The dcl whose next pointer will be returned

Return Value

Returns the DCL immediately following this DCL in program order (ignoring branches) or 0 for none.

Discussion

Applies: Any NuDCLRef

GetDCLBranch

Get the branch pointer for a NuDCL

NuDCLRef ( *GetDCLBranch)(
    NuDCLRef dcl );

Parameters

dcl: The dcl whose branch pointer will be returned.

Return Value

Returns the branch pointer of 'dcl' or 0 for none is set.

Discussion

Applies: Any NuDCLRef.

GetDCLCallback

Get callback for a NuDCL

NuDCLCallback ( *GetDCLCallback)(
    NuDCLRef dcl );

Parameters

dcl: The DCL to query

Return Value

Returns the DCLs callback function or NULL if none is set.

Discussion

Returns the callback function for a DCL

Applies: Any NuDCLRef

GetDCLFlags

UInt32 ( *GetDCLFlags)(
    NuDCLRef dcl );

Discussion

Description forthcoming

GetDCLRanges

Get the scatter-gather list for a NuDCL

UInt32 ( *GetDCLRanges) (
    NuDCLRef dcl,
    UInt32 maxRanges,
    IOVirtualRange *outRanges );

Parameters

dcl: The DCL to query
maxRanges: Description forthcoming.
outRanges: Description forthcoming.

Return Value

Returns the previously set handler or NULL is no handler was set.

Discussion

Applies: NuDCLSendPacketRef, NuDCLReceivePacketRef

GetDCLRefcon

void* ( *GetDCLRefcon)(
    NuDCLRef dcl );

Discussion

Description forthcoming

GetDCLs

Returns the pool's DCL program as a CFArray of NuDCLRef's.

CFArrayRef ( *GetDCLs)(
    IOFireWireLibNuDCLPoolRef self );

Parameters

self: The NuDCL pool to use.

Return Value

A CFArrayRef.

GetDCLSize

Returns number of bytes to be transferred by a NuDCL

IOByteCount ( *GetDCLSize) (
    NuDCLRef dcl );

Parameters

dcl: The DCL to query

Return Value

Returns an IOByteCount.

Discussion

Applies: NuDCLSendPacketRef, NuDCLReceivePacket

GetDCLSkipBranch

NuDCLRef ( *GetDCLSkipBranch)(
    NuDCLRef dcl );

Discussion

Description forthcoming

GetDCLSkipCallback

NuDCLCallback ( *GetDCLSkipCallback)(
    NuDCLRef dcl );

Discussion

Description forthcoming

GetDCLSkipRefcon

void * ( *GetDCLSkipRefcon)(
    NuDCLRef dcl );

Discussion

Description forthcoming

GetDCLSpan

Returns a virtual range spanning lowest referenced buffer address to highest

IOReturn ( *GetDCLSpan) (
    NuDCLRef dcl,
    IOVirtualRange *spanRange );

Parameters

dcl: The DCL to query

Return Value

Returns an IOVirtualRange.

Discussion

Applies: NuDCLSendPacketRef, NuDCLReceivePacket

GetDCLStatusPtr

Get the status pointer for a NuDCL.

UInt32* ( *GetDCLStatusPtr)(
    NuDCLRef dcl );

Parameters

dcl: The DCL whose status pointer will be returned.

Return Value

Returns a UInt32 status pointer.

Discussion

Applies: Any NuDCLRef.

GetDCLSyncBits

UInt8 ( *GetDCLSyncBits)(
    NuDCLRef dcl );

Discussion

Description forthcoming

GetDCLTagBits

UInt8 ( *GetDCLTagBits)(
    NuDCLRef dcl );

Discussion

Description forthcoming

GetDCLTimeStampPtr

Get the time stamp pointer for a NuDCL.

UInt32* ( *GetDCLTimeStampPtr)(
    NuDCLRef dcl );

Parameters

dcl: The DCL whose timestamp pointer will be returned.

Return Value

Returns a UInt32 time stamp pointer.

Discussion

Applies: Any NuDCLRef.

GetDCLUserHeaderPtr

UInt32 * ( *GetDCLUserHeaderPtr)(
    NuDCLRef dcl );

Discussion

Description forthcoming

GetProgram

Finds the first DCL in the pool not preceeded by any other DCL.

DCLCommand* ( *GetProgram)(
    IOFireWireLibNuDCLPoolRef self );

Parameters

self: The NuDCL pool to use.

Return Value

A DCLCommand pointer.

Discussion

Returns a backwards-compatible DCL program pointer. This can be passed to IOFireWireLibDeviceRef::CreateLocalIsochPort.

GetUserHeaderMaskPtr

UInt32 * ( *GetUserHeaderMaskPtr)(
    NuDCLRef dcl );

Discussion

Description forthcoming

PrintDCL

void ( *PrintDCL)(
    NuDCLRef dcl );

Discussion

Description forthcoming

PrintProgram

void ( *PrintProgram)(
    IOFireWireLibNuDCLPoolRef self );

Discussion

Description forthcoming

RemoveDCLUpdateList

IOReturn ( *RemoveDCLUpdateList)(
    NuDCLRef dcl );

Discussion

Description forthcoming

SetCurrentTagAndSync

Set current tag and sync bits

void ( *SetCurrentTagAndSync)(
    IOFireWireLibNuDCLPoolRef self,
    UInt8 tag,
    UInt8 sync );

Parameters

self: The NuDCL pool to use.
tag: Tag field value for subsequently allocated send DCLs
sync: Sync field value for subsequently allocated send DCLs

Discussion

Sets the DCL pool's current tag and sync bits. All send DCLs allocated after calling this function will transmit the specified tag and sync values. These fields can also be set on each DCL using SetDCLTagBits() and SetDCLSyncBits().

SetDCLBranch

Set the branch pointer for a NuDCL

IOReturn ( *SetDCLBranch)(
    NuDCLRef dcl,
    NuDCLRef branchDCL );

Return Value

Returns an IOReturn error code.

Discussion

Program execution will jump to the DCL pointed to by 'branchDCL', after the DCL is executed. If set to 0, execution will stop after this DCL.

This change will apply immediately to a non-running DCL program. To apply the change to a running program use IOFireWireLocalIsochPortInterface::Notify()

Applies: Any NuDCLRef.

SetDCLCallback

Set the callback for a NuDCL

IOReturn ( *SetDCLCallback) (
    NuDCLRef dcl,
    NuDCLCallback callback );

Parameters

dcl: The DCL to modify
callback: The callback function.

Return Value

Returns an IOReturn error code.

Discussion

A callback can be called each time a NuDCL is run. Use SetDCLCallback() to set the callback for a NuDCL. If the update option is also set, the callback will be called after the update has run.

This change will apply immediately to a non-running DCL program. To apply the change to a running program use IOFireWireLocalIsochPortInterface::Notify()

Applies: Any NuDCLRef

SetDCLFlags

void ( *SetDCLFlags)(
    NuDCLRef dcl,
    UInt32 flags );

Discussion

Description forthcoming

SetDCLRanges

Set the scatter gather list for a NuDCL

IOReturn ( *SetDCLRanges) (
    NuDCLRef dcl,
    UInt32 numRanges,
    IOVirtualRange *ranges );

Parameters

dcl: The DCL to modify
numRanges: number of ranges in 'ranges'.
ranges: An array of virtual ranges

Return Value

Returns an IOReturn error code.

Discussion

Set the list of data buffers for a DCL. Setting too many ranges may result in a memory region with too many discontinous physical segments for the hardware to send or receive in a single packet. This will result in an error when the program is compiled.

This change will apply immediately to a non-running DCL program. To apply the change to a running program use IOFireWireLocalIsochPortInterface::Notify()

Applies: NuDCLSendPacketRef, NuDCLReceivePacketRef

SetDCLRefcon

void ( *SetDCLRefcon)(
    NuDCLRef dcl,
    void *refcon );

Discussion

Description forthcoming

SetDCLSkipBranch

IOReturn ( *SetDCLSkipBranch)(
    NuDCLRef dcl,
    NuDCLRef skipCycleDCL );

Discussion

Description forthcoming

SetDCLSkipCallback

IOReturn ( *SetDCLSkipCallback)(
    NuDCLRef dcl,
    NuDCLCallback callback );

Discussion

Description forthcoming

SetDCLSkipRefcon

IOReturn ( *SetDCLSkipRefcon)(
    NuDCLRef dcl,
    void *refcon );

Discussion

Description forthcoming

SetDCLStatusPtr

Set the status pointer for a NuDCL

IOReturn ( *SetDCLStatusPtr)(
    NuDCLRef dcl,
    UInt32 *statusPtr );

Parameters

dcl: The DCL for which status pointer will be set
statusPtr: A pointer to a quadlet which will hold the status after 'dcl' is updated.

Return Value

Returns an IOReturn error code.

Discussion

Setting a the status pointer for a NuDCL causes the packet transmit/receive hardware status to be recorded when the DCL executes. This DCL must be updated after it has executed for the status to be valid.

This change will apply immediately to a non-running DCL program. To apply the change to a running program use IOFireWireLocalIsochPortInterface::Notify()

Status values are as follows: (from the OHCI spec, section 3.1.1)

5'h00 No event status.

5'h02 evt_long_packet (receive) The received data length was greater than the buffer's data_length.

5'h05 evt_overrun (receive) A receive FIFO overflowed during the reception of an isochronous packet.

5'h06 evt_descriptor_read (receive/transmit) An unrecoverable error occurred while the Host Controller was reading a descriptor block.

5'h07 evt_data_read (transmit) An error occurred while the Host Controller was attempting to read from host memory in the data stage of descriptor processing.

5'h08 evt_data_write (receive/transmit) An error occurred while the Host Controller was attempting to write to host memory either in the data stage of descriptor processing (AR, IR), or when processing a single 16-bit host memory write (IT).

5'h0A evt_timeout (transmit) Indicates that the asynchronous transmit response packet expired and was not transmitted, or that an IT DMA context experienced a skip processing overflow (See section9.3.4).

5'h0B evt_tcode_err (transmit) A bad tCode is associated with this packet. The packet was flushed.

5'h0E evt_unknown (receive/transmit) An error condition has occurred that cannot be represented by any other event codes defined herein.

5'h11 ack_complete (receive/transmit) No event occurred. (Success)

5'h1D ack_data_error (receive) A data field CRC or data_length error.

Applies: Any NuDCLRef.

SetDCLSyncBits

IOReturn ( *SetDCLSyncBits)(
    NuDCLRef dcl,
    UInt8 syncBits );

Discussion

Description forthcoming

SetDCLTagBits

IOReturn ( *SetDCLTagBits)(
    NuDCLRef dcl,
    UInt8 tagBits );

Discussion

Description forthcoming

SetDCLTimeStampPtr

Set the time stamp pointer for a NuDCL

IOReturn ( *SetDCLTimeStampPtr)(
    NuDCLRef dcl,
    UInt32 *timeStampPtr );

Parameters

dcl: The DCL for which time stamp pointer will be set
timeStampPtr: A pointer to a quadlet which will hold the timestamp after 'dcl' is updated.

Return Value

Returns an IOReturn error code.

Discussion

Setting a the time stamp pointer for a NuDCL causes a time stamp to be recorded when a DCL executes. This DCL must be updated after it has executed for the timestamp to be valid.

This change will apply immediately to a non-running DCL program. To apply the change to a running program use IOFireWireLocalIsochPortInterface::Notify()

Applies: Any NuDCLRef.

SetDCLUpdateList

IOReturn ( *SetDCLUpdateList)(
    NuDCLRef dcl,
    CFSetRef dclList );

Discussion

Description forthcoming

SetDCLUserHeaderPtr

Set a user specified header for a send NuDCL

IOReturn ( *SetDCLUserHeaderPtr)(
    NuDCLRef dcl,
    UInt32 *headerPtr,
    UInt32 *mask );

Parameters

dcl: The DCL to modify
headerPtr: A pointer to a two-quadlet header. See section 9.6 of the the OHCI specification.
mask: A pointer to a two-quadlet mask. The quadlets in headerPtr are masked with 'mask' and the masked-out bits are replaced by the FireWire system software.

Return Value

Returns an IOReturn error code.

Discussion

Allows the client to create a custom header for a transmitted isochronous packet. The header is masked with 'mask', and the FireWire system software fills in the masked out bits.

This change will apply immediately to a non-running DCL program. An update must be run on the DCL for changes to take effect in a running program.

Applies: NuDCLSendPacketRef

SetDCLWaitControl

IOReturn ( *SetDCLWaitControl)(
    NuDCLRef dcl,
    Boolean wait );

Discussion

Description forthcoming

Member Data

revision
version

revision

UInt32 revision;

Discussion

Interface version

version

UInt32 version;

Discussion

Interface version

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

Last Updated: 2009-10-15

5'h00	No event status.
5'h02	evt_long_packet (receive)	The received data length was greater than the buffer's data_length.
5'h05	evt_overrun (receive)	A receive FIFO overflowed during the reception of an isochronous packet.
5'h06	evt_descriptor_read (receive/transmit)	An unrecoverable error occurred while the Host Controller was reading a descriptor block.
5'h07	evt_data_read (transmit)	An error occurred while the Host Controller was attempting to read from host memory in the data stage of descriptor processing.
5'h08	evt_data_write (receive/transmit)	An error occurred while the Host Controller was attempting to write to host memory either in the data stage of descriptor processing (AR, IR), or when processing a single 16-bit host memory write (IT).
5'h0A	evt_timeout (transmit)	Indicates that the asynchronous transmit response packet expired and was not transmitted, or that an IT DMA context experienced a skip processing overflow (See section9.3.4).
5'h0B	evt_tcode_err (transmit)	A bad tCode is associated with this packet. The packet was flushed.
5'h0E	evt_unknown (receive/transmit)	An error condition has occurred that cannot be represented by any other event codes defined herein.
5'h11	ack_complete (receive/transmit)	No event occurred. (Success)
5'h1D	ack_data_error (receive)	A data field CRC or data_length error.