Skip to content

C
Conv TTL Blocking
Commit 85310015 authored by Theodor-Adrian Stana's avatar Theodor-Adrian Stana
Browse files
Options

doc: updated userguide 

- access cards via SNMP
- multiboot.py now reads raw binary files rather than the text files
  generated via the Micron flash bitstream generator
Signed-off-by: Theodor-Adrian Stana's avatarTheodor Stana <t.stana@cern.ch>
parent 7a090e58
Hide whitespace changes
Inline Side-by-side
Showing with 334 additions and 46 deletions
doc/userguide/cern-title.tex
View file @ 85310015
......@@ -9,7 +9,7 @@
\noindent \rule{\textwidth}{.1cm}
\hfill December 23, 2013
\hfill January 10, 2013
\vspace*{3cm}
......
doc/userguide/fig/oid.svg 0 → 100644
View file @ 85310015
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="860.25195"
height="160.24791"
id="svg2"
version="1.1"
inkscape:version="0.48.3.1 r9886"
sodipodi:docname="oid.svg">
<defs
id="defs4">
<marker
inkscape:stockid="TriangleOutL"
orient="auto"
refY="0"
refX="0"
id="TriangleOutL"
style="overflow:visible">
<path
id="path3939"
d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
transform="scale(0.8,0.8)"
inkscape:connector-curvature="0" />
</marker>
<marker
inkscape:stockid="TriangleOutM"
orient="auto"
refY="0"
refX="0"
id="TriangleOutM"
style="overflow:visible">
<path
id="path3942"
d="m 5.77,0 -8.65,5 0,-10 8.65,5 z"
style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt"
transform="scale(0.4,0.4)"
inkscape:connector-curvature="0" />
</marker>
</defs>
<sodipodi:namedview
id="base"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:pageopacity="0.0"
inkscape:pageshadow="2"
inkscape:zoom="1.4"
inkscape:cx="420.14108"
inkscape:cy="-125.21966"
inkscape:document-units="px"
inkscape:current-layer="layer1"
showgrid="true"
showguides="true"
inkscape:guide-bbox="true"
inkscape:window-width="1855"
inkscape:window-height="1176"
inkscape:window-x="65"
inkscape:window-y="24"
inkscape:window-maximized="1"
fit-margin-top="0"
fit-margin-left="0"
fit-margin-right="0"
fit-margin-bottom="0">
<inkscape:grid
type="xygrid"
id="grid2985"
empspacing="5"
visible="true"
enabled="true"
snapvisiblegridlinesonly="true"
units="mm"
spacingx="0.5mm"
spacingy="0.5mm"
originx="-2.3588888mm"
originy="-241.636mm" />
</sodipodi:namedview>
<metadata
id="metadata7">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title />
</cc:Work>
</rdf:RDF>
</metadata>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(-8.3582682,-35.923687)">
<text
xml:space="preserve"
style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
x="19.119011"
y="130.45163"
id="text2987"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan2989"
x="19.119011"
y="130.45163"
style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-family:Courier New;-inkscape-font-specification:Courier New"><tspan
style="fill:#000000;fill-opacity:0.29411765"
id="tspan3775">iso.3.6.1.4.1.37968.1.1.8</tspan>.2.<tspan
style="fill:#000000;fill-opacity:0.29411765"
id="tspan3759">2.1.2</tspan>.1</tspan></text>
<path
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#TriangleOutL)"
d="m 653.74016,139.9606 0,44.29135 -49.6063,0"
id="path3791"
inkscape:connector-curvature="0"
sodipodi:nodetypes="ccc" />
<text
xml:space="preserve"
style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
x="584.64569"
y="195.71848"
id="text4421"
sodipodi:linespacing="125%"><tspan
sodipodi:role="line"
id="tspan4423"
x="584.64569"
y="195.71848"
style="font-size:32px;text-align:end;text-anchor:end">slot number</tspan></text>
<path
inkscape:connector-curvature="0"
id="path4425"
d="m 845.07874,95.669257 0,-44.291339 -242.71654,0"
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#TriangleOutL)"
sodipodi:nodetypes="ccc" />
<text
sodipodi:linespacing="125%"
id="text4427"
y="60.236187"
x="585.91522"
style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
xml:space="preserve"><tspan
y="60.236187"
x="585.91522"
id="tspan4429"
sodipodi:role="line"
style="font-size:32px;text-align:end;text-anchor:end">register index</tspan></text>
<rect
style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
id="rect2997"
width="859.25195"
height="44.291336"
x="-11.358268"
y="65.823677"
transform="translate(20.216536,29.845562)" />
</g>
</svg>
doc/userguide/userguide-conv-ttl-blo.bib
View file @ 85310015
......@@ -90,3 +90,11 @@
note = {v2.5},
howpublished = {\url{http://www.xilinx.com/support/documentation/user_guides/ug380.pdf}}
}
@misc{ctb-fw-releases,
title = {{CONV-TTL-BLO firmware releases webpage on OHWR}},
month = jan,
year = {2014},
howpublished = {\url{http://www.ohwr.org/projects/conv-ttl-blo-gw/wiki/Releases}}
}
doc/userguide/userguide-conv-ttl-blo.tex
View file @ 85310015
......@@ -58,6 +58,7 @@
26-07-2013 & 1.03 & Added additional documentation subsection \\
05-08-2013 & 1.04 & Memory map is now appendix \\
23-12-2013 & 1.05 & Added remote reprogramming support \\
10-01-2014 & 1.06 & Added SNMP access sub-section \\
\hline
\end{tabular}
}
......@@ -77,9 +78,12 @@
\begin{tabular}{l l}
FPGA & Field-Programmable Gate Array \\
I$^2$C & Inter-Integrated Circuit \\
MIB & Management Information Base \\
OID & Object identifier (in the sense of SNMP) \\
PG & Pulse Generator \\
RTM & Rear Transition Module \\
SFP & Small Form-factor Pluggable (connector) \\
SNMP & Simple Network Management Protocol \\
VME & VERSAmodule Eurocard \\
\end{tabular}
......@@ -586,10 +590,24 @@ lines on the VME P1 connector (\textit{SERCLK}, \textit{SERDAT}).
By this protocol, 2$^{12}$ (12 address bits) 32-bit registers can be read from or written
to byte by byte. A complete memory map for accessible registers can be found in Appendix~\ref{app:memmap}.
The user accesses the VME crate using Telnet and sends commands which the ELMA SysMon board
translates to I$^2$C transfers to the board. Three telnet commands (see Table~\ref{tbl:cmds})
can be used to transfer data to the board. As their names suggest, \textit{readreg} reads a board
register, whereas \textit{writereg} and \textit{writemregs} write to a board register.
The user can access the CONV-TTL-BLO registers via either Telnet or SNMP. First, a connection
is made to the VME crate using either of these two protocols. Then, based on the protocol, commands
are sent via Telnet, or SNMP-specific object identifiers (OID) in the case of SNMP. Both
of these means of connecting to the CONV-TTL-BLO are described in the following subsections.
All the examples below were tried on a Ubuntu Linux computer.
%%--------------------------------------------------------------------------------------
%% SUBSEC: Telnet
%%--------------------------------------------------------------------------------------
\subsection{Telnet}
\label{sec:comm-telnet}
The first method to access registers on the CONV-TTL-BLO via the I$^2$C interface is via
a command-line based interface. This can be accessed via Telnet, through which commands
can be sent. Three Telnet commands (see Table~\ref{tbl:cmds}) can be used to transfer
data to the board. As names suggest, \textit{readreg} reads a board register, whereas
\textit{writereg} and \textit{writemregs} write to a board register.
\begin{table}[h]
\caption{Telnet commands to read and write registers}
......@@ -629,7 +647,7 @@ password:**********
%>
\end{verbatim}
First, a telnet connection is made with the crate, after which the \textit{readreg} command is issued
First, a Telnet connection is made with the crate, after which the \textit{readreg} command is issued
to read the value of address 0. The value of the register can be confirmed to be
the hex value of the ASCII string \textbf{TBLO}, so the board is indeed present in the slot.
......@@ -647,10 +665,11 @@ password:**********
%>
\end{verbatim}
Finally, to further illustrate how to use the the Telnet command line, an example of writing the value
\textbf{0xabcde} to a register at address \textbf{0x1c4} of a board in VME slot 11 and then reading
it back to check for correct write is given below. Note that this example does not normally yield
a similar result if performed on the CONV-TTL-BLO.
An example of writing the value \textbf{0xabcde} to a register at address \textbf{0x1c4} of
a board in VME slot 11 and then reading it back to check for correct write is given below.
Note that this example does not normally yield a similar result if performed on the
CONV-TTL-BLO, since even if a register is implemented at address \textbf{0x1c4},
it may be that not all of its bits are writable.
\begin{verbatim}
Connected to some-crate.cern.ch.
......@@ -663,6 +682,75 @@ password:**********
Read Data: 000ABCDE
\end{verbatim}
%------------------------------------------------------------------------------
% SUBSEC: SNMP
%------------------------------------------------------------------------------
\pagebreak
\subsection{SNMP}
\label{sec:comm-snmp}
The second method to access the CONV-TTL-BLO board is via the Simple Network
Management Protocol (SNMP). ELMA crates offer an Management Information Base (MIB)
which provide access to various information such as voltage and current sensor
readout, fan speeds and information about VME slots. Among the information about
the VME slots one can access register values for both read and write.
In order to access the registers, SNMP \textit{Get} and \textit{Set} requests
should be sent to a specific OID. The OID, apart from the ELMA enterprise
identifier and other OIDs to parse the MIB object tree, the VME slot number and
register indexes that translate to specific register addresses on the board.
An example of retrieving the CONV-TTL-BLO board ID from a card placed into the same
\textit{some-crate} in slot 2 is given below.
Note that in this and other examples the backslash is not needed, it is just added
here for formatting reasons and to keep to the rules of the Linux command-line.
\begin{verbatim}
%> snmpget -v2c -c public some-crate \
iso.3.6.1.4.1.37968.1.1.8.2.2.1.2.1
iso.3.6.1.4.1.37968.1.1.8.2.2.1.2.1 = STRING: "54424C4F"
\end{verbatim}
Here, the \textit{snmpget} command is used with a version 2c SNMP protocol (the
\textit{-v} parameter) and using the public community string (the -c parameter).
The OID (the last parameter of the \textit{snmpget command}) contains multiple
values that inform the MIB compiler how to parse the MIB object tree. Of these
values, only two are relevant to the user. These values are presented in
Figure~\ref{fig:oid}.
\begin{figure}[h]
\centerline{\includegraphics[width=\textwidth]{fig/oid}}
\caption{Relevant figures in the SNMP OID}
\label{fig:oid}
\end{figure}
To obtain register index values from register addresses as specified in
Appendix~\ref{app:memmap}, the following formula should be used:
\begin{center}
$reg. index = \frac{addr}{4} + 1$
\end{center}
To perform a write to a register via SNMP, the admin password of the crate
should be known.
An example of writing the value \textbf{0xabcde} to a register
at address \textbf{0x1c4} of a board in VME slot 11 and then reading it back to
check for correct write is given below. Note that this example does not normally
yield a similar result if performed on the CONV-TTL-BLO, since even if a register
is implemented at address \textbf{0x1c4}, it may be that not all of its bits are
writable.
\begin{verbatim}
%> snmpset -v2c -c admin-password some-crate \
iso.3.6.1.4.1.37968.1.1.8.11.2.1.2.114 s abcde
iso.3.6.1.4.1.37968.1.1.8.2.2.1.2.114 = STRING: "abcde"
%> snmpget -v2c -c public some-crate \
iso.3.6.1.4.1.37968.1.1.8.11.2.1.2.114
iso.3.6.1.4.1.37968.1.1.8.2.2.1.2.114 = STRING: "000ABCDE"
\end{verbatim}
%------------------------------------------------------------------------------
% SUBSEC: Remote reset
%------------------------------------------------------------------------------
......@@ -671,8 +759,10 @@ password:**********
The user can remotely reset the FPGA logic inside the CONV-TTL-BLO by writing to
the board's control register at address 0x8 (see Appendix~\ref{app:memmap-csr})
to first unlock the RST bit and then write it high to initiate the reset. An
example of resetting a card in slot 11 is given below.
to first unlock the RST bit and then write it high to initiate the reset. When the
reset is initiated, a 100~ms reset pulse is applied to the logic.
An example of resetting a card in slot 11 using the Telnet commands is given below.
\begin{verbatim}
%>writereg 11 8 1
......@@ -682,14 +772,29 @@ example of resetting a card in slot 11 is given below.
\end{verbatim}
A remote reset will also reset the I$^2$C interface logic, hence the
\textit{Not acknowledged} response above. The reset period is 100~ms, after which
all FPGA logic will be reset and the user will be able to communicate
to the CONV-TTL-BLO board again.
\textit{Not acknowledged} response above. After the reset period of 100~ms, during
which all FPGA logic is reset, the user will be able to communicate to the
CONV-TTL-BLO board again.
Using SNMP, the commands outlined below should be issued to reset the card. Note that
the reply in the case of \textit{snmpset} is not as in the case of the Telnet
commands.
\begin{verbatim}
%> snmpset -v2c -c admin-password some-crate \
iso.3.6.1.4.1.37968.1.1.8.2.2.1.2.3 s 1
iso.3.6.1.4.1.37968.1.1.8.2.2.1.2.3 = STRING: "1"
%> snmpset -v2c -c admin-password some-crate \
iso.3.6.1.4.1.37968.1.1.8.2.2.1.2.3 s 2
iso.3.6.1.4.1.37968.1.1.8.2.2.1.2.3 = STRING: "2"
\end{verbatim}
Note that the backslash in the command above is not needed, it is just added
here for formatting reasons and to keep to the rules of the Linux command-line.
%==============================================================================
% SEC: Remote reprog
%==============================================================================
\pagebreak
\section{Remote reprogramming support}
\label{sec:reprog}
......@@ -838,13 +943,14 @@ is given in the datasheet of the flash chip~\cite{m25p32}.
\subsection{The \textit{multiboot.py} script}
\label{sec:reprog-example-script}
An example Python script is provided to access the MultiBoot logic on the CONV-TTL-BLO. The
script can be found under the \textit{test/multiboot/} folder in the project
repository~\cite{ctb-repo}. The script implements the workflow in Table~\ref{tbl:reprog-workflow}
and can be used either as \textit{the} means of remotely reprogramming the Flash chip, or as
an example for the users to write their own tools.
An example Python script is provided to access the MultiBoot logic on the CONV-TTL-BLO.
The script can be found under the \textit{software/multiboot/} folder in the project
repository~\cite{ctb-repo}. The script implements the workflow in
Table~\ref{tbl:reprog-workflow} and can be used either as \textit{the} means of remotely
reprogramming the flash chip, or as an example for users to write their own tools.
Table~\ref{tbl:reprog-scripts} shows the files in the \textit{test/} repository folder needed to run the script.
Table~\ref{tbl:reprog-scripts} shows the files in the \textit{software/} repository folder
needed to run the script.
\begin{table}[h]
\caption{Scripts needed for remote reprogramming}
......@@ -856,9 +962,9 @@ Table~\ref{tbl:reprog-scripts} shows the files in the \textit{test/} repository
\hline
multiboot/multiboot.py & Communicates to the MultiBoot module to send the bitstream
and issue the IPROG command \\
vbcp/vbcp.py & Defines the I$^2$C class, containing methods implementing the
the I$^2$C protocol to access the cards \\
vbcp/vbcpexcept.py & Contains exceptions thrown by the I$^2$C class when the response
ei2c/ei2c.py & Defines the I$^2$C class, containing methods implementing the
the I$^2$C protocol to access the cards \\
ei2c/ei2cexcept.py & Contains exceptions thrown by the I$^2$C class when the response
from the ELMA crate yields an error \\
\hline
\end{tabular}
......@@ -871,36 +977,38 @@ giving the user access to the following:
\begin{itemize}
\item Readout of FPGA configuration register values (see the Configuration Registers
section in \cite{ug380} and the \textit{xil\_multiboot} module documentation)
\item Reading the first page of the flash starting with an address input by the user
\item Writing a bitstream to the M25P32 flash chip
\item Sending the IPROG command
\end{itemize}
The first item in this list is outside the scope of this document. We shall therefore
skip to the second, writing the bitstream to the flash chip.
Upon running the script, the user is asked in sequence for these actions. Since reading
the FPGA configuration register is an advanced feature, the first item in this list is
outside the scope of this document.
The \textit{multiboot.py} script will ask for a bitstream input file. This file is a simple
text file in which each line contains 512 ASCII characters, two for each of the 256 bytes
in a flash page. The input file is generated using the binary conversion tool from Micron.
This tool (called \textit{converter1.1.exe}) can be found by first downloading the M25P64
flash memory model:
If the user selects to read the first page of the flash chip at the MultiBoot address,
a contiguous list of hexadecimal values corresponding to the page will be returned. The
MultiBoot address will be given later in the script.
\url{http://cern.ch/go/xl8m}
Since writing the bitstream file takes a long time, the user is asked twice whether to write
a bitstream to the flash or not.
\noindent and navigating to the \textit{code/} folder. The tool can be run under Linux using
Wine.
After the user selects whether to send the IPROG command to the logic, the MultiBoot start
address is given. Note that this value should be given in hexadecimal; it is recommended
to use the values in Table~\ref{tbl:reprog-flash-memmap}.
After inputting the name of the bitstream text file, the \textit{multiboot.py}
script asks whether the IPROG command should be issued after the bitstream is written.
After that, the addresses of both the MultiBoot and Golden bitstreams are requested from
the user. It is advised to input the addresses listed in Table~\ref{tbl:reprog-flash-memmap}.
After inputting the start address of the bitstream, the name of the bitstream file to program
is given. The script accepts any type of raw binary files as input, but it is recommended to use
\textit{.bin} files. It is also recommended to place the binary file in the same location as the
\textit{multiboot.py} script.
Once the addresses have been input to the \textit{multiboot.py} script, it will start
the process of writing to the flash and after that is finished, if the user selected it,
the script will issue the IPROG command, triggering the reprogramming of the flash. Correct
reprogramming is checked by checking the version of the firmware from the SR.
Once the file name has been input to and checked by the \textit{multiboot.py} script,
it will start the process of writing to the flash and after that is finished, if the user
selected it, the script will issue the IPROG command, triggering the reprogramming of the
flash. Correct reprogramming is validated by checking the version of the firmware from the SR.
A full bitstream write to the flash chip via I$^2$C using \textit{multiboot.py} will take
at least twelve minutes. This interval may increase, depending on network status and
at least eleven minutes. This interval may increase, depending on network status and
operating system the script is run on.
%--------------------------------------------------------------------------------------
......@@ -926,7 +1034,8 @@ MultiBoot-enabled design.
\label{sec:reprog-fwstat}
CONV-TTL-BLO boards arrive with the Header and Golden bitstreams, along with bitstream
version 2.01 programmed into the flash.
version 1.0 (see the bitstream releases webpage~\cite{ctb-fw-releases} for more details)
programmed into the flash.
%======================================================================================
% Appendices
......@@ -1033,6 +1142,13 @@ The inverter channel will add a 30~ns delay to the input TTL signal.
Table~\ref{tbl:memmap} shows the complete memory map of the firmware. The
following sections list the memory map of each peripheral.
In order to convert address values to register index values for SNMP access,
the following formula should be used:
\begin{center}
$reg. index = \frac{addr}{4} + 1$
\end{center}
\begin{table}[h]
\caption{CONV-TTL-BLO memory map}
\label{tbl:memmap}
......@@ -1107,7 +1223,7 @@ following sections list the memory map of each peripheral.
-- rightmost nibble \textit{hex value} is minor release \textit{decimal value} \newline
e.g. \newline
0x11 -- v1.1\newline
0x1e -- v1.15 \newline
0x1e -- v1.14 \newline
0x20 -- v2.0 \newline
etc. \\
SWITCHES & Current switch status \newline
......
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