The Library API

Defines

PRItsps: printf format for timestamps with pico-second resolution

PRItspsVAL(_ts): printf value for timestamps with pico-second resolution

PRItswr: printf format for timestamps with White-Rabbit notation

PRItswrVAL(_ts): printf value for timestamp with White-Rabbit notation

__FMCTDC_ERR_MIN

Enums

enum fmctdc_error_numbers

Values:

enumerator FMCTDC_ERR_VMALLOC

enumerator FMCTDC_ERR_UNKNOWN_BUFFER_TYPE

enumerator FMCTDC_ERR_NOT_CONSISTENT_BUFFER_TYPE

enumerator FMCTDC_ERR_VERSION_MISMATCH

enumerator __FMCTDC_ERR_MAX

enum fmctdc_channel

Enumeration for all TDC channels

Values:

enumerator FMCTDC_CH_1

enumerator FMCTDC_CH_2

enumerator FMCTDC_CH_3

enumerator FMCTDC_CH_4

enumerator FMCTDC_CH_5

enumerator FMCTDC_CH_LAST

enumerator FMCTDC_NUM_CHANNELS

enum fmctdc_buffer_mode

Enumeration of all buffer modes

Values:

enumerator FMCTDC_BUFFER_FIFO: FIFO policy: when buffer is full, new time-stamps will be dropped

enumerator FMCTDC_BUFFER_CIRC: circular buffer policy: when the buffer is full, old time-stamps will be overwritten by new ones

enum fmctdc_buffer_type

Enumeration of all buffer types

Values:

enumerator FMCTDC_BUFFER_KMALLOC: kernel allocator: kmalloc

enumerator FMCTDC_BUFFER_VMALLOC: kernel allocator: vmalloc

enum fmctdc_channel_status

Enumeration for all possible status of a channel

Values:

enumerator FMCTDC_STATUS_DISABLE: The cannel is disable

enumerator FMCTDC_STATUS_ENABLE: the channel is enable

enum ft_transfer_mode

Values:

enumerator FT_ACQ_TYPE_FIFO

enumerator FT_ACQ_TYPE_DMA

enum fmctdc_ts_mode

Enumeration for all possible time-stmap mode

Values:

enumerator FMCTDC_TS_MODE_POST: after post-processing

enumerator FMCTDC_TS_MODE_RAW: directly from ACAM chip. This should be used ONLY when debugging low level issues

Functions

const char *fmctdc_strerror(int err)

It returns the error message associated to the given error code

Parameters: err – [in] error code

int fmctdc_init(void)

Init the library. You must call this function before use any other library function.

Returns: 0 on success, otherwise -1 and errno is appropriately set

void fmctdc_exit(void): It releases all the resources used by the library and allocated by fmctdc_init().

int fmctdc_set_time(struct fmctdc_board *b, const struct fmctdc_time *t)

It sets the TDC base-time according to the given time-stamp. Note that, for the time being, it sets only seconds. Note that, you can set the time only when the acquisition is disabled.

Parameters

userb – [in] TDC board instance token
t – [in] time-stamp

Returns

0 on success, otherwise -1 and errno is set

int fmctdc_get_time(struct fmctdc_board *b, struct fmctdc_time *t)

It gets the base-time of a TDC device. Note that, for the time being, it gets only seconds.

Parameters

userb – [in] TDC board instance token
t – [out] time-stamp

Returns

0 on success, otherwise -1 and errno is set

int fmctdc_set_host_time(struct fmctdc_board *b)

It sets the TDC base-time according to the host time

Parameters: userb – [in] TDC board instance token
Returns: 0 on success, otherwise -1 and errno is set appropriately

int fmctdc_wr_mode(struct fmctdc_board *b, int on)

It enables/disables the WhiteRabbit timing system on a TDC device

Parameters

userb – [in] TDC board instance token
on – [in] white-rabbit status to set

Returns

0 on success, otherwise -1 and errno is set appropriately

int fmctdc_check_wr_mode(struct fmctdc_board *b)

It check the current status of the WhiteRabbit timing system on a TDC device

Parameters

userb – [in] TDC board instance token

Returns

0 if it properly works, -1 on error and errno is set appropriately.

ENOLINK if it is not synchronized and
ENODEV if it is not enabled

