Skip to content

F
FMC TDC 1ns 5cha - Software
Commit 472ac478 authored by Federico Vaga's avatar Federico Vaga
Browse files
Options

doc: improve documentation and doxgen organization 

Signed-off-by: Federico Vaga's avatarFederico Vaga <federico.vaga@cern.ch>
parent e76e997d
Hide whitespace changes
Inline Side-by-side
Showing with 144 additions and 37 deletions
doc/doxygen-fmctdc-config
View file @ 472ac478
......@@ -12,7 +12,7 @@ CASE_SENSE_NAMES = YES
WARN_NO_PARAMDOC = YES
INPUT = ../lib
INPUT = ../lib readme.md
RECURSIVE = YES
EXCLUDE = $(EXCLUDE_FILES)
......
doc/readme.md 0 → 100644
View file @ 472ac478
Library Overview {#mainpage}
================
This is the **fmc-tdc** library documentation. Here you can find all
the information about the *fmc-tdc* API and the main library behaviour that
you need to be aware of.
If you are reading this from the doxygen documentation, then you can find
the API documentation in the usual Doxygen places. Otherwise, you can get
the API documentation directly from the source code that you can find in
the *lib* directory.
In this document we are going to provides you some clues to understand how
to use the libray API.
Initialization
==============
To be able to use this library the first thing to do is to initialize a library
instance using fmctdc_init(); form this point on you are able to use the
library API. Of course, when you finished to use the library you have to
remove this instance using fmctdc_exit().
By default all TDC channels are disabled. So, in order to start the time-stamps
acquisition you have to enables your channels using fmctdc_channel_enable().
Now you are ready to read your time-stamps. The procedure to read time-stamp is:
-# open a channel with fmctdc_open()
-# read time-stamps as much as you want with fmctdc_read()
-# close the channel with fmctdc_close()
If you fear that the channel buffer is not empyt when you start your acquisition
you can flush it by using fmctdc_flush(). Calling fmctdc_flush() will temporary
disable the acquisition on the given channel.
Time Stamps
===========
The main purpose of this library is to provide *time-stamps* without any
specific policy. All special policies to apply to the time-stamps must be
done on your side.
MODES
-----
The library provides two time-stamp modes that you can configure for
each channel: **base-time** and **difference-time**. The selection of
one or the other mode will change the meaning of the time-stamp that
you will read. To select the time-stamp mode you have to use
the fmctdc_reference_set() function.
The standard mode is the *base-time* mode. When the library is in this mode
for a given channel, the time-stamps coming from this channel will be pure
time-stamps according to the TDC internal base-time.
The *difference-time* mode can be enabled by assigning a channel reference
to a given channel (a.k.a. target). When you assing a channel reference to
a channel the time-stamp produced by will be a time difference between the
pulse on the target channel and the last pulse on the reference channel.
In order to disable the *difference-time* mode, and go back to
the *base-time* mode, you must remove the channel reference.
Bear in mind that the time-stamp mode will affect immediatly the time-stamp
acquisition but **not** the time-stamps already in the buffer.
Buffer
======
The buffer is place where time-stamps are stored. You can configure only the
lenght of the buffer and its operational mode
Modes
-----
You have mainly two buffer modes: **FIFO** and **CIRC** (circular). You can
change the buffer mode for a singel channel using fmctdc_set_buffer_mode().
In *FIFO* mode when the buffer is full all new time-stamps will be dropped,
instead when you use *CIRC* mode old time-stamps will be overwritten by
the new ones.
\ No newline at end of file
lib/fmctdc-lib.h
View file @ 472ac478
......@@ -75,31 +75,40 @@ struct fmctdc_time {
/**
* It compares two time-stamps.
* @param[in] a first time stamp
* @param[in] b second time stamp
* @return like memcmp(2) and strcmp(2)
* @file fmctdc-lib.c
*/
static inline int _fmctdc_tscmp(struct fmctdc_time *a, struct fmctdc_time *b)
{
return a->gseq_id - b->seq_id;
}
/**
* @file fmctdc-lib.c
* @defgroup libutil Utilities
* Set of library utilities
* @{
*/
extern char *fmctdc_strerror(int err);
extern int fmctdc_init(void);
extern void fmctdc_exit(void);
/**@}*/
extern struct fmctdc_board *fmctdc_open(int offset, int dev_id);
extern struct fmctdc_board *fmctdc_open_by_lun(int lun);
extern int fmctdc_close(struct fmctdc_board *);
/**
* @defgroup libboard Board Configuration
* Set of function to configure TDC board and retrieve information
* about the current status
* @{
*/
extern int fmctdc_set_time(struct fmctdc_board *b, struct fmctdc_time *t);
extern int fmctdc_get_time(struct fmctdc_board *b, struct fmctdc_time *t);
extern int fmctdc_set_host_time(struct fmctdc_board *b);
extern int fmctdc_wr_mode(struct fmctdc_board *b, int on);
extern int fmctdc_check_wr_mode(struct fmctdc_board *b);
extern float fmctdc_read_temperature(struct fmctdc_board *b);
/**@}*/
/**
* @defgroup libchan Channel Configuration
* Set of function to configure TDC channels and retrieve information
* about the current status
* @{
*/
extern int fmctdc_channel_status_set(struct fmctdc_board *userb,
unsigned int channel,
enum fmctdc_channel_status status);
......@@ -109,7 +118,6 @@ extern int fmctdc_channel_disable(struct fmctdc_board *userb,
unsigned int channel);
extern int fmctdc_channel_status_get(struct fmctdc_board *userb,
unsigned int channel);
extern int fmctdc_set_termination(struct fmctdc_board *b, unsigned int channel,
int enable);
extern int fmctdc_get_termination(struct fmctdc_board *b, unsigned int channel);
......@@ -123,41 +131,65 @@ extern int fmctdc_get_buffer_len(struct fmctdc_board *userb,
extern int fmctdc_set_buffer_len(struct fmctdc_board *userb,
unsigned int channel,
unsigned int lenght);
extern int fmctdc_reference_set(struct fmctdc_board *userb,
unsigned int ch_target, int ch_reference);
extern int fmctdc_reference_get(struct fmctdc_board *userb,
unsigned int ch_target);
/**
* It removes the time reference from a target channel
* @param[in] userb TDC board instance token
* @param[in] ch_target target channel [1, 5]
* @return 0 on success, otherwise -1 and errno is set appropriately
*/
static inline int fmctdc_reference_clear(struct fmctdc_board *userb,
int ch_target)
{
return fmctdc_reference_set(userb, ch_target, 0);
}
/**@}*/
/**
* @defgroup libacq Time-stamps Acquisition
* Set of functions to read time-stamps from the board
* @{
*/
extern struct fmctdc_board *fmctdc_open(int offset, int dev_id);
extern struct fmctdc_board *fmctdc_open_by_lun(int lun);
extern int fmctdc_close(struct fmctdc_board *);
extern int fmctdc_fread(struct fmctdc_board *b, unsigned int channel,
struct fmctdc_time *t, int n);
extern int fmctdc_fileno_channel(struct fmctdc_board *b, unsigned int channel);
extern int fmctdc_read(struct fmctdc_board *b, unsigned int channel,
struct fmctdc_time *t, int n, int flags);
extern float fmctdc_read_temperature(struct fmctdc_board *b);
extern int fmctdc_wr_mode(struct fmctdc_board *b, int on);
extern int fmctdc_check_wr_mode(struct fmctdc_board *b);
extern void fmctdc_ts_sub(struct fmctdc_time *a, struct fmctdc_time *b);
extern int fmctdc_reference_set(struct fmctdc_board *userb,
unsigned int ch_target, int ch_reference);
extern int fmctdc_reference_get(struct fmctdc_board *userb, unsigned int ch_target);
extern int fmctdc_flush(struct fmctdc_board *userb, unsigned int channel);
/**@}*/
/**
*@file fmctdc-lib-math.c
*/
extern uint64_t fmctdc_ts_approx_ns(struct fmctdc_time *a);
extern uint64_t fmctdc_ts_ps(struct fmctdc_time *a);
extern void fmctdc_ts_sub(struct fmctdc_time *a, struct fmctdc_time *b);
extern void ft_ts_add(struct fmctdc_time *a, struct fmctdc_time *b);
/**
* @defgroup libmath Time-Stamp Math
* Set of mathematical functions on time-stamps
* @{
*/
/**
* It removes the time reference from a target channel
* @param[in] userb TDC board instance token
* @param[in] ch_target target channel [1, 5]
* @return 0 on success, otherwise -1 and errno is set appropriately
* It compares two time-stamps.
* @param[in] a first time stamp
* @param[in] b second time stamp
* @return like memcmp(2) and strcmp(2)
*/
static inline int fmctdc_reference_clear(struct fmctdc_board *userb,
int ch_target)
static inline int _fmctdc_tscmp(struct fmctdc_time *a, struct fmctdc_time *b)
{
return fmctdc_reference_set(userb, ch_target, 0);
/* FIXME integer overflow to be managed */
return a->gseq_id - b->seq_id;
}
extern uint64_t fmctdc_ts_approx_ns(struct fmctdc_time *a);
extern uint64_t fmctdc_ts_ps(struct fmctdc_time *a);
extern void fmctdc_ts_sub(struct fmctdc_time *a, struct fmctdc_time *b);
extern void ft_ts_add(struct fmctdc_time *a, struct fmctdc_time *b);
/**@}*/
#endif /* __FMCTDC_LIB_H__ */
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment