diff --git a/doc/fpga_firmware.md b/doc/fpga_firmware.md index c01f864..e422e52 100644 --- a/doc/fpga_firmware.md +++ b/doc/fpga_firmware.md @@ -21,24 +21,115 @@ LED2 is on when the analog acquisition chain is waiting for a trigger. LED3 is on when the timetagger is active (at least one event type is enabled). +LED4 to LED7 are controlled by software via register `LED_STATE`. # Analog acquisition chain -TODO ... +The analog acquisition chain has 2 analog input signals (or 4 channels for a 4-channel device). +The analog signals are simultaneously sampled with ADCs at a fixed sample rate of 125 MSa/s. +Raw ADC samples are 14-bit unsigned integers. + +The FPGA can optionally reduce the sample rate through decimation or averaging. +When a trigger condition occurs, the FPGA collects a sequence of decimated samples and transfers them via DMA. +Continuous streaming acquisition is supported via an auto-trigger mode that triggers immediately when a previous acquisition ends. + +Sample data are queued in a FIFO buffer inside the FPGA before being transferred via DMA. +This FIFO is necessary to hold data for a short time while the DMA engine sets up a DMA transfer. +It can also be used to collect a limited number of samples at the maximum sample rate without decimation, which produces a higher data rate than can be sustained by DMA. +The FIFO has room for 16384 messages. + +## Averaging and decimation + +The ADCs operate at a fixed sample rate of 125 MSa/s. +While the sample rate of the ADC can not be changed, the effective sample rate can be reduced by digital processing in the FPGA. + +The effective sample rate after digital processing is equal to the ADC sample rate divided by the _decimation factor_. +The decimation factor is an integer, configured via register `DECIMATION_FACTOR`, which contains the decimation factor minus 1. +Setting this register to 0 configures decimation factor 1 such that the effective rate is identical to the ADC sample rate. +Setting a higher decimation factor reduces the effective sample rate accordingly. + +The FPGA supports two modes of sample rate reduction: decimation and averaging. +In decimation mode with decimation factor _N_, the FPGA keeps one ADC sample, then discards _N_ - 1 samples, then keeps one ADC sample, discards _N_ - 1 sample and so on. +In averaging mode, the FPGA calculates the sum of each group of _N_ samples. + +Decimation mode has the significant disadvantage that it folds aliased high frequency signals into the downsampled signal. +Averaging mode has the advantage that it suppresses aliasing while also reducing the impact of quantization noise from the ADC. +For these reasons, averaging mode is the best choice in most cases. + +If averaging mode is used with a high decimation factor (1024 or higher), the sum of a group of ADC samples may not fit in a 24-bit sample word. +In this case, the summed value may be shifted right by a configurable number of bit positions, effectively dividing the sum by a power of 2. +Before shifting right, a bias value is added such that the result represents the sum divided by a power of 2 and rounded to the nearest integer, or rounded up in case of a tie. + +We use the term _decimated samples_ to refer to samples that are produced by this sample rate reduction process, even when averaging mode is active, and even when the effective sample rate is equal to the ADC sample rate. + +## Triggered acquisition + +When a trigger occurs, the acquisition chain collects a configurable number of decimated samples. +The number of samples per trigger is configured via register `RECORD_LENGTH`. When auto-trigger mode is active, the acquisition chain triggers continuously. A new trigger occurs as soon as acquisition for the previous trigger has ended, after a dead time controlled by `TRIGGER_DELAY`. In this mode, the decimation factor must be at least 2 (or at least 4 in 4-channel mode). -If `TRIGGER_DELAY` is zero, sampling continues accross at a fixed pace controlled by the decimation factor. -This makes it possible to set up continuous streaming data acquisition. +If `TRIGGER_DELAY` is zero, sampling continues accross acquisitions at a fixed pace controlled by the decimation factor. +This makes it possible to set up continuous streaming sampling. When external triggering is active, sampling starts when the specified external trigger condition occurs, after a delay of `TRIGGER_DELAY` samples. The external trigger event is subject to a jitter of 1 sample (8 ns). Further trigger events are ignored until acquisition for the previous trigger has ended. -TODO : DMA data format +When auto-trigger mode and external trigger mode are both disabled, the acquisition chain remains idle. +In this mode, a trigger event can be forced by an explicit action from software. -TODO : LEDs +## Output data format + +The output from the analog acquisition chain is a sequence of 64-bit messages. +Three types of messages are used: + +* Sample messages, containing a pair of samples from two channels. +* Trigger messages, emitted when a triggered acquisition starts. +* Overflow messages, emitted when the internal data buffer overflows. + +### Acquisition sample message + +| Bits | Field name | Description | +|---------|---------------|-------------| +| 63 : 56 | msg_type | Fixed value 0x10 | +| 55 : 52 | channel1 | Value 0x1 or 0x3 to indicate channel IN2 or IN4. | +| 51 : 48 | channel0 | Value 0x0 or 0x2 to indicate channel IN1 or IN3. | +| 47 : 24 | sample1 | Sample value from channel IN2 or IN4. | +| 23 : 0 | sample0 | Sample value from channel IN1 or IN3. | + +In 2-channel mode, a sample message is emitted for each decimated sample produced during a triggered acquisition. +Each sample message contains a pair of samples from channels IN1 and IN2. + +In 4-channel mode (only supported for 4-channel devices), a pair of sample messages is emitted for each decimated sample. +The first message of each pair contains samples from channels IN1 and IN2. +The second message of each pair contains samples from channels IN3 and IN4. + +Samples are unsigned 24-bit integers. +In decimation mode (averaging off), the value represents the ADC code of the first sample of the decimation group. +In averaging mode, the value represents the sum of all ADC codes in the decimation group. + +### Acquisition trigger message + +| Bits | Field name | Description | +|---------|---------------|-------------| +| 63 : 56 | msg_type | Fixed value 0x11 | +| 47 : 0 | timestamp | Timestamp in units of 8 ns | + +A trigger message is emitted when a triggered acquisition starts. +The trigger message is emitted before the first sample of the acquisition. + +The trigger timestamp represents the moment when integration of the first sample starts. + +### Acquisition overflow message + +| Bits | Field name | Description | +|---------|---------------|-------------| +| 63 : 56 | msg_type | Fixed value 0x40 | + +An overflow message is emitted when the internal data buffer overflows. +It marks the point in the message sequence where an unknown number of messages have been discarded. # Timetagger