Skip to content

M
Mock Turtle
Commit 73f35758 authored by Federico Vaga's avatar Federico Vaga
Browse files
Options

doc: improve library API documentation 

Provide an overview of the library behaviour (readme.md) and improve
some doxygen details
Signed-off-by: Federico Vaga's avatarFederico Vaga <federico.vaga@cern.ch>
parent 51041e2f
Hide whitespace changes
Inline Side-by-side
Showing with 96 additions and 9 deletions
doc/doxygen-wrnc-config
View file @ 73f35758
......@@ -12,7 +12,7 @@ CASE_SENSE_NAMES = YES
WARN_NO_PARAMDOC = YES
INPUT = ../lib
INPUT = ../lib ../kernel/wrnc-user.h
RECURSIVE = YES
EXCLUDE = $(EXCLUDE_FILES)
......
kernel/wrnc-user.h
View file @ 73f35758
......@@ -5,6 +5,7 @@
*/
#ifndef __WRNC_USER_H__
#define __WRNC_USER_H__
/** @file wrnc-user.h */
#define WRNC_MAX_CARRIER 20 /**< Maximum number of WRNC components on a
single computer*/
......@@ -14,6 +15,11 @@
#define WRNC_MAX_PAYLOAD_SIZE 128
/**
* @enum wrnc_smem_modifier
* Shared memory operation modifier. This is a list of operation modifier
* that you can use to access the shared memory.
*/
enum wrnc_smem_modifier {
WRNC_SMEM_DIRECT = 0, /**< direct read/write of the memory */
WRNC_SMEM_OR, /**< on write, atomic OR with memory content */
......@@ -24,11 +30,12 @@ enum wrnc_smem_modifier {
};
/**
* Messages directions
* @enum wrnc_msg_direction
* Message direction on the Host Message Queue
*/
enum wrnc_msg_direction {
WRNC_MSG_DIR_SEND = 0,
WRNC_MSG_DIR_RECEIVE = 1
WRNC_MSG_DIR_SEND = 0, /**< from Host to RealTime Application */
WRNC_MSG_DIR_RECEIVE = 1, /**< from RealTime application to Host */
};
/**
......@@ -36,10 +43,12 @@ enum wrnc_msg_direction {
*/
struct wrnc_msg {
uint32_t datalen; /**< payload length*/
uint32_t data[WRNC_MAX_PAYLOAD_SIZE]; /**< payload */
uint32_t data[WRNC_MAX_PAYLOAD_SIZE]; /**< payload, free content
(no official protocol) */
uint32_t max_size; /**< maximum message size for chosen slot */
uint32_t offset; /**< serialization/deserialization offset */
enum wrnc_msg_direction direction; /**< serialization direction (used by wrnc_msg_x functions) */
enum wrnc_msg_direction direction; /**< serialization direction
(used by wrnc_msg_x functions) */
int error; /** serialization error status */
};
......@@ -55,6 +64,7 @@ struct wrnc_msg_sync {
};
/**
* @enum wrnc_msg_filter_operation_type
* List of available filter's operations
*/
enum wrnc_msg_filter_operation_type {
......@@ -68,8 +78,7 @@ enum wrnc_msg_filter_operation_type {
* It describe a filter to apply to messages
*/
struct wrnc_msg_filter {
uint32_t operation; /**< kind of operation
to perform */
uint32_t operation; /**< kind of operation to perform */
uint32_t word_offset; /**< offset of the word to check */
uint32_t mask; /**< mask to apply before the operation */
uint32_t value; /**< second operand of the operation */
......@@ -88,6 +97,7 @@ struct wrnc_smem_io {
};
/**
* @enum wrnc_ioctl_commands
* Available ioctl() messages
*/
enum wrnc_ioctl_commands {
......
lib/libwrnc.c
View file @ 73f35758
......@@ -1036,6 +1036,7 @@ void wrnc_debug_close(struct wrnc_dbg *dbg)
}
#define N_RETRY 100
/**
* It retrieves a message from the debug channel. It fills the buffer with a
* NULL terminated string.
......@@ -1049,7 +1050,6 @@ void wrnc_debug_close(struct wrnc_dbg *dbg)
* @return number of byte read on success, -1 otherwise and errno is set
* appropriately
*/
#define N_RETRY 100
int wrnc_debug_message_get(struct wrnc_dbg *dbg, char *buf, size_t count)
{
int n = 0, real_count = 0, retry = N_RETRY;
......
lib/libwrnc.h
View file @ 73f35758
......@@ -7,6 +7,7 @@
#ifndef __LIB_WRNC_H__
#define __LIB_WRNC_H__
/** @file libwrnc.h */
#ifdef __cplusplus
extern "C" {
......
lib/readme.md 0 → 100644
View file @ 73f35758
Library Overview {#mainpage}
================
This is the **WRNC** library documentation. Here you can find all
the information about the *White-Rabbit Node-Core* 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.
Initialization
==============
To be able to use this library the first thing to do is to initialize a library
instance using wrnc_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 wrnc_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.
Core Management
===============
The main actions that you can take on a *core* are the following:
- **Program**. When you load the FPGA bitstream the core's memory is empty.
By programming the core memory you overwrite any previous application.
- **enable** and **disable**. When the core is disabled its reset line is
asserted so it is not operative.
- **start** and **stop**. It starts or stops the Real-Time application
execution, so when you stop the core it will stop to run the application.
As soon as you start the execution again, the core start to execute the
application from the previous point.
Host Message Queue
==================
The main communication channel between the Host and the Real Time applications
running on the FPGA cores is the **Host Message Queue**. The HMQ allow the
Host and the Real Time application to exchange messages. For the time being
there is not a well defined protocol for the messages sent over the HMQ but as
a convention we are using the first 8 bytes as an header containing a sequence
number and a message type identifier. Then the content is up to the application.
The library allow you to send and receive asynchronous messages or to send
synchronous message, which means that you always get an answer to the sent
messages.
For synchronous messages, the driver assume that the second payload word is the
sequence number. So, if you want to use synchronous messages you have to keep in
mind this constraint.
Shared Memory
=============
The **shared memory** is mainly used to synchronize the Real-Time applications
running on different cores, but it can be accessed as well from the host system.
Basically, you can read/write any shared memory location performing different
action. These actions are defined by wrnc_smem_modifier enumeration.
Debug
=====
The **debug** interface is just a very simple serial channel from the cores to
the host system (From the host point of view the debug interface is read only).
It appears under the debugfs file-system, so you must mount the debugfs before
using the debug interface; otherwise you will only get error messages.
The only purpose of the debug interface is to send messages from a Real Time
application to the host system. It's not meant to be a perfect and high
performance communication channel, so it may happen that you loose messages in
some cases (e.g. high rate messages).
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