Consume Buffers

The driver and library initialize for circular buffers. The data fills the first frame buffer, then the second, and so forth, into the last of the nFrame buffers configured. After the n'th frame buffer is filled the next frame fills the first frame buffer again. More...

Enumerations
enum	tCIbufferModeEnums { kCIcircularBuffers = 0, kCIconsumeBuffers = 1 }
enum	tCIbufferStatusEnums {   kCIbsUnassigned = 0, kCIbsBusy = 1, kCIbsPending = 2, kCIbsFilled = 3,   kCIbsUnknown = 10 }

Functions
tCIRC	CiSetBufferMode (tCIp cip, tCIU32 mode)
	Set the VFG/library buffer mode. More...
tCIRC	CiGetBufferMode (tCIp cip, tCIU32 *mode)
	Get the VFG/library buffer mode. More...
tCIRC	CiGetBufferID (tCIp cip, tCIU32 frameID, tCIU32 *buffID)
	Get the buffer ID of a frame. More...
tCIRC	CiGetBufferStatus (tCIp cip, tCIU32 buffID, tCIU32 *status)
	Get the status of a frame buffer. More...
tCIRC	CiReleaseBuffer (tCIp cip, tCIU32 buffID)
	Release a frame buffer for DMA. More...

Detailed Description

The driver and library initialize for circular buffers. The data fills the first frame buffer, then the second, and so forth, into the last of the nFrame buffers configured. After the n'th frame buffer is filled the next frame fills the first frame buffer again.

After the board is initialized and before any buffers are configured the VFG and the library can be set to a "consume buffers" mode of operation. In this mode the user releases buffers which will be queued for subsequent DMA. The order of buffer fill is determined by how the user releases individual buffers from the suite of configured buffers.

When DMA is configured in "consume buffers" mode all frame buffers have initial status of kCIbsUnassigend and there are no buffers available for frame data.

The user must explicitly call CiReleaseBuffer() for each bufferID (0..nFrames-1) in order to make buffers available for frame data.

When operating in "consume buffers" mode there is no deterministic way to associate a frameID (count of EOF interrupts) with a bufferID (index into the list of configured buffers). The function CiGetBufferID() will associate a bufferID with a frameID. However, knowledge of the bufferID/frameID association will "age out" of the data structures if the user hangs onto the a buffer through multiple subsequent EOF interrupts.

Once acquisition is started the user accesses data as usual via, e.g., CiGetOldestNotDeliveredFrame() or CiGetMostRecentFrame(). The CiGetBufferID() call should be made immediately after the CiGetOldestNotDeliveredFrame() or CiGetMostRecentFrame() call which identifies the frameID associated with the buffer.

WHEN OPERATING IN "consume buffers" MODE THE bufferID SHOULD BE IMMEDIATELY FETCHED AND REMEMBERED UNTIL THE BUFFER CAN BE RELEASED FOR SUBSEQUENT DMA.

Any buffer can be kept for as long as the user desires. So long as there are sufficient buffers available for all new frame data there is no restriction on releasing any specific buffer (or buffers) back for subsequent DMA.

When the user is done with a buffer it is necessary to call CiReleaseBuffer(), passing in the bufferID which was returned by CiGetBufferID(). The buffer will be marked as kCIbsPending and is owned by the driver until it is once again filled with new data.

If insufficient buffers are released for new DMA data the driver will immediately stop DMA when the available buffers are exhausted. The CiGetMostRecentFrame() and CiGetOldestNotDeliveredFrame() functions will return kCIEbufferUnderrunErr. These functions will also return non-NULL framePtr values for any valid buffers which were filled before the DMA was stopped. When all valid data is exhausted the functions will return kCIEnoNewData.

NOTE: The user must continue to call CiGetOldestNotDeliveredFrame() until kCIEnoNewData is returned. When the buffers are processed be sure to call CiReleaseBuffer(). Failure to do so will result in abandoned buffers which are never again used for DMA.

A kCIEbufferUnderrunErr status is visible in the CiAqGetStatus() return and cleared at the next start of acquisition and by any CiAqSWreset() call.

Enumeration Type Documentation

tCIbufferModeEnums

enum tCIbufferModeEnums

Enumerator
kCIcircularBuffers
kCIconsumeBuffers

tCIbufferStatusEnums

enum tCIbufferStatusEnums

Enumerator
kCIbsUnassigned	never released (owned by user) After DMA is configured all buffers have kCIbsUnassigned status
kCIbsBusy	in DMA queue (owned by drvr) After a buffer is released it has one of these two status values
kCIbsPending	ready for DMA (owned by drvr)
kCIbsFilled	frame complete (owned by user) After a buffer is filled it has this status value
kCIbsUnknown	Unknown status

Function Documentation

CiGetBufferID()

tCIRC CiGetBufferID	(	tCIp	cip,
		tCIU32	frameID,
		tCIU32 *	buffID
	)

Get the buffer ID of a frame.

Parameters

cip	this frame grabber
frameID	from CiGetMostRecentFrame() or CiGetOldestNotDeliveredFrame()
buffID	buffer ID

CiGetBufferMode()

tCIRC CiGetBufferMode	(	tCIp	cip,
		tCIU32 *	mode
	)

Get the VFG/library buffer mode.

Parameters

cip	this frame grabber
mode	circular or consume

CiGetBufferStatus()

tCIRC CiGetBufferStatus	(	tCIp	cip,
		tCIU32	buffID,
		tCIU32 *	status
	)

Get the status of a frame buffer.

Parameters

cip	this frame grabber
buffID	from CiGetBufferID()
status	status of frame buffer

CiReleaseBuffer()

tCIRC CiReleaseBuffer	(	tCIp	cip,
		tCIU32	buffID
	)

Release a frame buffer for DMA.

Parameters

cip	this frame grabber
buffID	from CiGetBufferID()

CiSetBufferMode()

tCIRC CiSetBufferMode	(	tCIp	cip,
		tCIU32	mode
	)

Set the VFG/library buffer mode.

If the caller lacks write permission kCIEnoWrPermission is returned.

If DMA is already configured kCIEresourceBusy is returned.

Parameters

cip	this frame grabber
mode	circular or consume