Commit 330aa383 authored by Alessandro Rubini's avatar Alessandro Rubini

docs: added example to specification

parent e2cc31ef
......@@ -837,4 +837,111 @@ The value \textbf{must} point to an SDB array that begins with an \textit{interc
An embedded component info structure, where the type is 0x01 See Table \ref{sdb_component}.
\end{description}
\section{A Simple Real-World Example}
This section shows the simplest real-world example of an SDB array.
The FPGA binary used as an example is the \textit{boot} image to be
programmed in the SPEC cards
(\texttt{http://www.ohwr.org/projects/spec}); it only includes the
\textit{syscon} device, which allows generic access to the FMC
mezzanine card.
\subsection{Binary Data}
The following binary dump appears at offset 0x100 of the memory window
that maps to the programmable device:
\footnotesize
\begin{verbatim}
000000 53 44 42 2d 00 02 01 00 00 00 00 00 00 00 00 00 >SDB-............<
000010 00 00 00 00 00 00 01 ff 00 00 00 00 00 00 06 51 >...............Q<
000020 e6 a5 42 c9 00 00 00 02 20 12 05 11 57 42 34 2d >..B..... ...WB4-<
000030 43 72 6f 73 73 62 61 72 2d 47 53 49 20 20 20 00 >Crossbar-GSI .<
000040 00 00 01 01 00 00 00 07 00 00 00 00 00 00 00 00 >................<
000050 00 00 00 00 00 00 00 ff 00 00 00 00 00 00 ce 42 >...............B<
000060 ff 07 fc 47 00 00 00 01 20 12 03 05 57 52 2d 50 >...G.... ...WR-P<
000070 65 72 69 70 68 2d 53 79 73 63 6f 6e 20 20 20 01 >eriph-Syscon .<
\end{verbatim}
\normalsize
\subsection{Parsing the Data}
This is the suggested parsing sequence for the data shown above. The
parsing code is assumed to know where the data structure is expected to live.
\begin{itemize}
\item The parser verifies the magic number 0x5344422D at offset 0.
\item The type byte of 0x00 at offset 0x3f confirms this is an \textit{interconnect} record.
\item The SDB version, at offset 6, confirms this is version 1 and we can parse it.
\item By reading the 16-bit field at position 04-05, we know this is an array of two items.
\item The second item is of type \textit{device} (type 0x01).
\end{itemize}
What follows is the split-out view of the two structures:
\footnotesize
\begin{verbatim}
Interconnect:
0x00: 53 44 42 2d (Magic "SDB-")
0x04: 00 02 (Number of records)
0x06: 01 (SDB version)
0x07: 00 (Bus type: wishbone)
0x08: 00 00 00 00 00 00 00 00 (First address)
0x10: 00 00 00 00 00 00 01 ff (Last address)
0x18: 00 00 00 00 00 00 06 51 (Vendor: GSI)
0x20: e6 a5 42 c9 (Device)
0x24: 00 00 00 02 (Version)
0x28: 20 12 05 11 (Date: 11th May 2012)
0x2c: "WB4-Crossbar-GSI " (Name)
0x3f: 00 (Type: interconnect)
Device:
0x00: 00 00 (ABI class)
0x02: 01 (ABI version major)
0x03: 01 (ABI version minor)
0x04: 00 00 00 07 (Bus-specific: BE, 8,16,32 bits)
0x08: 00 00 00 00 00 00 00 00 (First address)
0x10: 00 00 00 00 00 00 00 ff (Last address)
0x18: 00 00 00 00 00 00 ce 42 (Vendor: CERN)
0x20: ff 07 fc 47 (Device)
0x24: 00 00 00 01 (Version)
0x28: 20 12 03 05 (Date: 5th March 2012)
0x2c: "WR-Periph-Syscon " (Name)
0x3f: 01 (Type: device)
\end{verbatim}
\normalsize
The previous dump shows how the vendor identifiers in this case have
been allocated in the globally-assigned space, while device identifiers
are pseudo-random numbers, in charge of the respective vendor.
\subsection{Endianness Problems}
Please note that the host may have some issue reading the binary
dumps. According to how the bridge between the host and FPGA is
designed you may face one of the following situation:
\begin{itemize}
\item The host is big-endian (data is always correct).
\item The host is little-endian and the bridge is byte-oriented.
\item The host is little-endian and the bridge is word-oriented.
\end{itemize}
If the bridge is byte-oriented, i.e. each and every byte can be
independently addressed as such, then the usual endian conversion
rules apply (e.g. you can \textit{memcpy} and then access fields with
endian-aware code).
If the bridge it word-oriented, however, the behaviour is stranger, in
a way. After you copied the data to host memory (whether one byte at
a time or not), you'll find that within each word the bytes are
swapped. This happens because when the host reads the byte at offset
0, it requests bits 0..7, and the bridge returns the byte at offset 3,
which corresponds to those bits. If this is your case, you need to
byte-swap each 32-bit word before using the structure in a
little-endian host. After such swapping, the usual rules for
multi-byte values apply.
\end{document}
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