Data Structures
union	tCItrigConfig

Macros
#define	BYTES_PER_PIXEL(bitsPerPixel) (((bitsPerPixel) == 36) ? (6) : (((bitsPerPixel) + 7) >> 3))

Enumerations
enum	tBFsplitEnums { kBFsplitVertical = 0, kBFsplitHorizontal = 1, kBFupsideDownA = 0x10, kBFupsideDownB = 0x20 }

enum	kCIVTrigModeEnum { kCItrigUnknown = -1, kCItrigInvalid = 0, kCItrigFreeRun, kCItrigPerFrame, kCItrigQualified, kCItrigOneShot, kCItrigOneShotStartAStopA, kCItrigOneShotStartAStopAlevel }

Functions
tCIRC	CiDrvrBuffConfigure (tCIp cip, tCIU32 count, tCIU32 hROIoffset, tCIU32 hROIsize, tCIU32 vROIoffset, tCIU32 vROIsize)
	Driver allocates DMA resources. More...

tCIRC	CiUserBuffConfigure (tCIp cip, tCIU32 count, tCIU8 *buffer, tCIU64 bufferBytes, tCIU32 hROIoffset, tCIU32 hROIsize, tCIU32 vROIoffset, tCIU32 vROIsize)
	User allocates DMA resources. More...

tCIRC	CiUserBuffConfigureSG (tCIp cip, tCIU32 nSGentry, tCISGP sgList, tCIU32 hROIoffset, tCIU32 hROIsize, tCIU32 vROIoffset, tCIU32 vROIsize)
	Scatter-gather DMA resources. More...

tCIRC	CiUserBuffConfigureSplit (tCIp cipA, tCIU32 hROIoffsetA, tCIU32 hROIsizeA, tCIU32 vROIoffsetA, tCIU32 vROIsizeA, tCIp cipB, tCIU32 hROIoffsetB, tCIU32 hROIsizeB, tCIU32 vROIoffsetB, tCIU32 vROIsizeB, tCIU32 nFrames, tCIU8 *userBuffer, tCIU64 buffSz, tCIU32 vertHoriz)
	DMA 2 VFG into one user buffer. More...

tCIRC	CiUserBuffConfigureEvenOdd (tCIp cipEven, tCIp cipOdd, tCIU32 hROIoffset, tCIU32 hROIsize, tCIU32 vROIoffset, tCIU32 vROIsizeOdd, tCIU32 nFrames, tCIU8 *userBuffer, tCIU64 buffSz)
	DMA 2 VFG into one user buffer. More...

tCIRC	CiBufferInterrogate (tCIp cip, tCIU32 nFrames, tCIU32 bitsPerPix, tCIU32 hROIoffset, tCIU32 hROIsize, tCIU32 vROIoffset, tCIU32 vROIsize, tCIU32 *stride)
	Return DMA resource description. More...

tCIRC	CiMapFrameBuffers (tCIp cip, tCIU32 nzWrite, tCIU32 nPtrs, tCIU8 **uPtrs)
	Returns user ptrs to frame buff(s). More...

tCIRC	CiUnmapFrameBuffers (tCIp cip)
	Release user access to DMA buffs. More...

tCIRC	CiTrigConfigure (tCIp cip, tCItrigConfig vCfg, tCItrigConfig hCfg)
	Configure vert/horiz data trig. More...

tCIRC	CiTrigConfigGet (tCIp cip, tCItrigConfig vCfg, tCItrigConfig hCfg, tCIU32 *mode)
	Retrieve current trigger setup. More...

tCIRC	CiTrigModeSet (tCIp cip, tCIU32 mode)
	Set vertical trigger mode. More...

Detailed Description

Macro Definition Documentation

◆ BYTES_PER_PIXEL

#define BYTES_PER_PIXEL ( bitsPerPixel ) (((bitsPerPixel) == 36) ? (6) : (((bitsPerPixel) + 7) >> 3))