float fmctdc_read_temperature(struct fmctdc_board *b)

It reads the current temperature of a TDC device

Parameters: userb – [in] TDC board instance token
Returns: temperature

int fmctdc_channel_status_set(struct fmctdc_board *userb, unsigned int channel, enum fmctdc_channel_status status)

The function enables/disables timestamp acquisition for the given channel.

Parameters

userb – [in] TDC board instance token
channel – [in] channel to which we want change status
status – [in] enable status to set

Returns

0 on success, otherwise -1 and errno is set appropriately

int fmctdc_channel_enable(struct fmctdc_board *userb, unsigned int channel)

It enables a given channel. NOTE: it is just a wrapper of fmctdc_channel_status_set()

Parameters

userb – [in] TDC board instance token
channel – [in] channel to which we want change status

Returns

0 on success, otherwise -1 and errno is set appropriately

int fmctdc_channel_disable(struct fmctdc_board *userb, unsigned int channel)

It disable a given channel. NOTE: it is just a wrapper of fmctdc_channel_status_set()

Parameters

userb – [in] TDC board instance token
channel – [in] channel to which we want change status

Returns

0 on success, otherwise -1 and errno is set appropriately

int fmctdc_channel_status_get(struct fmctdc_board *userb, unsigned int channel)

It gets the acquisition status of a TDC channel

Parameters

userb – [in] TDC board instance token
channel – [in] channel to which we want read the status

Returns

the acquisition status (0 disabled, 1 enabled), otherwise -1 and errno is set appropriately

int fmctdc_set_termination(struct fmctdc_board *b, unsigned int channel, int enable)

The function enables/disables the 50 Ohm termination of the given channel. Termination may be changed anytime.

Parameters

userb – [in] TDC board instance token
channel – [in] to use
on – [in] status of the termination to set

Returns

0 on success, otherwise a negative errno code is set appropriately

int fmctdc_get_termination(struct fmctdc_board *b, unsigned int channel)

The function returns current temrmination status: 0 if the given channel is high-impedance and positive if it is 50 Ohm-terminated.

Parameters

userb – [in] TDC board instance token
channel – [in] to use

Returns

termination status, otherwise a negative errno code is set appropriately

int fmctdc_get_buffer_type(struct fmctdc_board *userb)

The function returns current buffer type: 0 for kmallo, 1 for vmalloc.

Parameters: userb – [in] TDC board instance token
Returns: buffer type, otherwise a negative errno code is set appropriately

int fmctdc_set_buffer_type(struct fmctdc_board *userb, enum fmctdc_buffer_type type)

The function sets the buffer type for a device

Parameters

userb – [in] TDC board instance token
type – [in] buffer type to use

Returns

0 on success, otherwise a negative errno code is set appropriately

int fmctdc_get_buffer_mode(struct fmctdc_board *userb, unsigned int channel)

The function returns current buffer mode: 0 for FIFO, 1 for circular buffer.

Parameters

userb – [in] TDC board instance token
channel – [in] to use

Returns

buffer mode, otherwise a negative errno code is set appropriately

int fmctdc_set_buffer_mode(struct fmctdc_board *userb, unsigned int channel, enum fmctdc_buffer_mode mode)

The function sets the buffer mode for a channel

Parameters

userb – [in] TDC board instance token
channel – [in] to use
mode – [in] buffer mode to use

Returns

0 on success, otherwise a negative errno code is set appropriately

int fmctdc_get_buffer_len(struct fmctdc_board *userb, unsigned int channel)

The function returns current driver buffer length (number of timestamps)

Parameters

userb – [in] TDC board instance token
channel – [in] to use

Returns

buffer lenght, otherwise a negative errno code is set appropriately

int fmctdc_set_buffer_len(struct fmctdc_board *userb, unsigned int channel, unsigned int length)

The function set the buffer length

Internally, the buffer allocates memory in chunks of minimun 1KiB. This means, for example, that if you ask for 65 timestamp the buffer will allocate space for 128. This because 64 timestamps fit in 1KiB, to store 65 we need 2KiB (128 timestamps).

NOTE: it works only with the VMALLOC allocator.

Parameters

