Data Readout¶

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

timetagger4_read() requires timetagger4_read_in as configuration.

timetagger4_read() stores the read batch in a timetagger4_read_out struct.

Every packet needs to be acknowledged before its memory location can be used again by the TimeTagger4 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 timetagger4_acknowledge().

Instead of manually acknowledging each batch, each read batch of data can be automatically acknowledged by setting timetagger4_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 = timetagger4_read(device, &read_config, &read_data)
if (status != TIMETAGGER4_OK) {
    // handle errors of the call to timetagger4_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 timetagger4_read(timetagger4_device *device, timetagger4_read_in *in, timetagger4_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 a TimeTagger4 device.
in – Pointer to a timetagger4_read_in struct, configuring the read call.
out – Pointer to a timetagger4_read_out that will be filled by the call.

Returns:

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

int timetagger4_acknowledge(timetagger4_device *device, volatile crono_packet *packet)¶

Acknowledge all packets up to packet.

Only acknowledged data can be overwritten by the DMA controller.

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

Note

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

Note

timetagger4_acknowledge allows keeping data over multiple calls of timetagger4_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 a TimeTagger4 device.
packet – Pointer to a packet. All packets up to this one will be acknowledged.

Returns:

Status code: TIMETAGGER4_OK, or TIMETAGGER4_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 timetagger4_read_in¶

crono_bool_t acknowledge_last_read¶

Automatically acknowledge last readout.

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

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

struct timetagger4_read_out¶

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

crono_packet *last_packet¶

Pointer to the last packet that was captured by the call of timetagger4_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 timetagger4_read_out.first_packet and timetagger4_read_out.last_packet will not point to valid packets in memory.

CRONO_READ_INTERNAL_ERROR¶: Evaluates to 2. Some unhandled error occurred. The TimeTagger4 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 TimeTagger4 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.