Enumeration Type Documentation

◆ kCIVTrigModeEnum

enum kCIVTrigModeEnum

Enumerator
kCItrigUnknown	trig mode not known to library
kCItrigInvalid	invalid trigger mode
kCItrigFreeRun	board is slave to camera
kCItrigPerFrame	trigger assert starts frame
kCItrigQualified	acquire while trigger asserted
kCItrigOneShot	trig asserts starts frame Only valid on Cyton class VFG
kCItrigOneShotStartAStopA	acquire while trigger asserted
kCItrigOneShotStartAStopAlevel	acq wh/trgr asserted; wait hi/lo

◆ tBFsplitEnums

enum tBFsplitEnums

Enumerator
kBFsplitVertical
kBFsplitHorizontal
kBFupsideDownA	VFG A fills frame bottom up.
kBFupsideDownB	VFG B fills frame bottom up.

Function Documentation

◆ CiBufferInterrogate()

tCIRC CiBufferInterrogate	(	tCIp	cip,
		tCIU32 *	nFrames,
		tCIU32 *	bitsPerPix,
		tCIU32 *	hROIoffset,
		tCIU32 *	hROIsize,
		tCIU32 *	vROIoffset,
		tCIU32 *	vROIsize,
		tCIU32 *	stride
	)

Return DMA resource description.

The ROI returned is the actual hardware setting. It may differ from the values requested in CiDrvrBuffConfigure() or CiUserBuffConfigure() due to hardware restrictions on 32b/64b transfer boundaries.

NOTE: When split DMA is configured the original caller gets 0 h/v ROI offsets, gets h/v ROI size and stride for the merged buffer.

Parameters

cip	this frame grabber
nFrames	number of frames returned here
bitsPerPix	bits per pixel
hROIoffset	skip pixels at camera line start
hROIsize	valid pixels within camera line
vROIoffset	skip rows at frame buffer start
vROIsize	valid rows within frame buffer
stride	bytes between adjacent rows

◆ CiDrvrBuffConfigure()

tCIRC CiDrvrBuffConfigure	(	tCIp	cip,
		tCIU32	count,
		tCIU32	hROIoffset,
		tCIU32	hROIsize,
		tCIU32	vROIoffset,
		tCIU32	vROIsize
	)

Driver allocates DMA resources.

Pass zeros to ROI parameters to retain camera/config file values

NOTE: Pass count==0 to release all DMA buffers.

NOTE: The hROIsize*vROIsize must specify a multiple of 8 bytes.

Parameters

cip	this frame grabber
count	# frame buffers desired; 0=>free
hROIoffset	skip pixels at camera line start
hROIsize	valid pixels within camera line
vROIoffset	skip rows at frame buffer start
vROIsize	valid rows within frame buffer

◆ CiMapFrameBuffers()

tCIRC CiMapFrameBuffers	(	tCIp	cip,
		tCIU32	nzWrite,
		tCIU32 *	nPtrs,
		tCIU8 ***	uPtrs
	)

Returns user ptrs to frame buff(s).

NOTE: The frame buffers are kernel memory. This call maps them into user space. Do NOT free the frame pointers.

NOTE: DMA memory cannot be reconfigured so long as any process/thread has an active map of the DMA buffers.

NOTE: The nzWrite parameter should be 0 if the VFG was opened with kCIBO_readOnly access. In the absence of kernel PAT (page attribute table) support there is always rd/wr access to the frame buffers. If the kernel is using PAT then write access to the frame buffers is controlled by the modeFlags argument to CiVFGopen().

NOTE: When user scatter-gather DMA is configured this function returns pointers to a dummy frame. The original information used to build the scatter-gather DMA specification shuld be used to access the data frames.

NOTE: When split DMA is configured the original caller gets pointers offset from the original userBuffer pointer; both VFG get identical pointers valid for the merged ROI. Any access from another process/thread gets pointers to a dummy frame.

