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
-
enumerator FMCTDC_ERR_VMALLOC
-
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
-
enumerator FMCTDC_CH_1
-
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
-
enumerator FMCTDC_BUFFER_FIFO
-
enum fmctdc_buffer_type
Enumeration of all buffer types
Values:
-
enumerator FMCTDC_BUFFER_KMALLOC
kernel allocator: kmalloc
-
enumerator FMCTDC_BUFFER_VMALLOC
kernel allocator: vmalloc
-
enumerator FMCTDC_BUFFER_KMALLOC
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
-
uint64_t seconds