Initialization¶

To initialize a TimeTagger4:

Get a default set of initialization parameters using timetagger4_get_default_init_parameters().
Change parameters of timetagger4_init_parameters according to your specific requirements.
Initialize a TimeTagger4 device using timetagger4_init().
Release all resources using timetagger4_close().

The following example shows a basic setup of a TimeTagger4 using the default initialization parameters. A complete coding example can be found on github.com/cronologic-de/xtdc_babel or in Section Code Example.

// get a default set of initialization parameters
timetagger4_init_parameters params;
status = timetagger4_get_default_init_parameters(&params);
if (status != TIMETAGGER4_OK) { /* handle error */ }

// initialize a device
const char* err_message;
timetagger4_device* device = timetagger4_init(&params, &status, &err_message);
if (status != TIMETAGGER4_OK) { /* handle error */ }

// use device

// after usage, free up all resources by closing the device
status = timetagger4_close(device)

timetagger4_get_default_init_parameters¶

int timetagger4_get_default_init_parameters(timetagger4_init_parameters *init)¶

Initialize a timetagger4_init_parameters struct with default values.

You should always use this method first to set up your initialization parameters, then adjust the parameters to your specific needs.

Parameters:

init – Pointer to a timetagger4_init_parameters struct that will be filled.

Returns:

Status codes: TIMETAGGER4_OK or TIMETAGGER4_CRONO_INVALID_ARGUMENTS.

timetagger4_init¶

timetagger4_device timetagger4_init(timetagger4_init_parameters *params, int *error_code, char **error_message)¶

Opens and initializes the TimeTagger4 board with index params.card_index.

Parameters:

params – Pointer to a timetagger4_init_parameters. The struct must have been completely initialized using timetagger4_get_default_init_parameters().
error_code – Pointer to the location where a potential error code will be stored. Equals TIMETAGGER4_OK if no error occurred. Otherwise can be TIMETAGGER4_CRONO_INVALID_ARGUMENTS, TIMETAGGER4_DEVICE_OPEN_FAILED, TIMETAGGER4_HARDWARE_FAILURE, TIMETAGGER4_INVALID_BUFFER_PARAMETERS, TIMETAGGER4_CRONO_INTERNAL_ERROR, or TIMETAGGER4_WRONG_STATE.
error_message – Pointer to a location where a potential error message in plain text will be stored.

Returns:

The TimeTagger4 device corresponding to params.card_index.

timetagger4_close¶

int timetagger4_close(timetagger4_device *device)¶

Close an initialized TimeTagger4 device, releasing all resources.

Parameters:

device – Pointer to the device that shall be closed.

Returns:

Status code: TIMETAGGER4_OK, TIMETAGGER4_INVALID_DEVICE, TIMETAGGER4_WRONG_STATE, or TIMETAGGER4_CRONO_INTERNAL_ERROR.

timetagger4_init_parameters¶

struct timetagger4_init_parameters¶

Struct for the initialization of the TimeTagger4.

This structure must be completely initialized. For this, obtain a default set of initialization parameters first by using timetagger4_get_default_init_parameters(), then adjust parameters for your use case.

int version¶

The version number.

Must be set to TIMETAGGER4_API_VERSION.

int card_index¶

The index in the list of TimeTagger4 boards that should be initialized.

There might be multiple boards in the system that are handled by the driver as reported by timetagger4_count_devices(). This index selects one of them.

Boards are enumerated depending on the PCIe slot. The lower the bus number and the lower the slot number the lower the card index.

int board_id¶

The global index in all cronologic devices.

This 8-bit number is filled into each packet created by the board and is useful if data streams of multiple boards are be merged.

If only TimeTagger4 cards are used this number can be set to the card_index.

If boards of different types that use a compatible data format are used in a system, each board should get a unique ID.

uint64_t buffer_size[8]¶

The minimum size of the DMA buffer.

If set to 0, the default size of 16 MB is used.

For the TimeTagger4, only the first entry is used.

int buffer_type¶

The type of buffer.

Must be one of the following:

TIMETAGGER4_BUFFER_ALLOCATE¶: Use allocated buffer.

TIMETAGGER4_BUFFER_USE_PHYSICAL¶: Use physical buffer (currently not supported).

uint64_t buffer_address¶

The start address of the reserved memory.

The buffers will be allocated with the sizes given above. Make sure that the memory is large enough.

int variant¶: A variant, for reconfiguring the chip for future extension. Currently fixed at 0.

int device_type¶

A constant for the different devices from cronologic.

Initialized by timetagger4_get_default_init_parameters() to CRONO_DEVICE_TIMETAGGER4.

Must be left unchanged.

int dma_read_delay¶

The update delay of the writing pointer after a packet has been send over PCIe.

Given in multiples of 16 ns.

Must be left unchanged.

int use_ext_clock¶: Select external 10 MHz reference.

If set to 1 use external 10 MHz reference.

If set to 0 use internal reference.

int rclk_sel¶

Set THS788 RClk frequency, default is TDC4_RCLK_150M.

Must be one of the following:

TDC4_RCLK_37M5¶: 37.5 MHz

TDC4_RCLK_75M¶: 75 MHz

TDC4_RCLK_150M¶: 150 MHz

timetagger4_device¶

struct timetagger4_device¶

Structure referencing an initialized TimeTagger4 device.

void *timetagger4¶