Skip to content

L
LHC Instability Trigger Distribution LIST
Commit 79361d89 authored by Federico Vaga's avatar Federico Vaga
Browse files
Options

wrtd:doc: improve library API documentation 

Signed-off-by: Federico Vaga's avatarFederico Vaga <federico.vaga@cern.ch>


NOTE
This commit has been created by `git subtree` on the Mock Turtle repository
on tag mock-turtle-2.0

This commit will not compile
parent cd9cfcb2
Hide whitespace changes
Inline Side-by-side
Showing with 174 additions and 57 deletions
lib/libwrtd-input.c
View file @ 79361d89
......@@ -558,6 +558,8 @@ int wrtd_in_has_trigger(struct wrtd_node *dev, unsigned int input,
* @param[in] input index (0-based) of input channel
* @param[out] dead_time_ps dead time in pico-seconds
* @return 0 on success, -1 on error and errno is set appropriately
*
* @todo to be implemented
*/
int wrtd_in_dead_time_get(struct wrtd_node *dev, unsigned int input,
uint64_t *dead_time_ps)
......@@ -573,6 +575,8 @@ int wrtd_in_dead_time_get(struct wrtd_node *dev, unsigned int input,
* @param[in] input index (0-based) of input channel
* @param[out] delay_ps delay in pico-seconds
* @return 0 on success, -1 on error and errno is set appropriately
*
* @todo to be implemented
*/
int wrtd_in_delay_get(struct wrtd_node *dev, unsigned int input,
uint64_t *delay_ps)
......
lib/libwrtd-logging.c
View file @ 79361d89
......@@ -42,10 +42,9 @@ const char *wrtd_strlogging(enum wrtd_log_level lvl)
/**
* It opens the logging interface for device a given divice. The default
* It opens the logging interface for a given divice. The default
* logging level will be applied to all device channels. You can change it
* later using wrtd_log_level_set()
* @todo reduce code duplication wrtd_out_log_open()
* @param[in] dev device token
* @param[in] lvl default logging level
* @param[in] input channel number [-1, 4]. [-1] for all channels, [0,4] for a
......@@ -104,8 +103,8 @@ static struct wrnc_hmq *wrtd_log_open(struct wrtd_node *dev,
/**
* It reads one or more log entry from a given hmq_log. The user of this function
* must check that the hmq_log used correspond to a logging interface
* It reads one or more log entry from a given hmq_log. The user of this
* function must check that the hmq_log used correspond to a logging interface
* @param[in] hmq_log logging HMQ.
* @param[out] log log message
* @param[in] count number of messages to read
......@@ -204,7 +203,7 @@ static int wrtd_log_level_set(struct wrtd_node *dev, unsigned int channel,
/**
* It opens the logging interface for device a given divice. The default
* It opens the logging interface for a given divice. The default
* logging level will be applied to all device channels. You can change it
* later using wrtd_out_log_level_set()
* @param[in] dev device token
......@@ -222,6 +221,7 @@ struct wrnc_hmq *wrtd_out_log_open(struct wrtd_node *dev,
/**
* It sets the logging level for an output channel
* @param[in] dev device token
* @param[in] output index (0-based) of output channel
* @param[in] log_level log level to apply to the logging messages
......@@ -289,7 +289,7 @@ struct wrnc_hmq *wrtd_in_log_open(struct wrtd_node *dev,
/**
* Set the log level of a given input channel
* It sets the logging level for an input channel
* @param[in] dev device token
* @param[in] input index (0-based) of input channel
* @param[in] log_level log level to apply to the logging messages
......
lib/libwrtd.h
View file @ 79361d89
......@@ -7,6 +7,7 @@
#ifndef __WRTD_LIB_H__
#define __WRTD_LIB_H__
/** @file libwrtd.h */
#ifdef __cplusplus
extern "C" {
......@@ -22,6 +23,7 @@ struct wrtd_node;
#define WRTD_DEFAULT_TIMEOUT 1000
/**
* @enum wrtd_error_list
* White Rabbit Trigger Distribution errors
*/
enum wrtd_error_list {
......@@ -43,72 +45,103 @@ enum wrtd_error_list {
__EWRTD_MAX_ERROR_NUMBER,
};
/**
* @enum wrtd_core
* Core indexes according to their main purpose
*/
enum wrtd_core {
WRTD_CORE_IN = 0,
WRTD_CORE_OUT = 1,
WRTD_CORE_IN = 0, /**< Input core that manages incoming pulses */
WRTD_CORE_OUT = 1, /**< Output core that manages pulses generation */
};
/**
* Trigger token
*/
struct wrtd_trigger_handle {
uint32_t ptr_cond;
uint32_t ptr_trig;
int channel;
uint32_t ptr_cond;
uint32_t ptr_trig;
int channel;
};
/**
* Status description for an input channel
*/
struct wrtd_input_state {
int input;
int input; /**< Input channel index */
uint32_t flags; ///> enum list_io_flags
uint32_t log_level; ///> enum list_log_level
enum wrtd_trigger_mode mode;
uint32_t flags; /**< enum list_io_flags */
uint32_t log_level; /**< enum list_log_level */
enum wrtd_trigger_mode mode; /**< Trigger mode in use */
uint32_t tagged_pulses;
uint32_t sent_triggers;
uint32_t sent_packets;
uint32_t tagged_pulses; /**< Number of incoming pulses detected */
uint32_t sent_triggers; /**< Number of triggers sent over the
white-rabbit network */
uint32_t sent_packets; /**< Number of packets sent over the
white-rabbit network */
struct wrtd_trigger_entry last_sent;
struct wrtd_trig_id assigned_id;
struct wr_timestamp dead_time;
struct wr_timestamp delay;
struct wr_timestamp last_tagged_pulse;
struct wr_timestamp tdc_timebase_offset;
struct wrtd_trigger_entry last_sent; /**< Description of the last
trigger sent */
struct wrtd_trig_id assigned_id; /**< trigger assigned to this channel */
struct wr_timestamp dead_time; /**< Configured dead time */
struct wr_timestamp delay; /**< Time delay assined */
struct wr_timestamp last_tagged_pulse; /** Time stamp of the last
detected pulse*/
struct wr_timestamp tdc_timebase_offset; /**< TDC time base offset */
};
/**
* Status description for a trigger on output
*/
struct wrtd_output_trigger_state {
int is_conditional;
int enabled;
struct wrtd_trig_id trigger;
struct wrtd_trig_id condition;
struct wr_timestamp delay_trig;
struct wr_timestamp delay_cond;
struct wrtd_trigger_handle handle;
int latency_worst_us;
int latency_average_us;
uint32_t executed_pulses;
uint32_t missed_pulses;
int is_conditional; /**< tell if the trigger is under condition or not */
int enabled; /**< tell if the trigger is enable, so it may be
generater as output */
struct wrtd_trig_id trigger; /**< Trigger identifier */
struct wrtd_trig_id condition; /**< Trigger identifier for the trigger
condition */
struct wr_timestamp delay_trig; /**< Configured trigger delay */
struct wr_timestamp delay_cond; /**< Configured trigger condition delay */
struct wrtd_trigger_handle handle;
int latency_worst_us; /**< Worst latency in micro-seconds */
int latency_average_us; /**< Average latency in micro-seconds */
uint32_t executed_pulses; /**< Number of executed pulses */
uint32_t missed_pulses; /**< Number of missed pulses */
};
/**
* Status description for an output channel
*/
struct wrtd_output_state {
int output;
int output; /**< Output channel index */
uint32_t executed_pulses;
uint32_t missed_pulses_late;
uint32_t missed_pulses_deadtime;
uint32_t missed_pulses_overflow;
uint32_t missed_pulses_no_timing;
uint32_t executed_pulses; /**< Number of generated pulses */
uint32_t missed_pulses_late; /**< Number of missed pulses due to: */
uint32_t missed_pulses_deadtime; /**< Number of missed pulses due to: */
uint32_t missed_pulses_overflow; /**< Number of missed pulses due to: */
uint32_t missed_pulses_no_timing; /**< Number of missed pulses due to: */
struct wrtd_trigger_entry last_executed;
struct wrtd_trigger_entry last_received;
struct wrtd_trigger_entry last_enqueued;
struct wrtd_trigger_entry last_lost;
struct wrtd_trigger_entry last_executed; /**< Trigger description of the
last generated trigger */
struct wrtd_trigger_entry last_received; /**< Trigger description of the
last received trigger from
the white-rabbit network */
struct wrtd_trigger_entry last_enqueued; /**< Trigger description of
the last enqueued trigger
in the execution queue */
struct wrtd_trigger_entry last_lost; /**< Trigger description of the
last lost trigger */
uint32_t flags; ///> enum list_io_flags
uint32_t log_level; ///> enum list_log_level
enum wrtd_trigger_mode mode;
struct wr_timestamp dead_time;
struct wr_timestamp pulse_width;
uint32_t received_messages;
uint32_t received_loopback;
uint32_t flags; /**< enum list_io_flags */
uint32_t log_level; /**< enum list_log_level */
enum wrtd_trigger_mode mode; /**< Trigger mode in use */
struct wr_timestamp dead_time; /**< Configured dead time */
struct wr_timestamp pulse_width; /**< Pulse width */
uint32_t received_messages; /**< Number of received packets from
the network */
uint32_t received_loopback;
};
/**
......@@ -208,8 +241,6 @@ extern int wrtd_in_is_armed(struct wrtd_node *dev, unsigned int input,
extern int wrtd_in_has_trigger(struct wrtd_node *dev, unsigned int input,
unsigned int *assigned);
extern int wrtd_in_ping(struct wrtd_node *dev);
/* TODO implements the following prototypes */
extern int wrtd_in_dead_time_get(struct wrtd_node *dev, unsigned int input,
uint64_t *dead_time_ps);
extern int wrtd_in_delay_get(struct wrtd_node *dev, unsigned int input,
......@@ -260,8 +291,6 @@ extern int wrtd_out_ping(struct wrtd_node *dev);
extern int wrtd_out_trigger_mode_set(struct wrtd_node *dev,
unsigned int output,
enum wrtd_trigger_mode mode);
/* TODO implements the following prototypes */
extern int wrtd_out_trig_condition_delay_set(struct wrtd_node *dev,
struct wrtd_trigger_handle *handle,
uint64_t delay_ps);
......
lib/readme.md 0 → 100644
View file @ 79361d89
Library Overview {#mainpage}
================
This is the **WRTD** library documentation. Here you can find all
the information about the *White-Rabbit Trigger-Distribution* API and the main
library behavior 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 library API.
This library is completely base on the *White-Rabbit Node-Core* library.
It uses all its features to establish the communication between the
Trigger Distribution Real Time applications. This library hides the knowledge
about the conventions (protocol) used between the Host and the Real Time
applications and it exposes a simple API for the interaction.
While reading any documentation we suggest you to read the dictionary to avoid
misinterpretation.
Overview
========
The White-Rabbit Trigger-Distribution is a system that allow its users to detect
a trigger (pulse), propagate it over the White-Rabbit network and reproduce it
on a remote machine. This library is in charge to ease the configuration of this
system. The system is based on the White-Rabbit Node-Core. There are two cores
running separately two Real Time applications: one to manage the input,
one to manage the output.
+--------------Trigger-Distribution-System-------------+
| RealTime App - - - - - - - - - RealTime App |
-\ | +-------+ ( ) +--------+ | /-
|--------|->| INPUT |--->( WhiteRabbit Network )--->| OUTPUT |--|------->|
-/ PULSE | +-------+ ( ) +--------+ | PULSE \-
| - - - - - - - - - |
+------------------------------------------------------+
Initialization
==============
To be able to use this library the first thing to do is to initialize a library
instance using wrtd_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 wrtd_exit().
At the beginning, all communication channels are close, so before start to
communicate with the Real Time application you have to open your communication
channel. Then, close it when you have done.
Logging
=======
The WRTD Real Time applications are able to provide some logging information
about the things happening on the FPGA. This interface is read only, so
you can only read logging messages. There are only two configuration parameters:
one for the *logging level*; the other one to set the exclusivity access to the
logging interface. When the logging interface is shared, then also other users
are allowed to get the same messages.
Input
=====
The *input* Real Time application and the associated part of library manages
the detection of the incoming pulse and their correct propagation over the
white-rabbit network as trigger event.
The library allows the user to fully configure the input parameter and to get
the current status of Real Time application but also to get information about
the triggers associated to the input channels. Go directly to the API for the
list of parameters that you can set.
Output
======
The *input* Real Time application and the associated part of library manages
the pluse generation and their correct reception from the white-rabbit
network as trigger event.
The library allows the user to fully configure the output parameter and to get
the current status of Real Time application but also to get information about
the trigger associated to the output channesl. Go directly to the API for the
list of parameters that you can set.
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