--- /dev/null
+\section{Appendix}
+\label{sec:appendix}
+
+\subsection{List of JTAG related command line tools}
+
+\subsubsection{xml2ini.pl}
+\label{sec:xml2ini.pl}
+This script creates a low level ini file for the JTAG programming script from a valid configuration XML
+file. The specification file which is used to build the ini file is referenced inside the configuration
+XML file and has not to be given as an argument.
+Under normal conditions this script is not used stand-alone but is called during the execution of
+\hyperref[sec:startup.pl]{startup.pl}.
+\begin{Verbatim}
+xml2ini.pl -c config.xml [-o output.ini]
+
+ Options:
+ -h, --help brief help message
+ -v, --verbose detailed debugging info about ongoing actions
+ -c, --config specifies the input config xml file
+ -o, --output specifies the output filename, if ommitted,
+ the generated ini file is written to STDOUT
+\end{Verbatim}
+
+\subsubsection{ini2xml.pl}
+This script does the opposite of the above one. It parses a valid ini file and converts it back
+to an XML configuration file. By default, only the settings deviant from the specification's defaults
+are reconstructed and written to the output XML file.
+\begin{Verbatim}
+ini2xml.pl -i file.ini -s specFile.xml [-o output.xml]
+
+ Options:
+ -h, --help brief help message
+ -v, --verbose detailed debugging info about ongoing actions
+ -i, --ini specifies the input .ini file
+ -s, --spec specifies the specification xml file by
+ which the .ini file is to be decoded
+ -o, --output specifies the output filename, if ommitted
+ the generated xml is written to STDOUT
+ -r, --redundant write settings to config file that are identical
+ with the specification defaults
+\end{Verbatim}
+
+\subsubsection{xmlOperation.pl}
+\label{sec:xmlOperation.pl}
+This script is a tool to edit parameters of an XML configuration file. It can edit any editable
+entry of a given configuration file, but can only process one command at a time. The script has
+a CGI interface (invoked via HTTP request) but it can also be used from the command line.
+
+The configuration and the specification XML files are declared without path.
+The tool assumes, that the configuration XML files are stored in "../../mvdconfig/config/"
+and the specification files are stored in "../specs/"
+(relative to the location of xmlOperation.pl).
+\begin{Verbatim}
+usage:
+
+ via CGI/HTTP request:
+ http://[...]/mvdsensorcontrol/tools/xmlOperation.pl?\
+ action=[action]&[parameter]&[parameter]& ...
+
+ via command line:
+ xmlOperation.pl action=[action] [parameter] [parameter] ...
+ (just like the CGI request, just leave out ? and &)
+
+possible actions: save, delete, copyDefaultRegister,
+ createFile, deleteFile, changeAncestor
+
+parameter explanation:
+
+ save a value into a specific field, optional: if you enter a numeric base,
+ value will be saved in the specified format.:
+ action=save&configFile=[configFile]®ister=[register]&field=[field]&\
+ value=[value]&base=[base]
+
+ delete a specific field:
+ action=delete&configFile=[configFile]®ister=[register]&field=[field]
+
+ delete a whole register:
+ action=delete&configFile=[configFile]®ister=[register]
+
+ copy a register including default values from the specification
+ to the config file:
+ action=copyDefaultRegister&configFile=[configFile]®ister=[register]
+
+ create a new config file based on the given specification file
+ action=createFile&configFile=[configFile]&specFile=[specFile]
+
+ delete a config file
+ action=deleteFile&configFile=[configFile]
+
+ change the ancestor (include directive) of config file
+ action=changeAncestor&configFile=[configFile]&newAncestor=[newAncestor]
+
+ move/rename config file
+ action=moveFile&configFile=[configFile]&newFile=[newFile]
+
+ copy config file
+ action=copyFile&configFile=[configFile]&newFile=[newFile]
+\end{Verbatim}
+
+\subsubsection{changeConfigVal.pl}
+Regarding \hyperref[sec:xmlOperation.pl]{xmlOperation.pl}, changeConfigVal.pl is redunant in its
+functionality. It is merely a comfortable shortcut to change parameters inside a configuration
+XML file on the fly.
+The script parses STDIN for attribution directives in the format "registerName/fieldName=value" and applies
+these attributions to a denoted configuration XML file. Multiple attributions can be processed at
+the same time when separated by semicolon or line break.
+Values can be entered as hex (with prefix "0x"), binary (with prefix "0b") or decimal number
+(no prefix).
+The configuration file has to be declared with its full path.
+\begin{Verbatim}
+changeConfigVal.pl -c /path/to/config.xml [-v]
+
+ Options:
+ -h, --help brief help message
+ -v, --verbose detailed debugging info about ongoing actions
+ -c, --config specifies the input config xml file
+ (including path if necessary!)
+\end{Verbatim}
+
+\subsubsection{startup.pl}
+\label{sec:startup.pl}
+The script runs the necessary steps to configure and start the MAPS sensors. From a given
+\hyperref[sec:setupFile]{setup configuration file} (with full path!) the script extracts:
+\begin{itemize}
+\item
+The topology of the setup, i.e. how many controllers (and their addresses), how many chains, how many
+sensors in each chain
+\item
+Which JTAG configuration XML file is associated to which sensor
+\end{itemize}
+Subsequently the script builds a set of low level JTAG configuration ini files (using
+\hyperref[sec:xml2ini.pl]{xml2ini.pl}) and calls the JTAG programming tools to program and start
+the sensors.
+(!!) It does not (yet) set the sensor enable, JTAG enable, and power switches on the Converter Board
+to the correct settings! This has to be done manually! (!!)
+\begin{Verbatim}[label=startup.pl usage]
+startup.pl /path/to/setupFile
+
+ Options:
+ -h, --help brief help message
+ -v, --verbose be verbose to STDERR
+ --dryrun create but don't run scripts
+
+\end{Verbatim}
+
+
+\subsection{Miscellaneous command line tools}
+\subsubsection{adcread.pl}
+\label{sec:adcread.pl}
+Adcread.pl is a command line utility that acquires ADC readings from the converter board.
+The tool is able to acquire an arbitrary number of samples with an adjustable sampling delay.
+The output includes mean and standard deviation of the acquired values, as well as
+the minimum and maximum value that was seen by the FPGA (not the computer) during the
+entire sampling period. The script can be invoked via an HTTP/CGI GET request or directly
+from the command line.
+
+For continuous visual monitoring of the values, there exists a graphical tool:
+\hyperref[sec:adcmon]{Adcmon}
+(see section \ref{sec:adcmon}).
+
+\begin{Verbatim}[label=adcread.pl usage]
+Usage (cmdline):
+ adcread.pl FPGA=<address> chip=<number> channel=<channelName> [OPTIONS]
+Usage (CGI) :
+ adcread.pl?FPGA=<address>&chip=<number>&channel=<channelName>[&OPTIONS]
+
+Reads n (default=10) values from selected ConverterBoard(v2013) ADCs and
+prints out their mean and stdev, as well as the minimum and maximum value
+that the FPGA has seen during readout time (regardless of whether min and
+max have been sampled by this script).
+
+Results will have the following format:
+ <mean>\t<stdev>\t<min>\t<max>\n
+
+Options:
+ n = <number> sample <number> values
+ delay = <ms> delay between samples (default=5ms)
+ DAQOPSERVER = <host>:<port> sets the DAQOPSERVER
+ (server which hosts TRBnet daemon)
+ if left out, will use DAQOPSERVER ENV variable
+ verbose = <0|1> if verbose=1 then script will print all sampled
+ values as well as the channel unit and other
+ debug data
+ unit = <0|1> if unit=1 then only the selected channel
+ unit is printed
+
+available ADC channels:
+
+ CurrentDigital
+ CurrentAnalog
+ VoltageDigital
+ VoltageAnalog
+ VoltageGnd
+ SensorTemperature
+ ZeroSingle
+ ZeroDifferential
+ VDiscRef2A
+ VDiscRef2B
+ VDiscRef2C
+ VDiscRef2D
+ VDiscRefA
+ VDiscRefB
+ VDiscRefC
+ VDiscRefD
+
+Example:
+ cmdline:
+ adcread.pl DAQOPSERVER=localhost:88 FPGA=0xd882 chip=0 channel=CurrentDigital
+ CGI :
+ adcread.pl?DAQOPSERVER=localhost:88&FPGA=0xd882&chip=0&channel=CurrentDigital
+\end{Verbatim}
+
+
+
+\subsection{Overview of the daqscripts (draft!)}
+\subsubsection{run.pl}
+\label{sec:run.pl}
+\begin{description}
+\item[is called by]
+testgui.pl with parameters "setupFile" and "runtime" (CGI/HTTP request)
+\item[does]
+\begin{itemize}
+\item
+parse \hyperref[sec:setupFile]{setupFile}, extract systemName
+\item
+parse \hyperref[sec:systemFile]{systemFile}, extract gbe address and gbe port(s), extract daqopserver and set this as env variable.
+\item
+remove stale hld dumps, remove stale matrix plots
+\end{itemize}
+\item[calls]
+startup.pl with parameter setupFile
+\item[calls]
+./preview/exec\_evtbuild\_t.pl with arguments runtime, dumpPath, systemName and ports
+\item[calls]
+./preview/unpack\_hld.pl with arguments dumpfile, picPath and systemName
+\end{description}
+
+\subsubsection{exec\_evtbuild\_t.pl}
+\begin{description}
+\item[is called by]
+\hyperref[sec:run.pl]{run.pl} with arguments runtime, dumpPath, systemName and ports
+\item[calls]
+daq\_netmem with timeout and shm name
+\item[calls]
+daq\_evtbuild with timeout and shm name
+\end{description}
+
+\subsubsection{start.pl}
+\begin{description}
+\item[is called by] manual with argument systemName (not file, no path)
+\item[does]
+\begin{itemize}
+\item
+Parse corresponding systemFile to systemName
+\item
+Extract addresses of hub, gbe and roc
+\item
+Set addresses of FPGAs according to database definitions
+\item
+Set GbE Configuration (common for all boards) (??)
+\item
+Send arbiter start signal
+\end{itemize}
+
+\end{description}
+
+\subsubsection{startup.pl}
+Run the necessary steps to configure and start MAPS sensors.
+(see also section \hyperref[sec:startup.pl]{startup.pl})
+\begin{description}
+\item[is called by]
+run.pl or manual with argument /path/to/setupFile
+\item[does]
+\begin{itemize}
+\item
+extract sensor, chain and controller parameters from setup file
+\item
+generate all necessary low lewel JTAG configuration ini files from the high level configuration
+XML files
+\item
+call JTAG programmer, program and initialize the sensors
+\end{itemize}
+\end{description}
+
+
\label{sec:The_JTAG_configuration_file}
As mentioned before, in the setup configuration file each sensor is assigned a proper JTAG
configuration file that defines the content of the sensor's JTAG registers and thus determines
-its behaviour. The configuration of the JTAG registers involves an excessive supply of options
+its behaviour. The configuration of the JTAG registers involves an excessive amount of options
that massively complicates keeping an overview over the important settings.
As a counter measure an elaborate configuration software concept was developed wich is explained
in detail in the following section (section \ref{sec:JTAG_programming}).
+To briefly summarize the concept: The JTAG configuration information is split into two parts:
+A common specification file which contains all the sensor's register definitions and
+default values,
+and the actual settings files the user can edit and which are assigned to the individual
+sensors via the setup configuration file.
+Though, in principle, the JTAG configuration files can be edited by hand, this procedure
+is not recommended.
+For fast, correct and painless editing a dedicated
+\hyperref[sec:jtageditor]{graphical JTAG configuration file editor}
+was implemented.
\ No newline at end of file
-
-\section{Overview of the daqscripts (draft!)}
-\subsection{run.pl}
-\label{sec:run.pl}
-\begin{description}
-\item[is called by]
-testgui.pl with parameters "setupFile" and "runtime" (CGI/HTTP request)
-\item[does]
-\begin{itemize}
-\item
-parse \hyperref[sec:setupFile]{setupFile}, extract systemName
-\item
-parse \hyperref[sec:systemFile]{systemFile}, extract gbe address and gbe port(s), extract daqopserver and set this as env variable.
-\item
-remove stale hld dumps, remove stale matrix plots
-\end{itemize}
-\item[calls]
-startup.pl with parameter setupFile
-\item[calls]
-./preview/exec\_evtbuild\_t.pl with arguments runtime, dumpPath, systemName and ports
-\item[calls]
-./preview/unpack\_hld.pl with arguments dumpfile, picPath and systemName
-\end{description}
-
-\subsection{exec\_evtbuild\_t.pl}
-\begin{description}
-\item[is called by]
-\hyperref[sec:run.pl]{run.pl} with arguments runtime, dumpPath, systemName and ports
-\item[calls]
-daq\_netmem with timeout and shm name
-\item[calls]
-daq\_evtbuild with timeout and shm name
-\end{description}
-
-\subsection{start.pl}
-\begin{description}
-\item[is called by] manual with argument systemName (not file, no path)
-\item[does]
-\begin{itemize}
-\item
-Parse corresponding systemFile to systemName
-\item
-Extract addresses of hub, gbe and roc
-\item
-Set addresses of FPGAs according to database definitions
-\item
-Set GbE Configuration (common for all boards) (??)
-\item
-Send arbiter start signal
-\end{itemize}
-
-\end{description}
-
-\subsection{startup.pl}
-Run the necessary steps to configure and start MAPS sensors.
-(see also section \hyperref[sec:startup.pl]{startup.pl})
-\begin{description}
-\item[is called by]
-run.pl or manual with argument /path/to/setupFile
-\item[does]
-\begin{itemize}
-\item
-extract sensor, chain and controller parameters from setup file
-\item
-generate all necessary low lewel JTAG configuration ini files from the high level configuration
-XML files
-\item
-call JTAG programmer, program and initialize the sensors
-\end{itemize}
-\end{description}
\ No newline at end of file
\include{config_structure}
\include{jtag}
\include{gui}
-\include{daqscripts}
+\include{appendix}
\include{bib}
\include{remarks}
\begin{figure}[H]
\centering
\includegraphics[width=.85\textwidth]{jtageditor.png}
-\caption{Screenshot of the JTAGeditor GUI}
+\caption{Screenshot of the JTAG editor GUI}
\label{fig:jtageditor_ssht}
\end{figure}
\label{fig:testgui_ssht}
\end{figure}
+\subsection{Adcmon}
+\label{sec:adcmon}
+\begin{figure}[H]
+\centering
+\includegraphics[width=1\textwidth]{adcmon.png}
+\caption{Screenshot of the Adcmon application}
+\label{fig:adcmon_ssht}
+\end{figure}
+The Adcmon application is a utility for the surveillance of the converter board ADC channels.
+All channels that monitor the behaviour of one sensor can be viewed simultaneously in one
+instance of this application.
+The GUI is divided into two panes (see figure \ref{fig:adcmon_ssht}), the "Plots" pane on the left and the "Settings" pane on the right.
+The usage is self explanatory: In the "Settings" pane the user has to select the desired FPGA, converter board (0 or
+1\footnote{currently only one converter board per FPGA is implemented}), and sensor chip (0 or 1).
+Now the ADC channels can be selected by clicking checkboxes next to a list of available ADC channels below.
+After pressing the start button, the selected channels are plotted in the "Plots" panel as a function of time.
+The time resolution of the plots is \SI{10}{\hertz} and the display is refreshed every second.
+
+The ADC readout frequency is much higher (??) than the sampling frequency of the plotting utility.
+To make use of the surplus data, there is a logic entity inside the FPGA that stores the minimum and
+maximum of the ADC values that are received
+from the converter board in between the value requests by the plotting tool.
+These minima and maxima are read out by the plotting utility along with the current ADC value.
+The curves for the minimum and maximum values are plotted in red and green, their distance can be used to estimate the amount of noise
+on the particular ADC channel.
+\begin{figure}[H]
+\centering
+\includegraphics[width=1\textwidth]{plot_service.pdf}
+\caption{Schema of the plot service that runs in the background}
+\label{fig:plot_service}
+\end{figure}
-
-
+The Adcmon application consists of two layers:
+While the visible part of Adcmon (adcmon.pl) is merely a front-end,
+the communication with the hardware
+and the creation of the plots is performed by a back-end service: plotService.pl (see figure
+\ref{fig:plot_service}).
+When an instance of adcmon.pl is first activated (by opening the front-end
+in a web browser and clicking on the start button) plotService.pl is started and begins
+to process the requests from the front-end.
+The finished plots are written to a shared memory directory from which adcmon.pl can read.
+If another instance of adcmon.pl is started, it will recognize that plotService.pl is already
+started and send its own requests to the same service as the previous instance.
+Even when two or more front-ends request plots for identical channels, the back-end work is
+done only once. When a specific plot is ready, it is made accessible to all front-end instances
+via the shared memory directory.
+
+When an instance of adcmon.pl is closed or stopped by clicking on the stop button, the
+instance is sending no more requests. Consequently plotService.pl will discontinue
+executing the tasks that are no longer requested. When plotService.pl receives no more
+requests, i.e. when all front-ends are closed, it will start a countdown and consequently
+terminate itself until it is invoked again by adcmon.pl.
+
+The Adcmon application relies on xml-db from the daqtools package to acquire a list of
+all available ADC channels and their respective raw value conversion functions.
+
+There exists a command line/CGI script to acquire ADC values without plotting them:
+\hyperref[sec:adcread.pl]{adcread.pl} (see section \ref{sec:adcread.pl}).
Neither does he have to care how to align the values relative to the corresponding registers. With the
configuration file, the user has a clear "key->value" type interface to the sensor's JTAG settings.
-\subsection{List of JTAG related command line tools}
-
-\subsubsection{xml2ini.pl}
-\label{sec:xml2ini.pl}
-This script creates a low level ini file for the JTAG programming script from a valid configuration XML
-file. The specification file which is used to build the ini file is referenced inside the configuration
-XML file and has not to be given as an argument.
-Under normal conditions this script is not used stand-alone but is called during the execution of
-\hyperref[sec:startup.pl]{startup.pl}.
-\begin{Verbatim}
-xml2ini.pl -c config.xml [-o output.ini]
-
- Options:
- -h, --help brief help message
- -v, --verbose detailed debugging info about ongoing actions
- -c, --config specifies the input config xml file
- -o, --output specifies the output filename, if ommitted,
- the generated ini file is written to STDOUT
-\end{Verbatim}
-
-\subsubsection{ini2xml.pl}
-This script does the opposite of the above one. It parses a valid ini file and converts it back
-to an XML configuration file. By default, only the settings deviant from the specification's defaults
-are reconstructed and written to the output XML file.
-\begin{Verbatim}
-ini2xml.pl -i file.ini -s specFile.xml [-o output.xml]
-
- Options:
- -h, --help brief help message
- -v, --verbose detailed debugging info about ongoing actions
- -i, --ini specifies the input .ini file
- -s, --spec specifies the specification xml file by
- which the .ini file is to be decoded
- -o, --output specifies the output filename, if ommitted
- the generated xml is written to STDOUT
- -r, --redundant write settings to config file that are identical
- with the specification defaults
-\end{Verbatim}
-
-\subsubsection{xmlOperation.pl}
-\label{sec:xmlOperation.pl}
-This script is a tool to edit parameters of an XML configuration file. It can edit any editable
-entry of a given configuration file, but can only process one command at a time. The script has
-a CGI interface (invoked via HTTP request) but it can also be used from the command line.
-
-The configuration and the specification XML files are declared without path.
-The tool assumes, that the configuration XML files are stored in "../../mvdconfig/config/"
-and the specification files are stored in "../specs/"
-(relative to the location of xmlOperation.pl).
-\begin{Verbatim}
-usage:
-
- via CGI/HTTP request:
- http://[...]/mvdsensorcontrol/tools/xmlOperation.pl?\
- action=[action]&[parameter]&[parameter]& ...
-
- via command line:
- xmlOperation.pl action=[action] [parameter] [parameter] ...
- (just like the CGI request, just leave out ? and &)
-
-possible actions: save, delete, copyDefaultRegister,
- createFile, deleteFile, changeAncestor
-
-parameter explanation:
-
- save a value into a specific field, optional: if you enter a numeric base,
- value will be saved in the specified format.:
- action=save&configFile=[configFile]®ister=[register]&field=[field]&\
- value=[value]&base=[base]
-
- delete a specific field:
- action=delete&configFile=[configFile]®ister=[register]&field=[field]
-
- delete a whole register:
- action=delete&configFile=[configFile]®ister=[register]
-
- copy a register including default values from the specification
- to the config file:
- action=copyDefaultRegister&configFile=[configFile]®ister=[register]
-
- create a new config file based on the given specification file
- action=createFile&configFile=[configFile]&specFile=[specFile]
-
- delete a config file
- action=deleteFile&configFile=[configFile]
-
- change the ancestor (include directive) of config file
- action=changeAncestor&configFile=[configFile]&newAncestor=[newAncestor]
-
- move/rename config file
- action=moveFile&configFile=[configFile]&newFile=[newFile]
-
- copy config file
- action=copyFile&configFile=[configFile]&newFile=[newFile]
-\end{Verbatim}
-
-\subsubsection{changeConfigVal.pl}
-Regarding \hyperref[sec:xmlOperation.pl]{xmlOperation.pl}, changeConfigVal.pl is redunant in its
-functionality. It is merely a comfortable shortcut to change parameters inside a configuration
-XML file on the fly.
-The script parses STDIN for attribution directives in the format "registerName/fieldName=value" and applies
-these attributions to a denoted configuration XML file. Multiple attributions can be processed at
-the same time when separated by semicolon or line break.
-Values can be entered as hex (with prefix "0x"), binary (with prefix "0b") or decimal number
-(no prefix).
-The configuration file has to be declared with its full path.
-\begin{Verbatim}
-changeConfigVal.pl -c config.xml [-v]
-
- Options:
- -h, --help brief help message
- -v, --verbose detailed debugging info about ongoing actions
- -c, --config specifies the input config xml file
- (including path if necessary!)
-\end{Verbatim}
-
-\subsubsection{startup.pl}
-\label{sec:startup.pl}
-The script runs the necessary steps to configure and start the MAPS sensors. From a given
-\hyperref[sec:setupFile]{setup configuration file} (with full path!) the script extracts:
-\begin{itemize}
-\item
-The topology of the setup, i.e. how many controllers (and their addresses), how many chains, how many
-sensors in each chain
-\item
-Which JTAG configuration XML file is associated to which sensor
-\end{itemize}
-Subsequently the script builds a set of low level JTAG configuration ini files (using
-\hyperref[sec:xml2ini.pl]{xml2ini.pl}) and calls the JTAG programming tools to program and start
-the sensors.
-(!!) It does not (yet) set the sensor enable, JTAG enable, and power switches on the Converter Board
-to the correct settings! This has to be done manually! (!!)
-\begin{Verbatim}
-startup.pl /path/to/setupFile
-
- Options:
- -h, --help brief help message
- -v, --verbose be verbose to STDERR
- --dryrun create but don't run scripts
-
-\end{Verbatim}
-
-
\subsection{Naming consistency notes}
\begin{itemize}
\item
+Figure/figure ... check that
+\item
Converter board
\item
Front-end board ??
\subsection{ToDo}
\begin{itemize}
\item
+redesign selectors of adcmon, so they can be operated in terms of
+system/setup
+\item
+find out adc readout frequency on converter board
+\item
put description of low level daq scripts in appendix
\item
complete summary of converter board control registers (appendix?)
jspc29 / mvd_docu.git / commitdiff