Parameters

cip	this frame grabber
nzWrite	0 => read only; else read/write
nPtrs	rtns number of frame pointers
uPtrs	rtns frame pointers

◆ CiTrigConfigGet()

tCIRC CiTrigConfigGet	(	tCIp	cip,
		tCItrigConfig *	vCfg,
		tCItrigConfig *	hCfg,
		tCIU32 *	mode
	)

Retrieve current trigger setup.

Parameters

cip	this frame grabber
vCfg	vertical trigger configuration
hCfg	horizontal trigger configuration
mode	configured trigger mode

◆ CiTrigConfigure()

tCIRC CiTrigConfigure	(	tCIp	cip,
		tCItrigConfig	vCfg,
		tCItrigConfig	hCfg
	)

Configure vert/horiz data trig.

NOTE: When reconfiguring the trigger it is best to fetch the current configuration (set by the camera file) using CiTrigConfigGet(), modify only the required fields, and then call CiTrigConfigure() with the modifed structs.

Parameters

cip	this frame grabber
vCfg	vertical trigger configuration
hCfg	horizontal trigger configuration

◆ CiTrigModeSet()

tCIRC CiTrigModeSet	(	tCIp	cip,
		tCIU32	mode
	)

Set vertical trigger mode.

Parameters

cip	this frame grabber
mode	one of tCIVTrigModeEnum

◆ CiUnmapFrameBuffers()

tCIRC CiUnmapFrameBuffers ( tCIp cip )

Release user access to DMA buffs.

Parameters

cip	this frame grabber

◆ CiUserBuffConfigure()

tCIRC CiUserBuffConfigure	(	tCIp	cip,
		tCIU32	count,
		tCIU8 *	buffer,
		tCIU64	bufferBytes,
		tCIU32	hROIoffset,
		tCIU32	hROIsize,
		tCIU32	vROIoffset,
		tCIU32	vROIsize
	)

User allocates DMA resources.

Pass zeros to ROI parameters to retain camera/config file values.

NOTE: Each frame of data is page-aligned. Be sure to allocate the buffer with enough space for page-aligned frames. If the buffer size is too small then kCIEinvalidArg is returned.

NOTE: Always call CiMapFrameBuffers() to get the actual frame pointers. The buffer will be re-mapped into the callers memory space with page-aligned frame pointers.

NOTE: Once the user buffer is configured for DMA the memory is locked and will not be unlocked until there are no active maps of the underlying buffer in any process/thread. The VFG must be opened with exclusive write access in order to configure user DMA buffers.

NOTE: The hROIsize*vROIsize must specify a multiple of 8 bytes.

Parameters

cip	this frame grabber
count	# frame buffers desired; 0=>free
buffer	memory for DMA frames
bufferBytes	amount of memory allocated
hROIoffset	skip pixels at camera line start
hROIsize	valid pixels within camera line
vROIoffset	skip rows at frame buffer start
vROIsize	valid rows within frame buffer

◆ CiUserBuffConfigureEvenOdd()

tCIRC CiUserBuffConfigureEvenOdd	(	tCIp	cipEven,
		tCIp	cipOdd,
		tCIU32	hROIoffset,
		tCIU32	hROIsize,
		tCIU32	vROIoffset,
		tCIU32	vROIsizeOdd,
		tCIU32	nFrames,
		tCIU8 *	userBuffer,
		tCIU64	buffSz
	)

DMA 2 VFG into one user buffer.

This function provides high-level support for single camera DMA into two VFG. The camera data is split between even and odd rows. The DMA buffers are merged to provide simple access to all row data.

Both VFG must have exclusive write access.

The hROIsize must be a multiple of 8.

Since the buffers merge even/odd lines there is a single specification for the horizontal and vertical offset/size parameters.

NOTE: The process/thread which calls this function will receive identical valid buffer pointers from CiMapFrameBuffers() on either of the VFG. The buffer pointers are not remapped but are instead offsets from the userBuffer argument as passed into this function.

