Skip to content

Enhance digitizer block documentation #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lukipedio wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Enhance digitizer block documentation #3

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
68cebf6
Update digitizer.md
lukipedio Apr 11, 2025
af596a1
Merge pull request #1 from lukipedio/lukipedio-patch-1
lukipedio Apr 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 35 additions & 35 deletions docs/digitizer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# Wave Digitizer driver

The Wave Digitizer componet has the function to acquire multiple channels capturing waveform from each one. It is similar to the oscilloscope, but, while the oscilloscope purpose is to monitor the internal process of the firmware, and indeed is not very fast in transfering data, digitizer function is optimized to maximize the speed and the memory usage of the device.
In the Wave Digitizer exist a shared memory for all channels for which the Wave Digitizer has been created. At compile time, SciCompiler defines the total size of this memory and the maximum number of channels. At runtime the user can configure if to enable one, two, four channels. The memory will be partitioned in function of the enable channels.
The Wave Digitizer component has the function to acquire multiple channels, capturing waveform from each one. It is similar to the oscilloscope, but while the oscilloscope purpose is to monitor the internal process of the firmware, and indeed is not very fast in transferring data, the digitizer function is optimized to maximize the speed and the memory usage of the device.
In the Wave Digitizer, a shared memory exists for all channels for which it has been created. At compile time, SciCompiler defines the total size of this memory and the maximum number of channels. At runtime, the user can configure it to enable one, two, or four channels. The memory will be partitioned according to the enabled channels.

It is designed as following: a packet creator block serializes the enabled channels in a common FIFO and transfer data to the PC.
It is designed as follows: a packet creator block serializes the enabled channels in a common FIFO and transfers data to the PC.

Every time a start signal is triggered, the timestamp, the hits and user data are captured, and enqueued in the output FIFO.
Every time a start signal is triggered, the timestamp, the hits, and user data are captured and enqueued in the output FIFO.

It is only possible the specify the number of channels (N) starting from the channel 0. So If N = 2, CH0 and CH1 will be dumped, if N = 4, CH0, CH1, CH2, CH3 will be dumped.
It is only possible the specify the number of channels (N) starting from channel 0. So If N = 2, CH0 and CH1 will be dumped, if N = 4, CH0, CH1, CH2, CH3 will be dumped.

Example with four channels:

Expand All @@ -17,30 +17,30 @@ Example with four channels:
- Only CH0 and CH1 enabled
![](img/dgz02.png)

It is not possible to configre a pre-trigger on the Wave Digitizer. The trigger is always on the first sample. To implement a pre-trigger, it necessary to connect, on each input channel, a delay block with the desired delay (SciCompiler provide fixed and programmable delay block).
It is not possible to configure a pre-trigger on the Wave Digitizer. The trigger is always on the first sample. To implement a pre-trigger, it is necessary to connect, on each input channel, a delay block with the desired delay (SciCompiler provide fixed and programmable delay block).





The readout can be configure to work in two different mode:
- blocking : the `SCISDK_ReadData` function will block until the buffer is full or the timeout is reached.
- non-blocking : the `SCISDK_ReadData` function will return immediately with the number of bytes read.
The readout can be configured to work in two different modes:
- blocking: the `SCISDK_ReadData` function will block until the buffer is full or the timeout is reached.
- non-blocking: the `SCISDK_ReadData` function will return immediately with the number of bytes read.


**Raw Mode**
In raw mode the digitizer do not process packet and provide to the user application the raw data. The user application must be able to process the data and extract the information. Raw mode can be useful in order to save at the maximum speed the data to disk. The user application can be a simple script that save the data in a file. A second application can be used to process the data and extract the waveforms.
In raw mode, the digitizer does not process packets and provides the user application with the raw data. The user application must be able to process the data and extract the information. Raw mode can be useful to save at the maximum speed the data to disk. The user application can be a simple script that save the data in a file. A second application can be used to process the data and extract the waveforms.


## Parameters
The following parameters can be configured:

