tdc/doc: added doxygen help

Signed-off-by: Samuel Iglesias Gonsálvez's avatarSamuel Iglesias Gonsalvez <siglesias@igalia.com>
parent d97a1109
all: fmc-tdc.pdf
all: fmc-tdc.pdf doxygen-doc
fmc-tdc.pdf: fmc-tdc.tex
texi2pdf $<
doxygen-doc:
rm -rf fmc-tdc-doxygen
mkdir -p fmc-tdc-doxygen
./doxy.sh -n"FMCTDC Device Driver" -o "fmc-tdc-doxygen" ../lib/libtdc.h
clean:
rm -f *.pdf *.out *.toc *.aux *.log
\ No newline at end of file
rm -f *.pdf *.out *.toc *.aux *.log
rm -rf fmc-tdc-doxygen
all:
This diff is collapsed.
# doxy.sh
# Invokes doxygen modifying a pre-defined doxygen config file.
#
# Known bugs:
# - Exclamation marks (!) in any of the arguments break the script due to
# delimiter collision when invoking sed.
OUTPUT_DIR=doxygen_output
usage()
{
cat << EOF
`basename $0`: generate doxygen documentation
Usage: `basename $0` [-o<OUTPUT_DIRECTORY>] [-n<PROJECT_NAME>] input_files
options:
-h Show this message
-n Name of the project
-o Output directory for the generated files (default: $OUTPUT_DIR)
Example: `basename $0` -o"doxygen_output" -n"MyLib" mylib.c include/mylib.h
EOF
}
while getopts "hn:o:" OPTION
do
case $OPTION in
h)
usage
exit 1
;;
n)
NAME="$OPTARG"
;;
o)
OUTPUT_DIR="$OPTARG"
;;
?)
usage
exit
;;
esac
done
# set subsequent non-option arguments to $1...n
shift $((OPTIND-1))
OPTIND=1
if [[ -z "$*" ]]
then
echo "No input files given"
usage
exit 1
fi
cat $(dirname $0)/default.doxycfg | \
sed "s!__MAGIC_PROJECT_NAME__!$NAME!" | \
sed "s!__MAGIC_OUTPUT_DIRECTORY__!$OUTPUT_DIR!" | \
sed "s!__MAGIC_INPUT__!$*!" | \
doxygen -
......@@ -136,7 +136,7 @@ Get circular buffer pointer value.\\
Clear Dacapo flag from the circular buffer pointer value.\\
\textbf{int tdc\_read(struct tdc\_board *b, int chan, struct tdc\_time *t,
int n, int flags);} \\
Read \textit{n} events. The allowed flags are O\_BLOCKING (blocking read) and O\_NONBLOCKING (non-blocking read).
Read \textit{n} events. The allowed flags are 0 (blocking read) or O\_NONBLOCK (non-blocking read).
\section{Test program}
\subsection{Introduction}
......
/**
* @file libtdc.h
*
* @brief FMC TDC driver library interface
*
* This file describes the external interface to the FMCTDC
* driver and provides the definitions for proper communication
* with the device
*
* Copyright (c) 2012 CERN
* @author Samuel Iglesias Gonsalvez <siglesias@igalia.com>
* @date Oct 24th 2012
*
* @section license_sec License
* Released under the GPL v2. (and only v2, not any later version)
*/
/*! \file */
/*!
* \mainpage FMC TDC Device Driver
* \author Samuel Iglesias Gonsalvez, Igalia S.L.
* \version 24 Oct 2012
*
* An FPGA Mezzanine Card (FMC) with a Time to Digital Converter chip to perform
* one-shot sub-nanosecond time interval measurements.
*
* HW OHWR project: http://www.ohwr.org/projects/fmc-tdc
*
* SW OHWR project: http://www.ohwr.org/projects/fmc-tdc-sw
*
* Copyright (c) 2012 CERN
*/
#ifndef __TDC_LIB_H__
#define __TDC_LIB_H__
......@@ -7,6 +39,10 @@
extern "C" {
#endif
/*!
* This struct is used as argument in almost all the functions.
* The user should not modify its attributes!
*/
struct tdc_board {
int dev_id;
int lun;
......@@ -17,6 +53,9 @@ struct tdc_board {
int data[5]; /* The 5 data channels */
};
/*!
* This struct is used in tdc_read(). It is the event buffer.
*/
struct tdc_time {
uint64_t utc;
uint64_t ticks;
......@@ -24,6 +63,9 @@ struct tdc_time {
uint32_t da_capo;
};
/*!
* This enum can be used in tdc_{s,g}et_channels_term() functions.
*/
enum {
CHAN0 = 1 << 0,
CHAN1 = 1 << 1,
......@@ -32,38 +74,278 @@ enum {
CHAN4 = 1 << 4
};
/**
* @brief Get a handle for a FMCTDC device
*
* @param lun - LUN for fmc-tdc card
*
* @return - pointer to struct tdc_board.
*
*/
extern struct tdc_board *tdc_open(int lun);
/**
* @brief Close a FMCTDC device
*
* @param b - pointer to struct tdc_board
*
* @return >0 - on success, device file descriptor number
* @return <0 - if failure
*
*/
extern int tdc_close(struct tdc_board *b);
/**
* @brief Allocate a event buffer.
*
* @param events - number of elements of the buffer
*
* @return - struct tdc_time pointer.
*
*/
extern struct tdc_time *tdc_zalloc(unsigned int events);
/**
* @brief Free a event buffer.
*
* @param buffer - Buffer to be free'd
*
*/
extern void tdc_free(struct tdc_time *buffer);
/**
* @brief Start acquiring events
*
* @param b - pointer to struct tdc_board
*
* @return >0 - on success, device file descriptor number
* @return <0 - if failure
*
*/
extern int tdc_start_acquisition(struct tdc_board *b);
/**
* @brief Stop acquiring events
*
* @param b - pointer to struct tdc_board
*
* @return >0 - on success, device file descriptor number
* @return <0 - if failure
*
*/
extern int tdc_stop_acquisition(struct tdc_board *b);
/**
* @brief Set host UTC time to FMCTDC board
*
* @param b - pointer to struct tdc_board
*
* @return >0 - on success, device file descriptor number
* @return <0 - if failure
*
*/
extern int tdc_set_host_utc_time(struct tdc_board *b);
/**
* @brief Set UTC time to FMCTDC board
*
* @param b - pointer to struct tdc_board
* @param utc - UTC value to be written, in seconds. EPOC format.
*
* @return >0 - on success, device file descriptor number
* @return <0 - if failure
*
*/
extern int tdc_set_utc_time(struct tdc_board *b, uint32_t utc);
/**
* @brief Get UTC time to FMCTDC board
*
* @param b - pointer to struct tdc_board
* @param utc - Read UTC value, in seconds. EPOC format.
*
* @return >0 - on success, device file descriptor number
* @return <0 - if failure
*
*/
extern int tdc_get_utc_time(struct tdc_board *b, uint32_t *utc);
/**
* @brief Set DAC to FMCTDC board
*
* @param b - pointer to struct tdc_board
* @param dw - DAC word value to be written.
*
* @return >0 - on success, device file descriptor number
* @return <0 - if failure
*
*/
extern int tdc_set_dac_word(struct tdc_board *b, uint32_t dw);
/**
* @brief Set DAC to FMCTDC board
*
* @param b - pointer to struct tdc_board
* @param dw - DAC word value to be read.
*
* @return >0 - on success, device file descriptor number
* @return <0 - if failure
*
*/
extern int tdc_get_dac_word(struct tdc_board *b, uint32_t *dw);
/**
* @brief Set time threshold
*
* The time threshold is the maximum time we will not have an IRQ if there is no
* enough number of events acquired (configured by timestamp threshold).
*
* It doens't means that we have always pending events.
*
* @param b - pointer to struct tdc_board
* @param thres - Time threshold, in seconds.
*
* @return >0 - on success, device file descriptor number
* @return <0 - if failure
*
*/
extern int tdc_set_time_threshold(struct tdc_board *b, uint32_t thres);
/**
* @brief Get time threshold
*
* The time threshold is the maximum time we will not have an IRQ if there is no
* enough number of events acquired (configured by timestamp threshold).
*
* It doens't means that we have always pending events.
*
* @param b - pointer to struct tdc_board
* @param thres - Time threshold, in seconds.
*
* @return >0 - on success, device file descriptor number
* @return <0 - if failure
*
*/
extern int tdc_get_time_threshold(struct tdc_board *b, uint32_t *thres);
/**
* @brief Set timestamp threshold
*
* The timestamp threshold is the number of events (multiplied by two) we want
* per interrupt. It is the double of the expected number of events because ACAM
* chip thinks that each edge of the input signal is an event, but we are only
* interested on the rising edge one.
*
* @param b - pointer to struct tdc_board
* @param thres - Timestamp threshold, in seconds.
*
* @return >0 - on success, device file descriptor number
* @return <0 - if failure
*
*/
extern int tdc_set_timestamp_threshold(struct tdc_board *b, uint32_t thres);
/**
* @brief Get timestamp threshold
*
* The timestamp threshold is the number of events (multiplied by two) we want
* per interrupt. It is the double of the expected number of events because ACAM
* chip thinks that each edge of the input signal is an event, but we are only
* interested on the rising edge one.
*
* @param b - pointer to struct tdc_board
* @param thres - Timestamp threshold, in seconds.
*
* @return >0 - on success, device file descriptor number
* @return <0 - if failure
*
*/
extern int tdc_get_timestamp_threshold(struct tdc_board *b, uint32_t *thres);
/**
* @brief Set channel termination resistor (50 Ohms)
*
* @param b - pointer to struct tdc_board
* @param config - value to enable the channels. Each bit is one channel: bit 0 -> chan 0, bit 1 -> chan 1, etc.
*
* @return >0 - on success, device file descriptor number
* @return <0 - if failure
*
*/
extern int tdc_set_channels_term(struct tdc_board *b, uint32_t config);
/**
* @brief Get channel termination resistor (50 Ohms)
*
* @param b - pointer to struct tdc_board
* @param config - value to enable the channels. Each bit is one channel: bit 0 -> chan 0, bit 1 -> chan 1, etc.
*
* @return >0 - on success, device file descriptor number
* @return <0 - if failure
*
*/
extern int tdc_get_channels_term(struct tdc_board *b, uint32_t *config);
/**
* @brief Enable all channels to acquire
*
* It is needed to execute this function before calling tdc_start_acquisition().
*
* @param b - pointer to struct tdc_board
*
* @return >0 - on success, device file descriptor number
* @return <0 - if failure
*
*/
extern int tdc_activate_channels(struct tdc_board *b);
/**
* @brief Disable all channels to acquire
*
* @param b - pointer to struct tdc_board
*
* @return >0 - on success, device file descriptor number
* @return <0 - if failure
*
*/
extern int tdc_deactivate_channels(struct tdc_board *b);
/**
* @brief Get circular buffer pointer value.
*
* @param b - pointer to struct tdc_board
* @param ptr - circular buffer pointer value with dacapo register included.
*
* @return >0 - on success, device file descriptor number
* @return <0 - if failure
*
*/
extern int tdc_get_circular_buffer_pointer(struct tdc_board *b, uint32_t *ptr);
/**
* @brief Clear Dacapo register.
*
* @param b - pointer to struct tdc_board
*
* @return >0 - on success, device file descriptor number
* @return <0 - if failure
*
*/
extern int tdc_clear_dacapo_flag(struct tdc_board *b);
/**
* @brief Read events
*
* @param b - pointer to struct tdc_board
* @param chan - chan number in decimal, starting from 0 to 4.
* @param t - buffer
* @param n - number of events to read.
* @param flags - flags: 0 (blocking read) or O_NONBLOCK (non blocking read).
*
* @return >0 - on success, device file descriptor number
* @return <0 - if failure
*
*/
extern int tdc_read(struct tdc_board *b, int chan, struct tdc_time *t,
int n, int flags);
#ifdef __cplusplus
......
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