Status Information

The driver provides functions to retrieve detailed information on the board type, its configuration, settings, and state. The information is split according to its scope and the computational requirements to query the information from the board.

xtdc4_get_device_type

int xtdc4_get_device_type(xtdc4_device *device)

Get the type of the TimeTagger device.

Parameters:
  • device – Pointer to an xTDC4 device.

Returns:

CRONO_DEVICE_XTDC4

xtdc4_get_last_error_message

const char *xtdc4_get_last_error_message(xtdc4_device *device)

Get the last error message.

Parameters:
  • device – Pointer to an xTDC4 device.

Returns:

The error message.

xtdc4_get_fast_info

int xtdc4_get_fast_info(xtdc4_device *device, xtdc4_fast_info *info)

Obtain dynamic information about a xTDC4 device that can be obtained within a few microseconds.

Parameters:
  • device – Pointer to an xTDC4 device.

  • info – Pointer to a xtdc4_fast_info struct that will be filled.

Returns:

Status codes: XTDC4_OK, XTDC4_INVALID_DEVICE, XTDC4_CRONO_INVALID_ARGUMENTS, or -1.

xtdc4_get_param_info

int xtdc4_get_param_info(xtdc4_device *device, xtdc4_fast_info *info)

Obtain information about configuration changes.

Gets information that changes indirectly due to configuration changes.

Parameters:
  • device – Pointer to an xTDC4 device.

  • info – Pointer to a xtdc4_param_info struct that will be filled.

Returns:

Status codes: XTDC4_OK, XTDC4_CRONO_INVALID_ARGUMENTS, or XTDC4_WRONG_STATE,

xtdc4_get_static_info

int xtdc4_get_static_info(xtdc4_device *device, xtdc4_static_info *info)

Obtain information about an xTDC4 device that does not change during runtime.

Parameters:
  • device – Pointer to an xTDC4 device.

  • info – Pointer to an xtdc4_static_info struct that will be filled.

Returns:

Status codes: XTDC4_OK, XTDC4_INVALID_DEVICE, or XTDC4_CRONO_INVALID_ARGUMENTS.

xtdc4_get_pcie_info

int xtdc4_get_pcie_info(xtdc4_device *device, crono_pcie_info *pcie_info)

Obtain PCIe information.

Parameters:
  • device – Pointer to an xTDC4 device.

  • pcie_info – Pointer to a crono_pcie_info struct that will be filled.

Returns:

Status codes: XTDC4_OK, XTDC4_INVALID_DEVICE, or XTDC4_HARDWARE_FAILURE.

xtdc4_clear_pcie_errors

int xtdc4_clear_pcie_errors(xtdc4_device *device, int flags)

Clear PCIe errors.

Only useful for PCIe debugging.

Valid flags are:

CRONO_PCIE_CORRECTABLE_FLAG

Clear correctable PCIe errors.

CRONO_PCIE_UNCORRECTABLE_FLAG

Clear uncorrectable PCIe errors.

Parameters:
  • device – Pointer to an xTDC4 device.

  • flag – Flag which errors to clear.

Returns:

Status codes: XTDC4_OK, or XTDC4_INVALID_DEVICE.

xtdc4_fast_info

struct xtdc4_fast_info
int size

The number of bytes this struct occupies.

int version

Version number of this struct. It is increased when the definition of the struct changes.

int tdc_rpm

Speed of the TDC fan in rounds per minute.

0 if no fan is present.

int fpga_rpm

Speed of the FPGA fan in rounds per minute.

0 if no fan is present.

int alerts

Alert bits from the temperature sensor and the system monitor.

Bit 0 is set, if the TDC temperature exceeds 140°C. If set, the TDC shut down and the device needs to be reinitialized.

int pcie_pwr_mgmt

Fixed at 0.

Number of PCIe lanes the xTDC4 device uses.

Should always be 10.

int pcie_max_payload

Maximum size in bytes for one PCIe transaction.

Depends on the system configuration.

xtdc4_param_info

struct xtdc4_param_info

This structure is provided by xtdc4_get_param_info().

int size

The number of bytes this struct occupies.

int version

Version number of this struct. It is increased when the definition of the struct changes.

double binsize

Bin size in ps of the measured TDC data.

For the xTDC4, it is 13.02083 ps.

int board_id

ID of the xTDC4 device.

Used to identify itself in the output data stream.

Is between 0 and 255.

int channels

Number of TDC channels of the board.

Fixed at 4.

int channel_mask

Bit assignment of each enabled input channel.

Bit 0 ≤ n ≤ 3 is set if channel n is enabled.

int64_t total_buffer

The total amount of DMA buffer in bytes.

double packet_binsize

For the xTDC4, it is 5000 ps / 3 ≈ 1666.6 ps.

crono_packet.timestamp is given in multiples of this value.

double quantisation

Quantisation, that is, measurement resolution of the xTDC4, in ps.

For the xTDC4, it is equal to xtdc4_param_info.binsize.

xtdc4_static_info

struct xtdc4_static_info

