BFLinux
Data Structures | Macros | Enumerations | Functions
Acquisition Setup

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

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

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
cipthis frame grabber
nFramesnumber of frames returned here
bitsPerPixbits per pixel
hROIoffsetskip pixels at camera line start
hROIsizevalid pixels within camera line
vROIoffsetskip rows at frame buffer start
vROIsizevalid rows within frame buffer
stridebytes 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
cipthis frame grabber
count# frame buffers desired; 0=>free
hROIoffsetskip pixels at camera line start
hROIsizevalid pixels within camera line
vROIoffsetskip rows at frame buffer start
vROIsizevalid 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
cipthis frame grabber
nzWrite0 => read only; else read/write
nPtrsrtns number of frame pointers
uPtrsrtns frame pointers

◆ CiTrigConfigGet()

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

Retrieve current trigger setup.

Parameters
cipthis frame grabber
vCfgvertical trigger configuration
hCfghorizontal trigger configuration
modeconfigured 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
cipthis frame grabber
vCfgvertical trigger configuration
hCfghorizontal trigger configuration

◆ CiTrigModeSet()

tCIRC CiTrigModeSet ( tCIp  cip,
tCIU32  mode 
)

Set vertical trigger mode.

Parameters
cipthis frame grabber
modeone of tCIVTrigModeEnum

◆ CiUnmapFrameBuffers()

tCIRC CiUnmapFrameBuffers ( tCIp  cip)

Release user access to DMA buffs.

Parameters
cipthis 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
cipthis frame grabber
count# frame buffers desired; 0=>free
buffermemory for DMA frames
bufferBytesamount of memory allocated
hROIoffsetskip pixels at camera line start
hROIsizevalid pixels within camera line
vROIoffsetskip rows at frame buffer start
vROIsizevalid 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
cipEvenfirst frame grabber (even lines)
cipOddsecond frame grabber (odd lines)
hROIoffsetskip pixels at camera line start
hROIsizevalid pixels within camera line
vROIoffsetskip rows at frame buffer start
vROIsizeOdd1/2 total rows in frame
nFramesnumber of DMA frames; 0 => free
userBufferbuffer for combined DMA
buffSzsize 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
cipthis frame grabber
nSGentry# scatter-gather blocks; 0=>free
sgListscatter-gather buffer list
hROIoffsetskip pixels at camera line start
hROIsizevalid pixels within camera line
vROIoffsetskip rows at frame buffer start
vROIsizevalid 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
cipAfirst frame grabber
hROIoffsetAskip pixels at camera line start
hROIsizeAvalid pixels within camera line
vROIoffsetAskip rows at frame buffer start
vROIsizeAvalid rows within frame buffer
cipBsecond frame grabber
hROIoffsetBskip pixels at camera line start
hROIsizeBvalid pixels within camera line
vROIoffsetBskip rows at frame buffer start
vROIsizeBvalid rows within frame buffer
nFramesnumber of DMA frames; 0 => free
userBufferbuffer for combined DMA
buffSzsize of combined DMA buffer
vertHorizsee tBFsplitEnums (below)