userb – [in] TDC board instance token
channel – [in] to use
length – [in] maximum number of timestamps to store (min: 64)

Returns

0 on success, otherwise a negative errno code is set appropriately

int fmctdc_set_offset_user(struct fmctdc_board *userb, unsigned int channel, int32_t offset)

It sets the user offset to be applied on incoming timestamps. All the timestamps read from the driver (this means also from this library) will be already corrected using this offset.

Parameters

userb – [in] TDC board instance token
channel – [in] target channel [0, 4]
offset – [in] the number of pico-seconds to be added

Returns

0 on success, otherwise -1 and errno is set appropriately

int fmctdc_get_offset_user(struct fmctdc_board *userb, unsigned int channel, int32_t *offset)

It get the current user offset applied to the incoming timestamps

Parameters

userb – [in] TDC board instance token
channel – [in] target channel [0, 4]
offset – [out] the number of pico-seconds to be added

Returns

0 on success, otherwise -1 and errno is set appropriately

int fmctdc_transfer_mode(struct fmctdc_board *userb, enum ft_transfer_mode *mode)

It gets the current transfer mode

Parameters

userb – [in] TDC board instance token
mode – [out] transfer mode

Returns

0 on success, otherwise -1 and errno is set appropriately

int fmctdc_coalescing_timeout_set(struct fmctdc_board *userb, unsigned int channel, unsigned int timeout_ms)

It sets the coalescing timeout on a given channel

It does not work per-channel for the following acquisition mechanism:

FIFO (it will return the global IRQ coalescing timeout)

Parameters

userb – [in] TDC board instance token
channel – [in] target channel [0, 4]
timeout_ms – [in] ms timeout to trigger IRQ

Returns

0 on success, otherwise -1 and errno is set appropriately

int fmctdc_coalescing_timeout_get(struct fmctdc_board *userb, unsigned int channel, unsigned int *timeout_ms)

It gets the coalescing timeout from a given channel

It does not work per-channel for the following acuqisition mechanism:

FIFO: there is a global configuration for all channels

Parameters

userb – [in] TDC board instance token
channel – [in] target channel [0, 4]
timeout_ms – [out] ms timeout to trigger IRQ

Returns

0 on success, otherwise -1 and errno is set appropriately

int fmctdc_ts_mode_set(struct fmctdc_board *userb, unsigned int channel, enum fmctdc_ts_mode mode)

It sets the timestamp mode

Parameters

userb – [in] TDC board instance token
channel – [in] target channel [0, 4]
mode – [in] time-stamp mode

Returns

0 on success, otherwise -1 and errno is set appropriately

int fmctdc_ts_mode_get(struct fmctdc_board *userb, unsigned int channel, enum fmctdc_ts_mode *mode)

It gets the timestamp mode

Parameters

userb – [in] TDC board instance token
channel – [in] target channel [0, 4]
mode – [out] time-stamp mode

Returns

0 on success, otherwise -1 and errno is set appropriately

struct fmctdc_board *fmctdc_open(int dev_id)

struct fmctdc_board *fmctdc_open_by_lun(int lun)

It opens one specific device by logical unit number (CERN/BE-CO-like). The function uses a symbolic link in /dev that points to the standard device. The link is created by the local installation procedure, and it allows to get the device id according to the LUN. Read also fmctdc_open() documentation.

Parameters: lun – [in] Logical Unit Number
Returns: an instance token, otherwise NULL and errno is appripriately set

int fmctdc_close(struct fmctdc_board*)

It closes a TDC instance opened with fmctdc_open() or fmctdc_open_by_lun()

Parameters: userb – [in] TDC board instance token
Returns: 0 on success, otherwise -1 and errno is set appropriately

int fmctdc_fread(struct fmctdc_board *b, unsigned int channel, struct fmctdc_time *t, int n)

this “fread” behaves like stdio: it reads all the samples. Read fmctdc_read() for more details about the function.

Parameters

userb – [in] TDC board instance token
channel – [in] channel to use
t – [out] array of time-stamps
n – [in] number of elements to save in the array

Returns

number of acquired time-stamps, otherwise -1 and errno is set appropriately

int fmctdc_fileno_channel(struct fmctdc_board *b, unsigned int channel)