Other processes/threads calling CiMapFrameBuffers() wil receive pointers to a dummy frame. If multiple processes/threads need to access the data (from, e.g., shared memory passed into this function) then it is the user's responsibility to provide appropriate pointers to the other processes/threads.

NOTE: This function will accept a pointer to memory which is already locked by a driver, e.g., partial-page buffers from another BitFlow VFG or a shmat() pointer. If the memory is not already locked then the BitFlow driver will lock it down and it will remain locked until there are no active maps of the underlying buffer in any process/thread. The VFG must be opened with exclusive write access in order to configure split DMA buffers.

WARNING! If the memory is already locked then the driver does not relock it. In this case it is the caller's responsibility to maintain the locked status of the DMA buffers while any DMA is active on either VFG.

Parameters

cipEven	first frame grabber (even lines)
cipOdd	second frame grabber (odd lines)
hROIoffset	skip pixels at camera line start
hROIsize	valid pixels within camera line
vROIoffset	skip rows at frame buffer start
vROIsizeOdd	1/2 total rows in frame
nFrames	number of DMA frames; 0 => free
userBuffer	buffer for combined DMA
buffSz	size of combined DMA buffer

◆ CiUserBuffConfigureSG()

tCIRC CiUserBuffConfigureSG	(	tCIp	cip,
		tCIU32	nSGentry,
		tCISGP	sgList,
		tCIU32	hROIoffset,
		tCIU32	hROIsize,
		tCIU32	vROIoffset,
		tCIU32	vROIsize
	)

Scatter-gather DMA resources.

This function can be used to support, e.g., single camera DMA into multiple VFG. The camera data can be split left-right, top-bottom or even/odd and this function provides a mechanism for the DMA data to be delivered into contiguous frame buffers without any buffer copying.

Pass zeros to ROI parameters to retain camera/config file values.

NOTE: Scatter-gather entries should be multiples of 8 bytes and each block pointer should be aligned on 4 byte boundaries. The total bytes in the scatter-gather list should be a multiple of the VFG frame size. No scatter-gather entry should straddle a frame boundary. If any of these conditions is not met then kCIEinvalidArg is returned.

NOTE: This function will accept a pointer to memory which is already locked by a driver, e.g., partial-page buffers from another BitFlow VFG or a shmat() pointer. If the memory is not already locked then the BitFlow driver will lock it down and it will remain locked until there are no active maps of the underlying buffer in any process/thread. The VFG must be opened with exclusive write access in order to configure scatter-gather DMA buffers.

WARNING! If the memory is already locked then the driver does not relock it. In this case it is the caller's responsibility to maintain the locked status of the DMA buffers while any DMA is active.

NOTE: When user scatter-gather DMA is configured the function CiMapFrameBuffers() returns pointers to a dummy frame. The original information used to build the scatter-gather DMA specification shuld be used to access the data frames.

NOTE: CiUserBuffConfigureSG() is a low-level library tool used by CiUserBuffConfigureSplit() and CiUserBuffConfigureEvenOdd(). Most callers should use the CiUserBuffConfigureSplit() or the CiUserBuffConfigureEvenOdd() interfaces directly and should avoid this call.

NOTE: MSB set on nSGentry => hard PCI addresses for DMA target (not supported on 32b platform)

NOTE: On Cyton no sgList[] item can specify an s-g entry which crosses a page boundary. Also, each s-g entry must be 16 byte aligned.

Parameters

cip	this frame grabber
nSGentry	# scatter-gather blocks; 0=>free
sgList	scatter-gather buffer list
hROIoffset	skip pixels at camera line start
hROIsize	valid pixels within camera line
vROIoffset	skip rows at frame buffer start
vROIsize	valid rows within frame buffer

◆ CiUserBuffConfigureSplit()

