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);
    }
}

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.

int xtdc4_acknowledge(xtdc4_device *device, volatile 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(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.

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.

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¶: Evaluates to 0. Read was successful. No errors occurred.

CRONO_READ_NO_DATA¶

Evaluates to 1. The read attempt did not yield any data.

The pointers xtdc4_read_out.first_packet and xtdc4_read_out.last_packet will not point to valid packets in memory.

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

CRONO_READ_TIMEOUT¶: Evaluates to 3. This error code is currently not used.

CRONO_READ_WRONG_STATE¶: Evaluates to 4. The xTDC4 is in a wrong state (see Runtime Control).

CRONO_READ_INVALID_ARGUMENTS¶: Evaluates to 5.

const char *error_message¶

Error message in human-readable form.

This may contain additional information about error_code.