From: Michael Wiebusch Date: Tue, 25 Mar 2014 09:45:03 +0000 (+0100) Subject: started mvdsensorcontrol documentation X-Git-Url: https://jspc29.x-matter.uni-frankfurt.de/git/?a=commitdiff_plain;h=7489b9d5e73122b9e6403ee8c1396a73ad998ee9;p=mvd_docu.git started mvdsensorcontrol documentation --- diff --git a/mvdsensorcontrol/.gitignore b/mvdsensorcontrol/.gitignore new file mode 100644 index 0000000..9c8c91c --- /dev/null +++ b/mvdsensorcontrol/.gitignore @@ -0,0 +1,4 @@ +documentation.pdf +*.svg +actualize +actualize* diff --git a/mvdsensorcontrol/001_lowLevelChain.pdf b/mvdsensorcontrol/001_lowLevelChain.pdf new file mode 100644 index 0000000..9be084c Binary files /dev/null and b/mvdsensorcontrol/001_lowLevelChain.pdf differ diff --git a/mvdsensorcontrol/documentation.tex b/mvdsensorcontrol/documentation.tex new file mode 100644 index 0000000..e897c55 --- /dev/null +++ b/mvdsensorcontrol/documentation.tex @@ -0,0 +1,197 @@ +\documentclass[a4paper,11pt]{article} +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} +\usepackage{lmodern} +\usepackage{graphicx} +\usepackage{subfig} +\usepackage{float} +\usepackage{geometry} +\usepackage{eurosym} +\usepackage{amsmath} +\usepackage{listings} +\geometry{verbose,tmargin=3cm,bmargin=3cm,lmargin=3cm,rmargin=3cm} + + + +\begin{document} +% \bibliographystyle{plain} +% %\bibliographystyle{plainnat} +% +\title{Documentation of the MVDSensorControl tools} +\maketitle +% \begin{titlepage} +% \begin{center} +% \textsc{Master Thesis} \\[4cm] +% \textsc{\huge Employment of the next generation front end electronics for MIMOSA26} \\[2cm] +% \textsc{\Large Michael Wiebusch} \\[4cm] +% \textsc{Institut f\"{u}r Kernphysik} \\ +% \textsc{Goethe-Universit\"{a}t, Frankfurt} \\[2.5cm] +% \begin{align*} +% \text{First examiner}&\text{: Prof. Dr. Joachim Stroth}\\ +% % \text{Second examiner}&\text{: Dr. Christoph Schrader}\\[0.5cm] +% \end{align*} +% \today +% \end{center} +% \end{titlepage} +% +% \newpage +% \thispagestyle{empty} +% \mbox{} +% \newpage +% +% \pagenumbering{Roman} +\tableofcontents +% \newpage +% \pagenumbering{arabic} + + + + + + +%\include{brainstorm} +% \include{motivation/motivation} + +% \include{bib} +\newpage + +\section{JTAG programming} + +\subsection{MIMOSA26 registers and the JTAG controller entity} + +\begin{figure}[H] +\centering +\includegraphics[width=.80\textwidth]{registers.pdf} +\caption{Schema of the MIMOSA26 config registers and the JTAG controller logic entity implemented on FPGA.} +\label{fig::M26andItsRegisters} +\end{figure} + + +The MIMOSA26 chip posesses 11 JTAG settings registers, wich are hardwired to distinct functionalities in the +readout logic part of the sensor (see Figure \ref{fig::M26andItsRegisters}). Most registers are sub-divided +into multiple data fields of variable length (see Figure \ref{fig::datafields}). Each of the in total 82 +datafields corresponds to a distinct function or configurable quantity inside the sensor. +The JTAG programming is handled by a dedicated FPGA design entity, the JTAG Controller. +This entity receives commands from the programming software on a regular PC. + +\begin{figure}[H] +\centering +\includegraphics[width=.90\textwidth]{fields.pdf} +\caption{Schema of an example register, divided into multiple data fields.} +\label{fig::datafields} +\end{figure} + +\subsection{JTAG configuration software} + +The JTAG configuration software is split into two layers: +\begin{itemize} +\item +The high level user interface with its transparent XML-type configuration files. +\item +The low level functionality layer with hex-encoded ini-style configuration files. +\end{itemize} + +The low level software layer\footnote{implemented by Bertram Neumann during his master thesis} handles +the communication with the JTAG controller entity and the transmission of the JTAG register contents +destined to be stored in the sensors. Therefore the programming script parses +ini-style configuration files, which contain a list of strings: each string represents +the hex encoded content of one MIMOSA26 register. +Without knowledge about the technical details of the MIMOSA26 +registers these files should not be edited by hand. Normal users, i.e. non-developers, should ignore +this layer. + +\begin{figure}[H] +\centering +\includegraphics[width=.95\textwidth]{001_lowLevelChain.pdf} +\caption{The low level functionality layer.} +\label{fig::lowLevelchain} +\end{figure} + +The high level interface layer was added to make the JTAG configuration files and their manipulation more +transparent and less error-prone. +The confguration files make use of the XML format. XML is strictly hierarchically structured and human +readable. +While all data fields in the sensor's registers have to be programmed with a defined value, only few of +these ever have to be set to different values than the manufacturer's defaults. +Therefore information to program the sensor is split into two files: +\begin{description} +\item[specification] +The specification XML file contains the specifications of all the sensor's JTAG registers. Each register in the specification +file has a unique register id, a register name and a size (length of register in bits); it possesses +one or more data fields as child nodes. Each datafield has a start, end and size value which define the +relative position of the datafield inside the register. Furthermore the datafield has a name and default value +attribute. +For each register and field there is a short description included along the above specifications. +All specifications and descriptions were adapted from the MIMOSA26 user manual v1.5 without +alteration\footnote{apart from correcting a field size mismatch}. +\item[settings] +The settings XML file containst the actual settings that are defined by the user. +In this XML hierarchy, too, there are registers with data fields as child nodes. Here registers and +data fields are referenced only by ther unique names. Each data field has a value attribute. +The settings file is very streamlined and self-explanatory. +Data fields and registers that are not defined in the settings file are assumed to get the default +values assigned to them. +\end{description} + +\begin{figure}[H] +\centering +\includegraphics[width=.5\textwidth]{xml2ini.pdf} +\caption{The programming information for the sensor is split into a register specification including default values +and an individual settings file for each sensor.} +\label{fig::xml2ini} +\end{figure} + +If the sensor is to be programmed with a configuration file, the perl script "xml2ini.pl" is called. It uses the +specifications file to generate a low level ini file with all registers set to default values. +These default values are then overwritten by the user's values as defined in the configuration file. +This way the user has not to worry about the vast number of settings he does not want to touch at all. +Neither does he has 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 tools} + +\paragraph{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. +\begin{lstlisting} +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{lstlisting} + +\paragraph{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{lstlisting} +ini2xml.pl -i file.ini -s specFile.xml [-o output.xml] [-d] + + 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{lstlisting} + + + + + + + + + + + +\end{document} diff --git a/mvdsensorcontrol/fields.pdf b/mvdsensorcontrol/fields.pdf new file mode 100644 index 0000000..c3365d2 Binary files /dev/null and b/mvdsensorcontrol/fields.pdf differ diff --git a/mvdsensorcontrol/registers.pdf b/mvdsensorcontrol/registers.pdf new file mode 100644 index 0000000..bb0334c Binary files /dev/null and b/mvdsensorcontrol/registers.pdf differ diff --git a/mvdsensorcontrol/xml2ini.pdf b/mvdsensorcontrol/xml2ini.pdf new file mode 100644 index 0000000..dc72ffd Binary files /dev/null and b/mvdsensorcontrol/xml2ini.pdf differ