Skip to content

S
SDB - Self-describing Bus
Commit 8576e1d9 authored by Alessandro Rubini's avatar Alessandro Rubini
Browse files
Options

specification: added two more informative type 

This adds the "repo_url" and "synthesis" records, that are already
used in one of your projects.

Thanks to Matthieu Cattin for his help in designing the structures
and actually implementing them.
Signed-off-by: Alessandro Rubini's avatarAlessandro Rubini <rubini@gnudd.com>
parent 77f78d19
Hide whitespace changes
Inline Side-by-side
Showing with 163 additions and 9 deletions
docs/specification/sdb.h
View file @ 8576e1d9
/* /*
* This is a modified version 1.0 of sdb.h, not the official spec version * This is the proposed version 1.1 of sdb.h, still not official
*/ */
#ifndef __SDB_H__ #ifndef __SDB_H__
#define __SDB_H__ #define __SDB_H__
...@@ -47,11 +47,13 @@ struct sdb_component { ...@@ -47,11 +47,13 @@ struct sdb_component {
/* Type of the SDB record */ /* Type of the SDB record */
enum sdb_record_type { enum sdb_record_type {
sdb_type_interconnect = 0x00, sdb_type_interconnect = 0x00,
sdb_type_device = 0x01, sdb_type_device = 0x01,
sdb_type_bridge = 0x02, sdb_type_bridge = 0x02,
sdb_type_integration = 0x80, sdb_type_integration = 0x80,
sdb_type_empty = 0xFF, sdb_type_repo_url = 0x81,
sdb_type_synthesis = 0x82,
sdb_type_empty = 0xFF,
}; };
/* Type 0: interconnect (first of the array) /* Type 0: interconnect (first of the array)
...@@ -102,6 +104,29 @@ struct sdb_integration { ...@@ -102,6 +104,29 @@ struct sdb_integration {
struct sdb_product product; /* 0x08-0x3f */ struct sdb_product product; /* 0x08-0x3f */
}; };
/* Type 0x81: Top module repository url
*
* again, an informative field that software can ignore
*/
struct sdb_repo_url {
uint8_t repo_url[63]; /* 0x00-0x3e */
uint8_t record_type; /* 0x3f */
};
/* Type 0x82: Synthesis tool information
*
* this informative record
*/
struct sdb_synthesis {
uint8_t syn_name[16]; /* 0x00-0x0f */
uint8_t commit_id[16]; /* 0x10-0x1f */
uint8_t tool_name[8]; /* 0x20-0x27 */
uint32_t tool_version; /* 0x28-0x2b */
uint32_t date; /* 0x2c-0x2f */
uint8_t user_name[15]; /* 0x30-0x3e */
uint8_t record_type; /* 0x3f */
};
/* Type 0xff: empty /* Type 0xff: empty
* *
* this allows keeping empty slots during development, * this allows keeping empty slots during development,
......
docs/specification/sdb.tex
View file @ 8576e1d9
...@@ -646,8 +646,10 @@ unknown record type in the range 0x00-0x7f is found; unknown records in the rang ...@@ -646,8 +646,10 @@ unknown record type in the range 0x00-0x7f is found; unknown records in the rang
sdb\_type\_bridge & 0x02 & Bridge to a sub-bus \\ \hline sdb\_type\_bridge & 0x02 & Bridge to a sub-bus \\ \hline
& 0x03-0x6f & Reserved for future types \\ \hline & 0x03-0x6f & Reserved for future types \\ \hline
& 0x70-0x7f & Local/temporary use \\ \hline & 0x70-0x7f & Local/temporary use \\ \hline
sdb\_type\_integration & 0x80 & Informative integration structure \\ \hline sdb\_type\_integration & 0x80 & Informative: integration structure \\ \hline
& 0x81-0xef & Reserved for future informative records \\ \hline sdb\_type\_repo\_url & 0x81 & Informative: repository location \\ \hline
sdb\_type\_synthesis & 0x80 & Informative: synthesis details \\ \hline
& 0x83-0xef & Reserved for future informative records \\ \hline
& 0xf0-0xfef & Local/temporary use \\ \hline & 0xf0-0xfef & Local/temporary use \\ \hline
sdb\_type\_empty & 0xFF & Empty record \\ \hline sdb\_type\_empty & 0xFF & Empty record \\ \hline
\end{tabular} \end{tabular}
...@@ -887,7 +889,7 @@ For example, consider ...@@ -887,7 +889,7 @@ For example, consider
a manufacturer that takes components from various vendors and combines them with a standard bus a manufacturer that takes components from various vendors and combines them with a standard bus
interconnect. This aggregate product can be described by an SDB integration record, claiming interconnect. This aggregate product can be described by an SDB integration record, claiming
a vendor ID, the release date and the other \textit{product} information. a vendor ID, the release date and the other \textit{product} information.
The integrator record is is described in Table \ref{sdb_integrator}. The integration record is is described in Table \ref{sdb_integrator}.
\begin{figure}[h] \begin{figure}[h]
\centering% \centering%
...@@ -920,6 +922,133 @@ This is the \textit{product} structure described in Table \ref{sdb_product}. The ...@@ -920,6 +922,133 @@ This is the \textit{product} structure described in Table \ref{sdb_product}. The
record type for an integration record is 0x80. record type for an integration record is 0x80.
\end{description} \end{description}
\subsubsection{Repository-Url Record}
This record is not a \textit{product}; it is laid out as a simple 63-byte string
that reports the URL of the repository used to driver this synthesis.
This record is optional like all other informational structures, but we think it's
useful for designers to have a standardized way to allow tracing the design.
Actually, this data structure is already implemented in one ADC design.
\begin{figure}[h]
\centering%
\includegraphics[width=100mm]{img/sdb-url.ps}
\caption{The Repository-Url Structure}
\label{fig:FigureUrl}
\end{figure}
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{SDB Repository-Url Record (64 bytes, type 0x81)}\label{sdb_url}\centering
\begin{tabular}{| c | c | c | l | c | p{5cm} |} \hline
First & Last & Size & Name & Value & Description \\ \hline
0x00 & 0x3e & 63 & repo\_url & - & Repository for this design \\ \hline
0x3f & 0x3f & 1 & record\_type & 0x81 & Type of this record \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\begin{description}
\item[repo\_url] \hfill \\
This a string, encoded in UTF-8, with trailing spaces and no terminating 0.
It is expected to name the top-level repository
used to build this design, as a \texttt{git://} or \texttt{http://} form or
anything appropriate for the revision control system being used.
\item[record\_type] \hfill \\
The record type for this structures is 0x81.
\end{description}
\subsubsection{Synthesis Record}
This record, like the previous one, is not a \textit{product}.
This record is optional like all other informational structures, but it reveals
useful to provide information about the specific synthesis in a known format.
Not all designers want to provide such detailed information, but when they
do they \textbf{should} use this format.
Please note that the information in this record is pretty volatile, as
it represents the actual synthesis; if the record is used, developers
must be careful to update (or remove) it when they rebuild the
project. Even though the information may seem too detailed, sometimes
such high-precision tracking is actually needed in practice; all
unused fields can be left empty, but all used fields should be updated
with great care (otherwise, the would-be detailed tracking of builds just collapses).
\begin{figure}[h]
\centering%
\includegraphics[width=100mm]{img/sdb-synthesis.ps}
\caption{The Synthesis Structure}
\label{fig:FigureSynthesis}
\end{figure}
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{SDB Synthesis Record (64 bytes, type 0x82)}\label{sdb_synthesis}\centering
\begin{tabular}{| c | c | c | l | c | p{5cm} |} \hline
First & Last & Size & Name & Value & Description \\ \hline
0x00 & 0x0f & 16 & syn\_name & - & Name of this project/synthesis \\ \hline
0x10 & 0x1f & 16 & commit\_id & - & Identifier of the build commit \\ \hline
0x20 & 0x27 & 8 & tool\_name & - & Name of the synthesis tool \\ \hline
0x28 & 0x2b & 4 & tool\_version & - & Version of the synthesis tool \\ \hline
0x2c & 0x2f & 4 & date & - & Date of synthesis \\ \hline
0x30 & 0x3e & 15 & user\_name & - & Name of the user who did the synthesis \\ \hline
0x3f & 0x3f & 1 & record\_type & 0x82 & Type of this record \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\begin{description}
\item[syn\_name] \hfill \\
This a string, encoded in UTF-8, with trailing spaces and no terminating 0;
it should represent a human-readable name for this synthesis. Like all other
fields in this structures, it is meant to be useful for the designers, to help
tracking what is currently installed in the various systems. Thus, this may
be a generic name of the project or a more specific string, according to local
needs.
\item[commit\_id] \hfill \\
This field represents the binary identifier of the top-level commit used
to build this gateware image. If the identifier is more than 128 bits long
(e.g., \textit{git}), the field includes the leading bits. If the commit ID is numeric
(e.g., SVN), the representation is bit-endian binary. For repositories using
non-binary version numbers, the representation is let to the ingenuity of the
developer, to properly convey the informations. For example, a CVS version
like ``1.20.1.4'' can either be ASCII-encoded or represented as 4 32-bit big-endian
fields. Clearly, the commit\_id field raises a ``chicken-and-egg'' problem: once
you commit the change, your commit identifier changes, maybe in unpredictable
ways. Representing the ``previous'' commit, and then committing and sdb-only
change is a sensible workaround. The filed \textbf{should} be 0 if not used.
\item[tool\_name] \hfill \\
This a string, encoded in UTF-8, with trailing spaces and no terminating 0;
it represents a human-readable name for the synthesis tool used to build this
very binary gateware file.
\item[tool\_version] \hfill \\
The version of the synthesis tool, in a human-readable way. For example,
it can be used as two 16-bit fields, but this really depends on how the specific
tool names its versions.
\item[date] \hfill \\
The date of synthesis. This \textbf{must} be either 0 (unspecified) or a 32-bit hex
format number in the format 0xYYYYMMDD. For example, 0x20130327.
\item[user\_name] \hfill \\
This a string, encoded in UTF-8, with trailing spaces and no terminating 0;
it states who is the user who built the binary gateware. This name is expected
to be unique among the development group, so a Unix username or a nickname are good
choices that fit the allowed space of 15 bytes.
\item[record\_type] \hfill \\
The record type for this structures is 0x82.
\end{description}
\section{Simple Real-World Examples} \section{Simple Real-World Examples}
This section shows the details of the simplest real-world example of an SDB array, This section shows the details of the simplest real-world example of an SDB array,
......
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