 |
SciSDK Library
SDK for SciCompiler projects
|
|
SciSDK Library
SDK for SciCompiler projects
|
The frame driver is a special list that allow to transfer data from FPGA to the PC as pixelated images. Each pixel is a 32 bit word, the value of the pixel is the value of the input signal at the time of the pixel acquisition. The value of the pixel can be:
Frame transfer works in list mode. Inside the FPGA a FIFO store the packet of data each time a trigger events is detected. Trigger mode includes: external trigger, or between hits of all channels, and between all channels, trigger for a master board.
When configured in internal trigger (or/and) a coincidence windows allows a user to define a time window in which the trigger should active. The coincidence window is defined in FPGA clock cycles. For example if the sapling clock is 125 MHz and the coincidence window is 1000 FPGA clock cycles, the coincidence window is 8 us. If trigger is set to and, all channels must be active the DV input (hit) within 8us otherwise the event is ignored.
It is possible to received decoded and raw data. Raw data is the pure content of the FIFO buffer, including headers of the packet indeed should be recostructed by the user using the suggested algorithm. Decoded data is a struct contating all the pixels and the information about the event. The struct is defined in the scisdk_frame.h file.
On the PC side a buffer can be allocated using the SCISDK_AllocateBuffer function. The buffer is freed using the SCISDK_FreeBuffer function.
The SCISDK_AllocateBuffer function requires to specify a size paramter that has a different meaning depending on the buffer type:
The SCISDK_ReadData function will read an amount of data according to the sizes programmaed in the buffer
The readout can be configure to work in two different mode:
SCISDK_ReadData function will block until the buffer is full or the timeout is reached.SCISDK_ReadData function will return immediately with the number of bytes read.More over the list can be configured to work:
SCISDK_ReadData function will read the data from the hardware FIFO when the user call the function.SCISDK_ReadData function will read the data from the thread buffer. Thread mode increase the perfomance of the list because, while the use elaborate the previous data, the list accumulate next data in the thread buffer.The following parameters can be configured:
| Parameter | Acces Mode | Description | Default value |
|---|---|---|---|
| acq_mode | R/W | select blocking/non-blocking mode | blocking |
| data_processing | R/W | set data processing mode: raw, decode | decode |
| timeout | R/W | set the timout in ms in blocking mode | 100 |
| thread | R/W | enable the internal thread: true/false | false |
| high_performance | R/W | if true the internal FIFO access lock the bus in priority mode. | false |
| threaded_buffer_size | R/W | size in dword of the internal buffer | 100000 |
| trigger_mode | R/W | set trigger mode: or, and, trig, sync_trig | or |
| trigger_mask | R/W | set bit to 1 to mask specific channel from trigger | 0x00000000 |
| wait_coincidence | R/W | coincidence window width from trigger (clk cycles) waiting for all channels energy | 0 |
| sync_mode | R/W | set the ip as master/slave | master |
| buffer_type | R | get buffer type: SCISDK_OSCILLOSCOPE_RAW_BUFFER or SCISDK_OSCILLOSCOPE_DECODED_BUFFER |
In blocking mode the SCISDK_ReadData function will block until the buffer is full or the timeout is reached. In non-blocking mode the SCISDK_ReadData function will return immediately with the number of bytes read. The maximum number of bytes that can be read is the size of the buffer allocated with the function SCISDK_AllocateBuffer. In blocking mode the timeout is set with the timeout parameter. The timeout is expressed in ms. In non-blocking mode the timeout is not used. In both mode, if the buffer is fill with even just a single word the function will return NI_OK. If there is no data at all the read function will return NI_NO_DATA_AVAILABLE.
In threaded mode the frame will start a thread that will read the data from the hardware FIFO and store it in an internal buffer (thread buffer). The SCISDK_ReadData function will read the data from the thread buffer. While in polling mode, if the user do not call the SCISDK_ReadData function, the FIFO in the FPGA can be full and the data will be lost. In threaded mode the data are stored in the thread buffer automatically. The internall thread will poll the FPGA to check if data is available and will store it in the thread buffer. Thread mode increase the perfomance of the frame because, but consume continuously the communication bandiwdth between the FPGA and the PC. The user lost the control on how much time the specific frame will access to the shared bus.
We discurage to enable this parameter. If enabled, the highe performace mode force the internal physical ReadFIFO function to ignore the word available field of the FIFO. When this parameter is disable, the ReadFIFO function check the word available field of the FIFO and will make a read only if this number if not 0. More over the read size will be the minimum between word available and acq_len parameter. In this way the ReadFIFO function will not lock the bus for a long time. In high perforamnce mode, the ReadFIFO will always setup a read cycle with size equal to acq_len parameter. This will lock the bus for a long time untill all data are received. This will increase significantly the transfer speed but no other access, even to read/write register can be done until all data are received or the timeout is reached. Use this mode only if you are sure that the bus is not shared with other readout block and you don't need
The following commands are available:
| Command | Description | Parameter |
|---|---|---|
| start | Clear the FIFO and start the acqusition | |
| stop | Stop the acquisition |
Start will clear the FIFO content, create the internal thread and allocate the thread buffer if thread mode is enable and start the acquisition. All list parameter can not be changed while the acquisition is in progress. Stop the list before change any parameter or the property set will be rejected.
The buffer is allocated using the SCISDK_AllocateBuffer function. The buffer is freed using the SCISDK_FreeBuffer function. When used in RAW mode, because the frame is a FIFO, is not possible to know a priori the number of bytes that will be transferred. The SCISDK_AllocateBuffer take indeed an extra parameter to specify the size of the buffer (in word) on the PC side; the SCISDK_ReadData function will try to read the maximum number of bytes that can fit in the buffer.
When used in DECODED mode the driver knows the number of pixel and the structure of the header and will allocate the buffer accordingly. The user specify the size in order to create a buffer capable to store multiple events (improving the performance of the readout).
This is an example on how allocate a frame buffer RAW:
This example allocate a buffer with 1000 words:
This is an example on how allocate a frame buffer DECODED:
This example allocate a buffer with 10 events:
The IP do not support sparse data format indeed, indipendelty from the datavalid (DV) status, all pixel will be transfered to the PC, so the size of raw event or the number of pixel in the decoded event will be always the same.
The data output structure is the following:
magic : magic number to identify the buffer type. It is set to SCISDK_FRAME_RAW_BUFFER_MAGIC data : it's the array of the raw data. The data is stored as a uint32_t word. In order to access to the data the user must implement a proper decoding function.
The decode algorithm appears to be a state machine that processes a sequence of bytes in a specific order to extract and decode information from them.
The algorithm reads bytes from a queue called pQ and stores the decoded information in a data structure called p. p is a SCISDK_FRAME_RAW_BUFFER struct. The state machine has the following states, in every step the algorithm pop the front element of the queue pQ and processes it:
HEADER_1: In this state, the algorithm checks if the front element of the queue pQ is equal to 0xFFFFFFFF. If it is, the state machine transitions to the HEADER_2 state. Otherwise, it remains in the HEADER_1 state discardinf data.
HEADER_2: In this state, the algorithm checks if the front element of the queue pQ is equal to 0x12345678. If it is, the state machine transitions to the TIMESTAMP_1 state. Otherwise, it transitions back to the HEADER_1 state.
TIMESTAMP_1: In this state, the algorithm extracts the front element of the queue pQ and stores it as the most significant 32 bits of a 64-bit timestamp in p. The state machine then transitions to the TIMESTAMP_2 state.
TIMESTAMP_2: In this state, the algorithm extracts the front element of the queue pQ and stores it as the least significant 32 bits of the timestamp in p. The state machine then transitions to the COUNT_IN_1 state.
COUNT_IN_1: In this state, the algorithm extracts the front element of the queue pQ and stores it as the most significant 32 bits of a 64-bit trigger count in p. The state machine then transitions to the COUNT_IN_2 state.
COUNT_IN_2: In this state, the algorithm extracts the front element of the queue pQ and stores it as the least significant 32 bits of the trigger count in p. The state machine then transitions to the COUNT_OUT_1 state.
COUNT_OUT_1: In this state, the algorithm extracts the front element of the queue pQ and stores it as the most significant 32 bits of a 64-bit event count in p. The state machine then transitions to the COUNT_OUT_2 state.
COUNT_OUT_2: In this state, the algorithm extracts the front element of the queue pQ and stores it as the least significant 32 bits of the event count in p. The state machine then transitions to the HITS_1 state.
HITS_1: In this state, the algorithm extracts the front element of the queue pQ and stores it as the number of hits in p. If the number of channels is greater than 32, the state machine transitions to the HITS_2 state. Otherwise, it transitions to the PIXELS state.
HITS_2: In this state, the algorithm extracts the front element of the queue pQ and stores it as the number of additional hits in p. The state machine then transitions to the PIXELS state.
PIXELS: In this state, the algorithm extracts all the pixels data value. The use must provide the information of the number of pixel present in the IP from the front of the queue pQ and
The data output structure is the following:
magic : magic number to identify the buffer type. It is set to SCISDK_LIST_RAW_BUFFER_MAGIC pixel : it's the array of the pixel data. The data is stored as an array of uint32_t word. n : it's the number of pixel in the event. timestamp : it's the timestamp of the event. trigger_count : it's the trigger count of the event. It counts the number of trigger events for the programmed trigger soruce even if the trigger is not accepted by the IP because it is busy. event_count : it's the event counter of the accepted trigger. hits : it's the hit flag buffer. It is a 64 bit word where each bit represents a pixel. If the bit is set to 1, the pixel has been hit.
You can find the labview file for this example here
You can find the labview file for this example here
This example print a decoded frame to the console.
Suppose to have dump the raw data field of the frame into a file called data.bin.
Suppose to have dump the raw data field of the frame into a file called data.bin
1.9.8