It get the file descriptor of a TDC channel. So, for example, you can poll(2) and select(2). Note that, the file descriptor is the file-descriptor of a ZIO control char-device.

Parameters

userb – [in] TDC board instance token
channel – [in] channel to use

Returns

a file descriptor, otherwise -1 and errno is set appropriately

int fmctdc_read(struct fmctdc_board *b, unsigned int channel, struct fmctdc_time *t, int n, int flags)

It reads a given number of time-stamps from the driver. It will wait at most once and return the number of samples that it received from a given input channel.

Timestamps are to the base time.

This “read” behaves like the system call and obeys O_NONBLOCK

Parameters

userb – [in] TDC board instance token
channel – [in] channel to use [0, 4]
t – [out] array of time-stamps
n – [in] number of elements to save in the array
flags – [in] tune the behaviour of the function. O_NONBLOCK - do not block

Returns

number of acquired time-stamps, otherwise -1 and errno is set appropriately.

EINVAL for invalid arguments
EIO for invalid IO transfer
EAGAIN if nothing ready to read in NONBLOCK mode

int fmctdc_flush(struct fmctdc_board *userb, unsigned int channel)

It removes all samples from the channel buffer. In order to doing this, the function temporary disable any active acquisition, only when the flush is completed the acquisition will be re-enabled

Parameters

userb – [in] TDC board instance token
channel – [in] target channel [0, 4]

Returns

0 on success, otherwise -1 and errno is set appropriately

int fmctdc_stats_recv_get(struct fmctdc_board *userb, unsigned int channel, uint32_t *val)

It gets the number of received pulses (on hardware)

Parameters

userb – [in] TDC board instance token
channel – [in] target channel [0, 4]
val – [out] number of received pulses

Returns

0 on success, otherwise -1 and errno is set appropriately

int fmctdc_stats_trans_get(struct fmctdc_board *userb, unsigned int channel, uint32_t *val)

It gets the number of transferred timestamps

Parameters

userb – [in] TDC board instance token
channel – [in] target channel [0, 4]
val – [out] number of transferred timestamps

Returns

0 on success, otherwise -1 and errno is set appropriately

uint64_t fmctdc_ts_approx_ns(struct fmctdc_time *a)

Set of mathematical functions on time-stamps

It provides a nano-second approximation of the timestamp.

Parameters: a – [in] timestamp
Returns: it returns the time stamp in nano-seconds

uint64_t fmctdc_ts_ps(struct fmctdc_time *a)

It provides a pico-seconds representation of the time stamp. Bear in mind that it may overflow. If you thing that it may happen, check the timestamp

Parameters: a – [in] timestamp
Returns: it returns the time stamp in pico-seconds

void fmctdc_ts_norm(struct fmctdc_time *a)

It normalizes the timestamp

Parameters: a – [inout] timestamp

int fmctdc_ts_sub(struct fmctdc_time *r, const struct fmctdc_time *a, const struct fmctdc_time *b)

It perform the subtraction: r = a - b

Parameters

r – [out] result
a – [in] normalized timestamp
b – [in] normalized timestamp

Returns

1 if the difference is negative, otherwise 0

void fmctdc_ts_add(struct fmctdc_time *r, const struct fmctdc_time *a, const struct fmctdc_time *b)

It perform an addiction: r = a + b

Parameters

r – [out] result
a – [in] normalized timestamp
b – [in] normalized timestamp

int _fmctdc_tscmp(struct fmctdc_time *a, struct fmctdc_time *b)

Variables

const char *const libfmctdc_version_s: libfmctdc version string

const char *const libfmctdc_zio_version_s: zio version string used during compilation of libfmctdc

struct fmctdc_time

#include <fmctdc-lib.h>

FMC-TDC time-stamp descriptor

Public Members

uint64_t seconds: TAI seconds. Note this is not an UTC time; the counter does not support leap seconds. The internal counter is also limited to 32 bits (2038-error-prone).

uint32_t coarse: number of ticks of 8ns since the beginning of the last second

uint32_t frac: fractional part of an 8 ns tick, rescaled to (0..4095) range - i.e. 0 = 0 ns, and 4095 = 7.999 ns.

uint32_t seq_id: channel sequence number

uint32_t debug: debug stuff, driver/firmware-specific