Structure that contains static information.

This structure contains information about the board that does not change during run time. It is provided by the function xtdc4_get_static_info().

int size

The number of bytes occupied by the structure.

int version

The version number.

A version number that is increased when the definition of the structure is changed. The increment can be larger than one to match driver version numbers or similar. Set to 0 for all versions up to first release.

int board_id

ID of the xTDC4 board.

This value is passed to the constructor. It is reflected in the output data.

int driver_revision

Encoded version number.

The lower three bytes contain a triple level hierarchy of version numbers. E.g. 0x010103 codes version 1.1.3.

The versioning follows the Semantic Versioning 2.0.0 specifications.

int driver_build_revision

SVN revision of the driver build.

int firmware_revision

Revision number of the FPGA configuration.

int board_revision

Board revision number.

The board revision number can be read from a register. It is a four-bit number that changes when the schematic of the board is changed. This should match the revision number printed on the board.

int board_configuration

Describes the schematic configuration of the board.

The same board schematic can be populated in multiple variants. This is a eight bit code that can be read from a register.

int subversion_revision

Subversion revision ID of the FPGA configuration.

int chip_id

16 bit factory ID of the TDC chip.

int board_serial

Serial number of the xTDC4.

With year and running number in 8.24 format (8 bits are used to encode the year, 24 bits are used to encode the serial number). The number is identical to the one printed on the silvery sticker on the board.

unsigned int flash_serial_low

Low 32 bits of the 64-bit manufacturer serial number of the flash chip.

unsigned int flash_serial_high

High 32 bits of the 64-bit manufacturer serial number of the flash chip.

crono_bool_t flash_valid

This value is not applicable for the xTDC4.

char calibration_date

Calibration date.

DIN EN ISO 8601 string YYYY-MM-DD HH:DD describing the time when the card was calibrated.

char bitstream_date

Bitstream creation date.

DIN EN ISO 8601 string YYYY-MM-DD HH:DD:SS describing the time when the bitstream was created.

double delay_bin_size

This value is not applicable for the xTDC4.

double auto_trigger_ref_clock

Auto trigger clock frequency in Hz.

Used for calculating the frequency of the auto trigger (see Auto-Triggering Function Generator and xtdc4_configuration.auto_trigger_period).

uint32_t rollover_period

The number of bins in a rollover period.

The rollover period is T = 2rollover_period.

If a rollover occurred, T bins have to be added to the timestamp of the hit (see crono_packet.data for more information, in particular, XTDC4_HIT_FLAG_TIME_OVERFLOW)

crono_pcie_info

struct crono_pcie_info
uint32_t pwr_mgmt

Organizes power supply of the PCIe lanes.

Number of PCIe lanes that the card uses.

uint32_t max_payload

Maximum size in bytes for one PCIe transaction.

Data rate of the PCIe card.

uint32_t error_status_supported

Different from 0 if the PCIe error status is supported for this device.

uint32_t correctable_error_status

Correctable error status flags.

Read directly from the PCIe config register.

Useful for debugging PCIe problems.

One of the following:

CRONO_PCIE_RX_ERROR

Equals 1 << 0.

CRONO_PCIE_BAD_TLP

Equals 1 << 6.

CRONO_PCIE_BAD_DLLP

Equals 1 << 7.

CRONO_PCIE_REPLAY_NUM_ROLLOVER

Equals 1 << 8.

CRONO_PCIE_REPLAY_TIMER_TIMEOUT

Equals 1 << 12.

CRONO_PCIE_ADVISORY_NON_FATAL

Equals 1 << 13.

CRONO_PCIE_CORRECTED_INTERNAL_ERROR

Equals 1 << 14.

CRONO_PCIE_HEADER_LOG_OVERFLOW

Equals 1 << 15.

uint32_t uncorrectable_error_status

Uncorrectable error status flags.

Read directly from the PCIe config register.

Useful for debugging PCIe problems.

One of the following:

CRONO_PCIE_UNC_UNDEFINED

Equals 1 << 0.

Equals 1 << 4.

CRONO_PCIE_UNC_SURPRISE_DOWN_ERROR

Equals 1 << 5.

CRONO_PCIE_UNC_POISONED_TLP

Equals 1 << 12.

CRONO_PCIE_UNC_FLOW_CONTROL_PROTOCOL_ERROR

Equals 1 << 13.

CRONO_PCIE_UNC_COMPLETION_TIMEOUT

Equals 1 << 14.

CRONO_PCIE_UNC_COMPLETER_ABORT

Equals 1 << 15.

CRONO_PCIE_UNC_UNEXPECTED_COMPLETION

Equals 1 << 16.

CRONO_PCIE_UNC_RECEIVER_OVERFLOW_ERROR

Equals 1 << 17.

CRONO_PCIE_UNC_MALFORMED_TLP

Equals 1 << 18.

CRONO_PCIE_UNC_ECRC_ERROR

Equals 1 << 19.

CRONO_PCIE_UNC_UNSUPPORED_REQUEST_ERROR

Equals 1 << 20.