Data Readout¶

The device provides a stream of packets (see Output Data Format) that are read in batches with xtdc4_read().

xtdc4_read() requires xtdc4_read_in as configuration.

xtdc4_read() stores the read batch in a xtdc4_read_out struct.

Every packet needs to be acknowledged before its memory location can be used again by the xTDC4 device.

A typical workflow in an application would be:

Start data acquisition (see Runtime Control).
Read a batch of packets.
Iterate through the batch and process the packets (see Output Data Format for
the data layout). For this purpose, crono_next_packet is provided.
Acknowledge the batch as processed with xtdc4_acknowledge().

Instead of manually acknowledging each batch, each read batch of data can be automatically acknowledged by setting xtdc4_read_in.acknowledge_last_read to true.

The following example highlights the workflow. A complete coding example can be found on github.com/cronologic-de/xtdc_babel or in Section Code Example.

timetagger_read_in read_config;
read_config.acknowledge_last_read = true;
timetagger_read_out read_data;

status = xtdc4_read(device, &read_config, &read_data)
if (status != XTDC4_OK) {
    // handle errors of the call to xtdc4_read
}
else if (read_data.error_code != CRONO_READ_OK)
{
    // handle read errors, e.g., empty packets
}
else
{
    volatile crono_packet *p = read_data.first_packet;
    while (p <= read_data.last_packet)
    {

        /* process data */

        p = crono_next_packet(p);
    }
}

Memory Management¶

The xTDC4 internal FIFOs (first-in, first-out) that buffer data during acquisition.

The data is streamed from the FIFO to the host PC and stored in the host buffer. Data will only be overwritten in the host buffer if it has been acknowledged.

The host buffer is managed by the DMA (direct memory access) driver. The DMA driver can only ever write to the host buffer if enough memory is free. That means, new packets will never overwrite old packets unless they have been acknowledged.

If the host buffer is full, data may be lost. If this occurred, the corresponding packets will have the XTDC4_PACKET_FLAG_HOST_BUFFER_FULL bit of crono_packet.flags will be set. This may result in lost packets.

If the hit rate is too high, the internal FIFOs may fill up. If this is the case, the affected packets will have the XTDC4_PACKET_FLAG_DMA_FIFO_FULL bit of crono_packet.flags will be set. This may result in lost packets. However, only if the XTDC4_PACKET_FLAG_SHORTENED bit of crono_packet.flags is set, packets were actually missed.

xtdc4_read¶

int xtdc4_read(xtdc4_device *device, xtdc4_read_in *in, xtdc4_read_out *out)¶

Read captured data.

Data is read in batches of packets. Pointers to the first and last packets are stored in out.first_packet and out.last_packet.

Parameters:

device – Pointer to an xTDC4 device.
in – Pointer to an xtdc4_read_in struct, configuring the read call.
out – Pointer to an xtdc4_read_out that will be filled by the call.

Returns:

Status code: Same as out.error_code, or XTDC4_INVALID_DEVICE.

xtdc4_acknowledge¶

int xtdc4_acknowledge(xtdc4_device *device, crono_packet *packet)¶

Acknowledge all packets up to packet.

Only acknowledged data can be overwritten by the DMA controller.

Explicitly calling xtdc4_acknowledge is only necessary if xtdc4_read() was called with in.acknowledge_last_read == false.

Note

xtdc4_acknowledge allows freeing up memory early if there will be no call to xtdc4_read() anytime soon.

Note

xtdc4_acknowledge allows keeping data over multiple calls of xtdc4_read(), avoiding unnecessary copying of data.

Attention

After acknowledging a packet, it becomes immediately invalid. It is immediately unsafe to attempt accessing its content.

Parameters:

device – Pointer to an xTDC4 device.
packet – Pointer to a packet. All packets up to this one will be acknowledged.

Returns:

Status code: XTDC4_OK, or XTDC4_INVALID_DEVICE.

crono_next_packet¶

crono_next_packet(current_packet)¶

Convenience macro that jumps to the next crono_packet.

Attention

You must explicitly check that the pointer to the next packet is valid!

Parameters:

current_packet – Pointer to the current packet.

Returns:

Pointer to the next packet.

xtdc4_read_in¶

struct xtdc4_read_in¶

crono_bool_t acknowledge_last_read¶

Automatically acknowledge last readout.

If set, xtdc4_read() automatically acknowledges packets from the last read.

Otherwise, xtdc4_acknowledge() needs to be explicitly called by the user.

xtdc4_read_out¶

struct xtdc4_read_out¶

crono_packet *first_packet¶: Pointer to the first packet that was captured by the call of xtdc4_read().

crono_packet *last_packet¶

Pointer to the last packet that was captured by the call of xtdc4_read().

This packet is still valid. All data after this packet is invalid.

int error_code¶

Error codes.

One of the following:

CRONO_READ_OK¶: 0. Read was successful. No errors occurred.

CRONO_READ_NO_DATA¶: 1. The read attempt did not yield any data.

CRONO_READ_INTERNAL_ERROR¶: 2. Some unhandled error occurred. The xTDC4 device needs to be reinitialized.

CRONO_READ_TIMEOUT¶: 3. Attempt to read packets did not yield data in the given time.

const char *error_message¶

Error message in human-readable form.

This may contain additional information about error_code.