From ebd951b0e16b70a5467bd10f252713d429720d6f Mon Sep 17 00:00:00 2001
From: Samuel Meehan <smeehan12@gmail.com>
Date: Thu, 23 Apr 2020 11:52:55 +0200
Subject: [PATCH] updated doxygen stuff a bit
---
Doxyfile | 12 +--
.../EventFormats/DigitizerDataFragment.hpp | 83 +++++++++++++++++--
Logging/include/Logging.hpp | 10 +--
README.md | 78 +++++++++++++----
4 files changed, 148 insertions(+), 35 deletions(-)
diff --git a/Doxyfile b/Doxyfile
index 37b01ec..5554d7d 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -467,7 +467,7 @@ LOOKUP_CACHE_SIZE = 0
# normally produced when WARNINGS is set to YES.
# The default value is: NO.
-EXTRACT_ALL = NO
+EXTRACT_ALL = YES
# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
# be included in the documentation.
@@ -829,7 +829,7 @@ WARN_LOGFILE =
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
-INPUT = build EventFormats Exceptions Logging
+INPUT = build EventFormats Exceptions Logging/include/Logging.hpp .
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -904,7 +904,7 @@ FILE_PATTERNS = *.c \
# be searched for input files as well.
# The default value is: NO.
-RECURSIVE = NO
+RECURSIVE = YES
# The EXCLUDE tag can be used to specify files and/or directories that should be
# excluded from the INPUT source files. This way you can easily exclude a
@@ -1022,7 +1022,7 @@ FILTER_SOURCE_PATTERNS =
# (index.html). This can be useful if you have a project on for instance GitHub
# and want to reuse the introduction page also for the doxygen output.
-USE_MDFILE_AS_MAINPAGE =
+USE_MDFILE_AS_MAINPAGE = README.md
#---------------------------------------------------------------------------
# Configuration options related to source browsing
@@ -2260,7 +2260,7 @@ HIDE_UNDOC_RELATIONS = YES
# set to NO
# The default value is: NO.
-HAVE_DOT = NO
+HAVE_DOT = YES
# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed
# to run in parallel. When set to 0 doxygen will base this on the number of
@@ -2365,7 +2365,7 @@ INCLUDE_GRAPH = YES
# The default value is: YES.
# This tag requires that the tag HAVE_DOT is set to YES.
-INCLUDED_BY_GRAPH = YES
+INCLUDED_BY_GRAPH = NO
# If the CALL_GRAPH tag is set to YES then doxygen will generate a call
# dependency graph for every global function or class method.
diff --git a/EventFormats/EventFormats/DigitizerDataFragment.hpp b/EventFormats/EventFormats/DigitizerDataFragment.hpp
index facfcde..ef5df47 100644
--- a/EventFormats/EventFormats/DigitizerDataFragment.hpp
+++ b/EventFormats/EventFormats/DigitizerDataFragment.hpp
@@ -8,6 +8,8 @@
#define CERR std::cout<<__LINE__<<std::endl;
+/*! A test class */
+
static inline int GetBit(unsigned int word, int bit_location){
// obtain the value of a particular bit in a word
word = (word>>bit_location);
@@ -18,7 +20,10 @@ static inline int GetBit(unsigned int word, int bit_location){
class DigitizerDataException : public Exceptions::BaseException { using Exceptions::BaseException::BaseException; };
struct DigitizerDataFragment {
-
+
+////////////////////////////////////////////////////
+/// Constructor for creating a parsed digitizer event fragment
+////////////////////////////////////////////////////
DigitizerDataFragment( const uint32_t *data, size_t size ) {
m_size = size;
@@ -104,7 +109,15 @@ struct DigitizerDataFragment {
}
- // to check the validity of the data object for readback after decoding
+////////////////////////////////////////////////////
+/// Check the validity of the fragment that has been parsed
+///
+/// This checks the following
+/// - The full fragment size is as expected and matches the size that the fragment
+/// in the EventPayload finds
+/// - The number of samples in all channels with event data (as specified in the
+/// channel mask) have the same number of samples
+////////////////////////////////////////////////////
bool valid() const {
bool validityFlag = true; // assume innocence until proven guilty
@@ -130,41 +143,97 @@ struct DigitizerDataFragment {
}
public:
- // getters
+////////////////////////////////////////////////////
+/// Retrieves the total size of the event, including the header. This should be equal to :
+/// - 4 words for the header
+/// - N*(M/2) words for the readout data where N is the number of channels enabled for readout and M is the length of the buffer
+////////////////////////////////////////////////////
uint32_t event_size() const { return event.event_size; }
+
+////////////////////////////////////////////////////
+/// Retrieves the hardware board identifier
+////////////////////////////////////////////////////
uint32_t board_id() const { return event.board_id; }
+
+////////////////////////////////////////////////////
+/// Retrieves the board failure flag (a single bit) which should be set to 0 if everything is fine
+/// and is set to 1 in the case of a hardware issue (e.g. PLL unlock).
+////////////////////////////////////////////////////
uint32_t board_fail_flag() const { return event.board_fail_flag; }
+
+////////////////////////////////////////////////////
+/// Retrieves the 16 bit pattern that was on the LVDS I/O flat cable upon the trigger reception
+////////////////////////////////////////////////////
uint32_t pattern_trig_options() const { return event.pattern_trig_options; }
+
+////////////////////////////////////////////////////
+/// Retrieves the channel mask that specifies which channels were enabled for readout in a given event.
+/// This data can also be accessed via the channel_has_data() method
+////////////////////////////////////////////////////
uint32_t channel_mask() const { return event.channel_mask; }
+
+////////////////////////////////////////////////////
+/// Retrieves the local event counter of all triggered events
+////////////////////////////////////////////////////
uint32_t event_counter() const { return event.event_counter; }
+
+////////////////////////////////////////////////////
+/// Retrieves the Trigger Time Tag
+////////////////////////////////////////////////////
uint32_t trigger_time_tag() const { return event.trigger_time_tag; }
+
+////////////////////////////////////////////////////
+/// Retrieves the number of samples in the buffer for a single channel
+////////////////////////////////////////////////////
int n_samples() const { return event.n_samples; }
+
+////////////////////////////////////////////////////
+/// Retrieves a copy of the full ADC count structure for all channels. This is available for completeness
+/// but it is recommended to retrieve data from a single channel at a time using the channel_adc_counts()
+/// function which simply provides a reference
+////////////////////////////////////////////////////
std::map<int, std::vector<uint16_t> > adc_counts() const { return event.adc_counts; }
+
+////////////////////////////////////////////////////
+/// Retrieves the data for a single channel, regardless of whether that channel was enabled for reading.
+/// If it was not enabled, it will print a WARNING to the screen but proceed to give you empty data.
+////////////////////////////////////////////////////
const std::vector<uint16_t>& channel_adc_counts(int channel) const {
// verify that the channel requested is in the channel mask
if( GetBit(event.channel_mask, channel)==0 ){
- INFO("You have requesting data for channel "<<channel<<" for which reading was not enabled at data taking according to the channel mask.");
+ WARNING("You have requesting data for channel "<<channel<<" for which reading was not enabled at data taking according to the channel mask.");
}
// verify that the channel requested is in the map of adc counts
if( event.adc_counts.find(channel)==event.adc_counts.end()){
- INFO("You are requesting data for channel "<<channel<<" for which there is no entry in the adc counts map.");
+ WARNING("You are requesting data for channel "<<channel<<" for which there is no entry in the adc counts map.");
}
return event.adc_counts.find(channel)->second;
}
+
+////////////////////////////////////////////////////
+/// Helper function to let you determine if a given channel has data stored after decoding the event
+////////////////////////////////////////////////////
bool channel_has_data(int channel) const {
return GetBit(event.channel_mask, channel);
}
+
+////////////////////////////////////////////////////
+/// Retrieves the size of the full event fragment, including the header as the number of 8 bit words
+////////////////////////////////////////////////////
size_t size() const { return m_size; }
- //setters
+
+////////////////////////////////////////////////////
+/// Sets the debug flag to on for the decoding object
+////////////////////////////////////////////////////
void set_debug_on( bool debug = true ) { m_debug = debug; }
private:
struct DigitizerEvent {
- uint32_t event_size;
+ uint32_t event_size; /// The total size of the event including the header
uint32_t board_id;
bool board_fail_flag;
bool event_format; // should always be 0
diff --git a/Logging/include/Logging.hpp b/Logging/include/Logging.hpp
index 1311dc1..3c4752f 100644
--- a/Logging/include/Logging.hpp
+++ b/Logging/include/Logging.hpp
@@ -15,11 +15,11 @@
#pragma message "Compiled without DAQling logger"
// Base log output - just printing to screen
-#define LOG(LEVEL,MSG) std::cout << "[" << LEVEL <<"] " \
- <<"(file = "<<std::left<<__FILE__<<")" \
- <<"(func = "<<std::left<<__FUNCTION__<<")" \
- <<"(line = "<<std::left<<__LINE__<<")" \
- <<" | "<< MSG << std::endl; \
+#define LOG(LEVEL,MSG) std::cout << "[" << LEVEL <<"] " \
+ <<"(file = "<<std::left<<__FILE__<<")" \
+ <<"(func = "<<std::left<<__FUNCTION__<<")" \
+ <<"(line = "<<std::left<<__LINE__<<")" \
+ <<" | "<< MSG << std::endl; \
// Log levels
#define TRACE(MSG) LOG("TRACE", MSG)
diff --git a/README.md b/README.md
index 52233b6..f568d50 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,53 @@
-# faser-common
+# faser-common Description
-Software common to detector, online and offline faser code
+This houses software common to detector, online and offline faser code. It includes
+some utilities/functions as well as the event decoders that convert binary data
+to useable data stored in memory for offline reconstruction. This can be included
+in other code bases as well as built and run standalone.
+# Code Bases
+There are different bits of code here that serve separate purposes. Note that this
+documentation is also used by doxygen and when viewing that page, this provides the
+links to those places.
+
+## EventFormats
+DAQFormats ([Link To Source](EventFormats/EventFormats/DAQFormats.hpp)):
+This is the base of all raw data formats.
+
+DigitizerDataFragment ([Link To Source](EventFormats/EventFormats/DigitizerDataFragment.hpp)):
+This is the digitizer specific data format and event decoder.
+
+TLBDataFragment ([Link To Source](EventFormats/EventFormats/TLBDataFragment.hpp)):
+This is the trigger logic board specific data format and event decoder for *data* fragments.
+
+TLBMonitoringFragment ([Link To Source](EventFormats/EventFormats/TLBMonitoringFragment.hpp)):
+This is the trigger logic board specific data format and event decoder for *monitoring* fragments.
+
+## Exceptions
+Exceptions ([Link To Source](Exceptions/Exceptions/Exceptions.hpp)):
+This houses the functionality for exceptions handling.
+
+## Logging
+Logging ([Link To Source](Logging/include/Logging.hpp)):
+This houses a set of utilities that allow one to mimic DAQ-ling logging in their
+hardware specific code to avoid writing std::cout statements in a controlled way.
+
+
+
+
+
+# Standalone Build Instructions
+The code can be built standalone on machines that have the right software installed.
+One example of this is the __faser-daq-001.cern.ch__ machine housed in the CaloScint
+lab at CERN. If you need credentials for this machine, contact [Brian Petersen](mailto:Brian.Petersen@cern.ch).
+
+The other options is to use [docker](https://www.docker.com/) ([Tutorial Here](https://matthewfeickert.github.io/intro-to-docker/))
+for which we have an image configured to mimic the environment necessary for uses such as this. The image
+__gitlab-registry.cern.ch/faser/docker/daq__ is built and housed at [faser/docker](https://gitlab.cern.ch/faser/docker)
+and used for the CI tests as well. If you boot into that image, then it will work as well.
+
+Once you have configured one of these methods, you can build the code as :
-# Build Instructions
```
source setup.sh
mkdir -p build
@@ -12,33 +56,33 @@ cmake3 ..
make
```
-# Event Decoders
+# Standalone Running/Testing
-## Executables
+## Event Decoders
Once you build the code, there is a primary executable [eventDump.cxx](EventFormats/app/eventDump.cxx)
which is compiled into the executable in your build directory at `build/EventFormats/eventDump` which
can be run on test binary data to develop or understand the functionality of the event/fragment decoders.
-
-## Test Input
-The following are test data recorded which can be used to work with the standalone event decoders.
-
-### April 16
-TLB + Digitizer data were recorded with the scintillator lab lockdown
+Test data were recorded on April 16 which can be used to work with the standalone event decoders. These test runs
+were done with the TLB + Digitizer and were recorded with the scintillator lab lockdown
setup using the branch - [TLB-Digi-testing](https://gitlab.cern.ch/faser/daq/-/tree/TLB-Digi-testing).
The data can be found on the faserdaq service account EOS space at `/eos/user/f/faserdaq/TestData/2020_April16`
with readme.txt contained within. It should be noted that the data has small (Trigger receiver)
bug in it and there are corrupted events in physics stream. Two configurations exist:
- - 1)
- - 200 Hz input signal into channel 0 & 2
+ - [Run 1]
+ - 200 Hz input signal into channel 0 & 2 of the Digitizer
- Coincidence signal, prescale 1 (~100 Hz)
- single signal input 1, prescale 2 (~50 Hz)
- ~25 Hz random trigger
- - 1 Hz monitoring data
- - 2)
- - 200 Hz input signal into channel 0 & 2
+ - 1 Hz monitoring data from the TLB
+ - Only channel 1 is enabled for data readout from the Digitizer
+ - [Run 2]
+ - 200 Hz input signal into channel 0 & 2 of the Digitizer
- Coincidence signal, prescale 1 (~100 Hz)
- single signal input 1, prescale 3 (~30 Hz)
- single signal input 2, prescale 10 (~10 Hz)
- ~25 Hz random trigger, prescale 3 (~10 Hz)
- - 1 Hz monitoring data
+ - 1 Hz monitoring data from the TLB
+ - Only channel 1 is enabled for data readout from the Digitizer
+
+
\ No newline at end of file
--
GitLab