tCIRC CiUserBuffConfigureSplit	(	tCIp	cipA,
		tCIU32	hROIoffsetA,
		tCIU32	hROIsizeA,
		tCIU32	vROIoffsetA,
		tCIU32	vROIsizeA,
		tCIp	cipB,
		tCIU32	hROIoffsetB,
		tCIU32	hROIsizeB,
		tCIU32	vROIoffsetB,
		tCIU32	vROIsizeB,
		tCIU32	nFrames,
		tCIU8 *	userBuffer,
		tCIU64	buffSz,
		tCIU32	vertHoriz
	)

DMA 2 VFG into one user buffer.

This function provides high-level support for single camera DMA into two VFG. The camera data can be split left-right (vertHoriz LSB != 0) or top-bottom (vertHoriz LSB == 0). In addition the kBFupsideDownA/B flags can be added to have either or both VFG DMA the data into the frame buffer bottom-most row first. Without the switches the data DMAs into the frame buffer top-most row first.

Both VFG must have exclusive write access.

If the buffer is split left-right then vROIsizeA must equal vROIsizeB. If the buffer is split top-bottom then hROIsizeA must equal hROIsizeB.

Data from VFG "A" is positioned "left" or "top" in the combined buffer.

The hROIsizeA/B * vROIsize must be a multiple of 8.

NOTE: The process/thread which calls this function will receive identical valid buffer pointers from CiMapFrameBuffers() on either of the VFG. The buffer pointers are not remapped but are instead offsets from the userBuffer argument as passed into this function.

Other processes/threads calling CiMapFrameBuffers() will receive pointers to a dummy frame. If multiple processes/threads need to access the data (from, e.g., shared memory passed into this function) then it is the user's responsibility to provide appropriate pointers to the other processes/threads.

NOTE: This function will accept a pointer to memory which is already locked by a driver, e.g., partial-page buffers from another BitFlow VFG or a shmat() pointer. If the memory is not already locked then the BitFlow driver will lock it down and it will remain locked until there are no active maps of the underlying buffer in any process/thread. The VFG must be opened with exclusive write access in order to configure split DMA buffers.

WARNING! If the memory is already locked then the driver does not relock it. In this case it is the caller's responsibility to maintain the locked status of the DMA buffers while any DMA is active on either VFG.

NOTE: It is OK to specify the two ROI such that one is empty, e.g., zero horizontal and/or vertical size. In the event of an empty ROI for either VFG then a single line of DMA into a bit-bucket buffer is configured for that VFG.

This allows the caller to arbitrarily configure the overall ROI for a single camera/two VFG configuration without any change of call sequence even when data from one of the VFGs is excluded from the desired ROI.

Parameters

cipA	first frame grabber
hROIoffsetA	skip pixels at camera line start
hROIsizeA	valid pixels within camera line
vROIoffsetA	skip rows at frame buffer start
vROIsizeA	valid rows within frame buffer
cipB	second frame grabber
hROIoffsetB	skip pixels at camera line start
hROIsizeB	valid pixels within camera line
vROIoffsetB	skip rows at frame buffer start
vROIsizeB	valid rows within frame buffer
nFrames	number of DMA frames; 0 => free
userBuffer	buffer for combined DMA
buffSz	size of combined DMA buffer
vertHoriz	see tBFsplitEnums (below)

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ BYTES_PER_PIXEL

Enumeration Type Documentation

◆ kCIVTrigModeEnum

◆ tBFsplitEnums

Function Documentation

◆ CiBufferInterrogate()

◆ CiDrvrBuffConfigure()

◆ CiMapFrameBuffers()

◆ CiTrigConfigGet()

◆ CiTrigConfigure()

◆ CiTrigModeSet()

◆ CiUnmapFrameBuffers()

◆ CiUserBuffConfigure()

◆ CiUserBuffConfigureEvenOdd()

◆ CiUserBuffConfigureSG()

◆ CiUserBuffConfigureSplit()