| Parameter | Acces Mode | Description | Default value |
| --------------------- | ---------- | ---------------------------------------------------------------------------------------- | ------------- |
| acq_len | R/W | maximum number of sample to be transferred per physical FIFO access | 1024 |
| acq_len | R/W | maximum number of samples to be transferred per physical FIFO access | 1024 |
| acq_mode | R/W | select blocking/non-blocking mode | blocking |
| timeout | R/W | set the timout in ms in blocking mode | 100 |
| high_performance | R/W | if true the internal FIFO access lock the bus in priority mode. | false |
| timeout | R/W | set the timeout in ms in blocking mode | 100 |
| high_performance | R/W | If true, the internal FIFO accesses lock the bus in priority mode. | false |
| check_align_word | R/W | if true, check the packet alignment | false |
| data_processing | R/W | set data processing mode: raw, decode | decode |
| enabledch | R/W | number of enabled channels. | --all ch-- |
Expand All @@ -50,25 +50,25 @@ The following parameters can be configured:
| max_ch_samples | R | return the maximum number of samples per channel can be read | |

### Acquisition length
The `acq_len` parameter set the number of sample per channels to be read.
The maximum value depends by tge number of channels enabled. The maximum value is the total size of the shared memory divided by the number of channels enabled.
The driver suggest the maximum value for this parameter reading the `max_ch_samples` parameter.
The `acq_len` parameter sets the number of samples per channel to be read.
The maximum value depends on the number of channels enabled. The maximum value is the total size of the shared memory divided by the number of channels enabled.
The driver suggests the maximum value for this parameter reading the `max_ch_samples` parameter.

### Blocking/Non blocking mode
### Blocking/Non-blocking mode

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.
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 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.
If there is no data at all, the read function will return NI_NO_DATA_AVAILABLE.

### Enable channels
The `enabledch` parameter is the number of enabled channels. It is only possible the specify the number of channels (N) starting from the channel 0. So If N = 2, CH0 and CH1 will be dumped, if N = 4, CH0, CH1, CH2, CH3 will be dumped.
Valid number are from 1 to the maximum number of channels created in SciCompiler.
The `enabledch` parameter is the number of enabled channels. It is only possible the specify the number of channels (N) starting from channel 0. So If N = 2, CH0 and CH1 will be dumped, if N = 4, CH0, CH1, CH2, CH3 will be dumped.
Valid numbers are from 1 to the maximum number of channels created in SciCompiler.

## Data processing mode
The `data_processing` parameter can be used to set the data processing mode. The data processing mode can be set to raw or decode.
In raw mode the data are not processed and the user will receive the raw data from the FPGA. In decode mode the data are processed and the user will receive the data as they are pushed in the FPGA fifo, loosing the concept of packet. The custom packet behavior is the same of the list
In raw mode, the data are not processed, and the user will receive the raw data from the FPGA. In decode mode, the data are processed, and the user will receive the data as they are pushed in the FPGA FIFO, losing the concept of packet. The custom packet behavior is the same as the list
In decode mode the data are analized, divided in packet and it is possible to check the alignment to an aligment word.


Expand All @@ -77,22 +77,22 @@ The following commands are available:

| Command | Description | Parameter |
| --------------------- | ------------------------------------------------------------------------------ | --------- |
| start | Clear the FIFO and start the acqusition | |
| start | Clear the FIFO and start the acquisition | |
| stop | Stop the acquisition | |

Start will clear the digitizer wave.
All digitizer parameter can not be changed while the acquisition is in progress. Stop the digitizer before change any parameter or the property set will be rejected.

## Buffer Allocation
**Raw mode**
In raw mode the buffer must be allocated with the function `SCISDK_AllocateBuffer`. In raw mode it is mandatory to specify the size of the buffer is FIFO word. The size of the FIFO word is 4 bytes (DWORD).
In raw mode, the buffer must be allocated with the function `SCISDK_AllocateBuffer`. In raw mode it is mandatory to specify the size of the buffer is FIFO word. The size of the FIFO word is 4 bytes (DWORD).
```c
SCISDK_AllocateBuffer(<path to list>, T_BUFFER_TYPE_RAW, (void**)&dgtz_data, <number of word>)
```

