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:
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
, orXTDC4_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
, orXTDC4_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
, orXTDC4_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
, orXTDC4_INVALID_DEVICE
.
-
CRONO_PCIE_CORRECTABLE_FLAG¶
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.
-
int pcie_link_width¶
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.
-
int size¶
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
.
-
int size¶
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
)
-
int size¶
crono_pcie_info¶
-
struct crono_pcie_info¶
-
uint32_t pwr_mgmt¶
Organizes power supply of the PCIe lanes.
-
uint32_t link_width¶
Number of PCIe lanes that the card uses.
-
uint32_t max_payload¶
Maximum size in bytes for one PCIe transaction.
-
uint32_t link_speed¶
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
.
-
CRONO_PCIE_RX_ERROR¶
-
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
.
-
CRONO_PCIE_UNC_DATA_LINK_PROTOCOL_ERROR¶
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
.
-
CRONO_PCIE_UNC_UNDEFINED¶
-
uint32_t pwr_mgmt¶