Initialization¶

To initialize an xTDC4:

Get a default set of initialization parameters using xtdc4_get_default_init_parameters().
Change parameters of xtdc4_init_parameters according to your specific requirements.
Initialize an xTDC4 device using xtdc4_init().
Release all resources using xtdc4_close().

The following example shows a basic setup of an xTDC4 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
xtdc4_init_parameters params;
status = xtdc4_get_default_init_parameters(&params);
if (status != XTDC4_OK) { /* handle error */ }

// initialize a device
const char* err_message;
xtdc4_device* device = xtdc4_init(&params, &status, &err_message);
if (status != XTDC4_OK) { /* handle error */ }

// use device

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

xtdc4_get_default_init_parameters¶

int xtdc4_get_default_init_parameters(xtdc4_init_parameters *init)¶

Initialize an xtdc4_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 xtdc4_init_parameters struct that will be filled.

Returns:

Status codes: XTDC4_OK or XTDC4_CRONO_INVALID_ARGUMENTS.

xtdc4_init¶

xtdc4_device xtdc4_init(xtdc4_init_parameters *params, int *error_code, char **error_message)¶

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

Parameters:

params – Pointer to a xtdc4_init_parameters. The struct must have been completely initialized using xtdc4_get_default_init_parameters().
error_code – Pointer to the location where a potential error code will be stored. Equals XTDC4_OK if no error occurred. Otherwise can be XTDC4_CRONO_INVALID_ARGUMENTS, XTDC4_DEVICE_OPEN_FAILED, XTDC4_HARDWARE_FAILURE, XTDC4_INVALID_BUFFER_PARAMETERS, XTDC4_CRONO_INTERNAL_ERROR, or XTDC4_WRONG_STATE.
error_message – Pointer to a location where a potential error message in plain text will be stored.

Returns:

The xTDC4 device corresponding to params.card_index.

xtdc4_close¶

int xtdc4_close(xtdc4_device *device)¶

Close an initialized xTDC4 device, releasing all resources.

Parameters:

device – Pointer to the device that shall be closed.

Returns:

Status code: XTDC4_OK, XTDC4_INVALID_DEVICE, XTDC4_WRONG_STATE, or XTDC4_CRONO_INTERNAL_ERROR.

xtdc4_init_parameters¶

struct xtdc4_init_parameters¶

Struct for the initialization of the xTDC4.

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

int version¶

The version number.

Must be set to XTDC4_API_VERSION.

int card_index¶

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

There might be multiple boards in the system that are handled by the driver as reported by xtdc4_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 xTDC4 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 xTDC4, only the first entry is used.

int buffer_type¶

The type of buffer.

Must be one of the following:

XTDC4_BUFFER_ALLOCATE¶: Use allocated buffer.

XTDC4_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 xtdc4_get_default_init_parameters() to CRONO_DEVICE_XTDC4.

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

xtdc4_device¶

struct xtdc4_device¶

Structure referencing an initialized xTDC4 device.

void *xtdc4¶