**Decoded data**
The buffer is allocated using the `SCISDK_AllocateBuffer` function. The buffer is freed using the `SCISDK_FreeBuffer` function.
There is no argument to be pass to the `SCISDK_AllocateBuffer` function. The allocator will allocate the buffer with the size for each channe large enough to contain the maximum number of samples per channel in the configuration with a single channel enabled (the worst case).
There is no argument to be passed to the `SCISDK_AllocateBuffer` function. The allocator will allocate the buffer with the size for each channel large enough to contain the maximum number of samples per channel in the configuration with a single channel enabled (the worst case).

```c
SCISDK_AllocateBuffer(<path to list>, T_BUFFER_TYPE_DECODED, (void**)&dgtz_data)
Expand All @@ -117,16 +117,16 @@ The packet structure is the following:
| CH0_0 | CH1_0 | CH2_0 | CH3_0 | CH0_1 | CH1_1 | CH2_1 | CH3_1 |
| CH0_2 | CH1_2 | CH2_2 | CH3_2 | CH0_3 | CH1_3 | CH2_3 | CH3_3 |

The header is composed by the following fields:
The header is composed of the following fields:
- Constant word:(32 bits) 0xFFFFFFFF
- Timestamp: (64 bits) timestamp
- Start counter: (32 bits) packet index
- Hits data: (64 bits) every bit represent a channel. If the bit is 1 the channel has triggered. LSB is the first channel
- User data: (32 bits) user defined dword data
- filler: the size of the filler is indicated in the table below
- Filler: the size of the filler is indicated in the table below

In order to optimize the access speed to the memory, the size of the header must be alligned to the size of the data packet; this is met by adding a padding (filler) to the header.
This table indicate the size of the filler
This table indicates the size of the filler

| Number of channels | FIFO word size (DW) | Filler size |
| ------------------ | ------------------- | ----------- |
Expand All @@ -138,7 +138,7 @@ This table indicate the size of the filler
| 32 | 16 | 9 |
| 64 | 32 | 25 |

The channels are ordered as follow: every WORD (16 bit / 2 bytes) there is a channel.
The channels are ordered as follows: every WORD (16 bit / 2 bytes,) there is a channel.
All channels are ordered from the first to the last. In the list there is just the data of the enabled channels. After a group of channels another sample for all the channels is stored.
So the order is the following:

Expand Down Expand Up @@ -181,7 +181,7 @@ The `info` field contains the information about the buffer:

**Decoded data**

In decode mode the user will receive data already decoded. The user has not to care about the packet structure and the alignment. The driver will produce in output an array with the waveform for each channel. The data are stored in the following structure:
In decode mode, the user will receive data already decoded. The user does not care about the packet structure and the alignment. The driver will produce in output an array with the waveform for each channel. The data are stored in the following structure:

```c
typedef struct {
Expand All @@ -207,12 +207,12 @@ The `magic` field is a constant value that can be used to check if the buffer is
| Sample | 0 .... n-th | 0 .... n-th | 0 .... n-th | 0 .... n-th |


The `hits` field contains the information about the channels that have triggered. The LSB is the first channel.
The `hits` field contains the information about the channels that have been triggered. The LSB is the first channel.
The `timecode` field contains the timestamp of the event.
The `counter` field contains the index of the event.
The `user` field contains the user defined dword data.
The `user` field contains the user-defined dword data.
The `info` field contains the information about the buffer:
- `samples`: the maximum number of samples per channel when all the channels are enabled. If less channels are enabled the number of samples will be less channels are enabled this number should be scaled accordingling to the following formula:
- `samples`: the maximum number of samples per channel when all the channels are enabled. If fewer channels are enabled, the number of samples will be fewer channels are enabled this number should be scaled accordingling to the following formula:
`max_acq_len = samples * (total_channels/enabled_channels)`

- `valid_samples`: the real number of valid samples in the buffer. This number can be up to `samples * enabled_channels` if just one channel is enabled.
Expand Down Expand Up @@ -390,4 +390,4 @@ The `info` field contains the information about the buffer:
}
}
}
```
```