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

IOFireWireNuDCLPoolInterface

Declared In:

IOFireWireLibIsoch.h

Overview

Use this interface to build NuDCL-based DCL programs.

Functions

AddDCLRange: Adds a memory range to the scatter gather list of a NuDCL.
AllocateReceivePacket: Allocates a ReceivePacket NuDCL and appends it to the program.
AllocateReceivePacket_v: Allocate a ReceivePacket NuDCL and append it to the program
AllocateSendPacket: Allocates a SendPacket NuDCL and appends it to the program.
AllocateSendPacket_v: Allocates a SendPacket NuDCL and appends it to the program.
AllocateSkipCycle: Allocates a SkipCycle NuDCL and appends it to the program.
AppendDCLRanges: Adds a memory range to the scatter gather list of a NuDCL.
CountDCLRanges: Returns number of buffers for a NuDCL
FindDCLNextDCL: Get the next pointer for a NuDCL
GetDCLBranch: Get the branch pointer for a NuDCL @discussion: Applies: Any NuDCLRef.
GetDCLCallback: Gets callback for a NuDCL.
GetDCLNextDCL: Get the next pointer for a NuDCL
GetDCLRanges: Gets the scatter-gather list for a NuDCL
GetDCLs: Returns the pool's DCL program as a CFArray of NuDCLRefs.
GetDCLSize: Returns number of bytes to be transferred by a NuDCL
GetDCLSpan: Returns a virtual range spanning lowest referenced buffer address to highest
GetDCLStatusPtr: Gets the status pointer for a NuDCL.
GetDCLTimeStampPtr(NuDCLRef): Get the time stamp pointer for a NuDCL.
GetDCLTimeStampPtr(NuDCLRef): Gets the status pointer for a NuDCL.
GetProgram: Finds the first DCL in the pool not preceeded by any other DCL.
SetCurrentTagAndSync: Sets current tag and sync bits.
SetDCLBranch: Set the branch pointer for a NuDCL
SetDCLCallback(NuDCLRef, NuDCLCallback): Sets the callback for a NuDCL.
SetDCLCallback(NuDCLRef, UInt32 *, UInt32 *): Sets a user specified header for a send NuDCL.
SetDCLRanges: Sets the scatter gather list for a NuDCL.
SetDCLStatusPtr: Set the status pointer for a NuDCL
SetDCLTimeStampPtr: Set the time stamp pointer for a NuDCL
SetDCLUserHeaderPtr: Sets a user specified header for a send NuDCL.

AddDCLRange

Adds 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: An 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, NuDCLReceivePacket.

AllocateReceivePacket

Allocates a ReceivePacket NuDCL and appends 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

Allocates a SendPacket NuDCL and appends 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 overridden. 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

Allocates a SendPacket NuDCL and appends 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 IOVirtualRanges.

AllocateSkipCycle

Allocates a SkipCycle NuDCL and appends 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

Adds 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: An 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, NuDCLReceivePacket.

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 @discussion: Applies: Any NuDCLRef.

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.

GetDCLCallback

Gets callback for a NuDCL.

NuDCLCallback ( *GetDCLCallback)(
    NuDCLRef dcl );

Parameters

dcl: The DCL to query.

Return Value

Returns the DCL's callback function or NULL if none is set.

Discussion

Returns the callback function for a DCL.

Applies: Any NuDCLRef.

GetDCLNextDCL

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

GetDCLRanges

Gets the scatter-gather list for a NuDCL

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

Parameters

dcl: The DCL to query.
stopProc: The handler to set.

Return Value

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

Discussion

Applies: NuDCLSendPacketRef, NuDCLReceivePacket.

GetDCLs

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

CFArrayRef ( *GetDCLs)(
    IOFireWireLibNuDCLPoolRef self );

Parameters

self: The NuDCL pool to use.

Return Value

Returns 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

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

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

GetDCLTimeStampPtr(NuDCLRef)

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.

GetDCLTimeStampPtr(NuDCLRef)

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

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

Returns a DCLCommand pointer.

Discussion

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

SetCurrentTagAndSync

Sets 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(NuDCLRef, NuDCLCallback)

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

SetDCLCallback(NuDCLRef, UInt32 , UInt32 )

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

SetDCLRanges

Sets 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

Sets 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, NuDCLReceivePacket.

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.
timeStampPtr: 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.

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.

SetDCLUserHeaderPtr

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

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

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.