Skip to content
Snippets Groups Projects
Commit 0c8f8b7a authored by Alessandro Rubini's avatar Alessandro Rubini
Browse files

Merge branch 'rubi'

parents 1036ae92 58e3aaec
Branches
Tags
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/specification/.gitignore 0 → 100644
+ 1
− 0
View file @ 0c8f8b7a
sdb-h.expand
docs/specification/Makefile
+ 10
− 6
View file @ 0c8f8b7a
FILE=sdwb
INPUT = $(wildcard *.tex)
ALL = $(INPUT:.tex=.pdf)
all: $(FILE).pdf
all: $(ALL)
$(FILE).pdf: $(FILE).tex
latex $(FILE).tex
latex $(FILE).tex
dvipdfm $(FILE).dvi
%.pdf: %.tex sdb-h.expand
latex $*.tex
latex $*.tex
dvipdfm $*.dvi
clean:
rm -rf *.aux *.dvi *.log *.pdf *.toc *.lot *.lof
sdb-h.expand: sdb.h
expand -8 $^ > $@
docs/specification/sdb.h 0 → 100644
+ 119
− 0
View file @ 0c8f8b7a
#include <stdint.h>
/*
* All structures are 64 bytes long and are expected
* to live in an array, one for each interconnect.
* Most fields of the structures are shared among the
* various types, and most-specific fields are at the
* beginning (for alignment reasons, and to keep the
* magic number at the head of the interconnect record
*/
/* Product, 40 bytes at offset 24, 8-byte alignmed
*
* device_id is vendor-assigned; version is device-specific,
* date is hex (e.g 0x20120501), name is UTF-8, blank-filled
* and not terminated with a 0 byte.
*/
struct sdb_product {
uint64_t vendor_id; /* 0x18..0x1f */
uint32_t device_id; /* 0x20..0x23 */
uint32_t version; /* 0x24..0x27 */
uint32_t date; /* 0x28..0x2b */
uint8_t name[19]; /* 0x2c..0x3e */
uint8_t record_type; /* 0x3f */
};
/*
* Component, 56 bytes at offset 8, 8-byte aligned
*
* The address range is first to last, inclusive
* (for example 0x100000 - 0x10ffff)
*/
struct sdb_component {
uint64_t addr_first; /* 0x08..0x0f */
uint64_t addr_last; /* 0x10..0x17 */
struct sdb_product product; /* 0x18..0x3f */
};
/* Type of the SDB record */
enum sdb_record_type {
sdb_type_interconnect = 0x00,
sdb_type_device = 0x01,
sdb_type_bridge = 0x02,
sdb_type_integration = 0x80,
sdb_type_empty = 0xFF,
};
/* Type 0: interconnect (first of the array)
*
* magic ix 0x5344422d, sdb_records is the length of the table
* including this first record, version is 1. The bus type
* is enumerated later.
*/
struct sdb_interconnect {
uint32_t sdb_magic; /* 0x00-0x03 */
uint16_t sdb_records; /* 0x04-0x05 */
uint8_t sdb_version; /* 0x06 */
uint8_t sdb_bus_type; /* 0x07 */
struct sdb_component sdb_component; /* 0x08-0x3f */
};
/* Type 1: device
*
* class is 0 for "custom device", other values are
* to be standardized; ABI version is for the driver,
* bus-specific bits are defined by each bus (see below)
*/
struct sdb_device {
uint16_t abi_class; /* 0x00-0x01 */
uint8_t abi_ver_major; /* 0x02 */
uint8_t abi_ver_minor; /* 0x03 */
uint32_t bus_specific; /* 0x04-0x07 */
struct sdb_component sdb_component; /* 0x08-0x3f */
};
/* Type 2: bridge
*
* child is the address of the nested SDB table
*/
struct sdb_bridge {
uint64_t sdb_child; /* 0x00-0x07 */
struct sdb_component sdb_component; /* 0x08-0x3f */
};
/* Type 0x80: integration
*
* all types with by 7 set are meta-information, so
* software can ignore the types it doesn't know. Here we
* just provide product information for an aggregate device
*/
struct sdb_integration {
uint8_t reserved[24]; /* 0x00-0x17 */
struct sdb_product product; /* 0x08-0x3f */
};
/* Type 0xff: empty
*
* this allows keeping empty slots during development,
* so they can be filled later with miminal efforts and
* no misleading description is ever shipped -- hopefully.
* It can also be used to pad a table to a desired length.
*/
struct sdb_empty {
uint8_t reserved[63]; /* 0x00-0x3e */
uint8_t record_type; /* 0x3f */
};
/* The type of bus, for bus-specific flags (currently only Wishbone) */
enum sdb_bus_type {
sdb_wishbone = 0x00
};
#define SDB_WB_WIDTH_MASK 0x0f
#define SDB_WB_ACCESS8 0x01
#define SDB_WB_ACCESS16 0x02
#define SDB_WB_ACCESS32 0x04
#define SDB_WB_ACCESS64 0x08
#define SDB_WB_LITTLE_ENDIAN 0x80
docs/specification/sdb.tex 0 → 100644
+ 840
− 0
View file @ 0c8f8b7a
\documentclass[a4paper, 12pt]{article}
\usepackage{draftwatermark}
\usepackage{changepage}
%\usepackage{fullpage}
\usepackage{color}
\usepackage{xcolor}
\usepackage{listings}
\usepackage{array}
\usepackage{multirow}
\usepackage{footnote}
\usepackage{graphicx}
\usepackage{verbatim}
\SetWatermarkScale{4}
\SetWatermarkText{}
\SetWatermarkLightness{0.9}
\usepackage{caption}
\DeclareCaptionFont{white}{\color{white}}
\DeclareCaptionFormat{listing}{\colorbox{gray}{\parbox{\textwidth}{#1#2#3}}}
\captionsetup[lstlisting]{format=listing,labelfont=white,textfont=white}
\lstset{
tabsize=4,
basicstyle=\footnotesize,
columns=fixed,
}
\parindent0pt
\parskip10pt
\makesavenoteenv{tabular}
\title{Self-Describing Bus (SDB) Specification\\
for Logic Cores}
\author{Alessandro Rubini (Consultant for CERN)\\
Wesley Terpstra (GSI),\\
Manohar Vanga (CERN, BE/CO/HT)}
\date{June 21th 2012}
\begin{document}
\maketitle
\tableofcontents
\listoftables
%\listoffigures
\pagebreak
\section*{Bugs}
This version of this document is still a draft (if it was software, it would be
between \textit{beta} and \textit{release candidate}).
This is a list of things that ought to be changed or added:
\begin{itemize}
\item We should clarify that in nested buses addresses are relative to the sub-bus;
\item The type description should get a more prominent place than the
current description in the \textit{product} structure;
\item We need a policy for designers adding class etc, and it must be described;
\item Wishbone-specific flags deserve a subsection;
\item Filesystem-specific flags must be defined and documented.
\end{itemize}
\section{Introduction}
This document describes a specification for a series of self description
structures that can be used to provide metadata about logic blocks. This metadata
should be provided by the logic cores, like PCI or USB description records,
so device drivers and other software can automatically discover the blocks and
configure them during runtime.
\subsection{History and Rationale}
The idea of a self-description for a bus appeared while working on
\textit{White Rabbit} and related projects that make massive use of
FPGA devices. Separately and concurrently, both the CERN and the GSI
working groups identified the need for some way to self-detect the
contents of a specific logic device after it is programmed.
We envisioned that if the internal FPGA bus could enumerate its own
content, we would get the following advantages:
\begin{itemize}
\item Run-time validation of FPGA binary images;
\item Easy matching of software and gateware;
\item Automatic handling of several binaries with the same software;
\item Feasibility of tools similar to \texttt{lspci} and \texttt{lsusb};
\item Automatic loading of kernel drivers on the host computer;
\item Automatic setup of low-level drivers within soft cores;
\item Better decoupling of gateware and software development.
\end{itemize}
As usual in engineering, we wanted a system that was as simple as possible,
yet open to future extensions without introducing compatibility issues.
While our internal bus is \textit{Wishbone}, we designed the structures
to be generic so other bus implementations may use them.
We are aware of the AMBA (PrimeCell) cell-id standard, but we think it
is seriously under-designed: the idea is sound, but a single cell-ID field
is not enough if we want to make sense of the whole bus. We think current
hardware and software resources allow a richer description of logic blocks.
We are also aware of the PCI and USB data structures, but they are
unsuitable for an FPGA, either. First of all, they assume devices are
enumerated by other means whereas we need to be able to scan a flat
address space; then, their vendor ID space is not wide enough to allow
small developers to easily participate.
This specification, thus, uses 64 bits for the vendor ID, to prevent scarcity.
The vendor space is split in two parts, and all users are free to bless their
own vendor number and start designing using these data structures,
provided the most-significant vendor-id bit is set.
We acknowledge the usefulness of a central vendor registry, so
the lower half of the
vendor-ID space is reserved for numbers that
are officially assigned and published. The vendor registry, however, is not
part of this specification, which just lists the first few vendor-ID values that
have already been used.
All multi-byte values are stored in \textit{big endian} order. We need
a well-defined endianness to allow generic scanning of the target bus;
we picked bigendian because most embedded devices are big endian and
because it is the format usually chosen by existing standards documents.
All data structures are 64 byte in size and they are all similar in their
internal layout; the last byte in the 64-byte slot identifies the type
of each structure, to allow very simple parsing code and easy extension
to new types of structures. The size is a power of two in order to
avoid multiplication and division in calculation of sizes, as the
driver may reside in a very simple soft-core.
\subsection{Scope of This Specification}
This specification documents the format used by CERN and GSI. However,
everyone is welcome to use the data structures defined in this
specification (or customized derivatives) in their own work.
Parts of this document are written in the language of
a formal specification because we need clear and sharp rules in
order to make different implementations interoperate. We are sticking
to those rules in our own implementations, both in gateware and in
associated software.
Everybody is free to choose a vendor-ID and start coding right now; we
suggest to pick a random 64 bit number and set the most significant
bit (as an alternative, you can paste the bit ``1'' in front of
a random 63 bit number).
If you want to implement your own data structures, similar to ours
but different in some way, please change the magic number, to avoid
headaches if both bus implementation are instantiated within the same host
computer or network.
\subsection{The Overall System Structure}
The bus described by the structures defined herein is set up as a
flat address space. Our initial target is the \textit{Wishbone} bus,
as used in our own FPGA projects, but the overall situation is
pretty general and can be applied to any bus or even a storage
system for quasi-static information in flash memory
To keep variety to a minimum, this standard defines the concept of
\textit{product}, which is anything that has been \textit{done}, and thus has
its own identifiers, name, version and date. This includes
meta-information, for example a record of the final build of the
FPGA binary.
Every \textit{product} that lives in some address range is called a
\textit{component}; as such it specifies its first and last address, both as
64 bit numbers.
Within the bus memory area, the address space available to bus masters
is usually decoded into several blocks using the high address bits, so
that the space is divided into several blocks, usually they are sized
as powers of two, but this is not mandatory -- some designers may use
individual address lines to select blocks, to easily get a sparsely
populated address space. The designer of the address demultiplexer
(the \textit{interconnect} block) is expected to describe the
logic blocks living behind the interconnect, as well as the
interconnect itself. Thus, the \textit{interconnect} is a \textit{component}
(so that it owns an address range), and the associated SDB record is the first
one of an array of structures; the other records on the array
defines the \textit{components} that are connected downstream of this multiplexer
and optionally more abstract \textit{products}.
Some of the blocks within the data space of an \textit{interconnect}
component can in turn be
bridges to other \textit{interconnect} components. Thus, the \textit{bridge}
component states the address where further self-description structures are to
be found. This allows nesting at arbitrary levels (too deep nesting is
not a good practice, but this specification is not limiting the
designer's ingenuity).
Only the bus designer knows where the outer-level data structure is to
be found, and such information is expected to be known by the ``bus
driver'' software package. For example, a soft-core scanning its own
bus will know where to start from, because it is part of the same
overall design; a PCI driver must know how to access internal bus
memory from a PCI memory window, so it can also know where the
SDB entry point is stored; an \textit{Etherbone} bus master will
comply to its own packet-format standard, so it can as well know
where to start enumerating the remote bus from.
We can therefore define the following terms to build the
self-description framework:
\begin{description}
\item[Product] \hfill \\
Every structure includes \textit{product} fields, i.e.
the vendor and device identifiers, version and date, and an UTF-8
name.
\item[Component] \hfill \\
A component is a \textit{product} with an associated address range. Its
structure lists the first and last valid addresses within
the encompassing address space and includes a \textit{product}
structure.
\item[Interconnect] \hfill \\
The \textit{interconnect} is a \textit{component} representing an address demultiplexer.
The associated data structure heads an array of \textit{product} descriptions;
its specific fields are magic number, bus type, version and the number of
structures in the array.
\item[Device] \hfill \\
The \textit{device} component identifies a peripheral block, with
its class, ABI version and bus-specific flags.
\item[Bridge] \hfill \\
The \textit{bridge} component marks a memory area leading to a lower-level
address demultiplexer (i.e. an \textit{interconnect}). Its data
structure declares the address where the self-description for the
sub-bus is to be found.
\item[Integration] \hfill \\
The optional \textit{integration} product describes an aggregate bus.
It is a \textit{product} record, not a
\textit{component}, in that it has no associated address range. This
meta-information item can be used by a vendor to describe
its particular combination of devices, interconnect, and address layout.
For example, if an expansion card uses a number of stock devices
combined with a stock interconnect, its driver can nonetheless recognize
the aggregate device by the integration record.
\item[Controller] \hfill \\
The \textit{controller} is a software abstraction, used in the host
computer driving the bus (if any). The controller defines the
methods to access its own bus and knows where the outer SDB
array is found. There is no controller concept for soft-cores
that self-scan their own address space.
\end{description}
\subsection{Current Implementations}
The self-description mechanisms described here are already
successfully used by the Etherbone project, whereas FPGA devices
equipped with an Ethernet port allow external hosts to be bus masters
in the internal Wishbone bus. The host computer can completely
describe and access the remote bus(es) using the structures described
here; by identifying each instantiated device it can also drive the
remote peripherals without prior knowledge of the specific FPGA binary
it is talking to.
The same mechanism is already part of the \textit{White
Rabbit PTP Core} and the outer-level FPGA designs that are
being used in our synchronized I/O boards.
\section{SDB Header Material}
This section includes the whole header file that defines the data
structures. The header itself is included in the source code
that accompanies this specification.
All fields and bits are explained in detail in later sections of this
specification, but we prefer to show the meat straight at the
beginning, before being lost in acronyms and gory details.
This header uses the Linux kernel coding style (e.g.: no \texttt{typedef} is used),
but you can write it differently if you prefer -- some of us already did -- as
long as the binary representation of the data matches this one.
\footnotesize
\verbatiminput{sdb-h.expand}
\normalsize
\section{Linux Kernel Model}
This sections describes the plans for integration of SDB in the Linux
Kernel environment. The uninterested reader can skip over to the next
section where we get back to the actual structures.
In our plans this self-description standard is tightly related with
Linux device drivers, because most of our FPGA devices are going to be
driven by a GNU/Linux host, whether over PCI, VME, or Etherbone.
Devices may appear and disappear during system lifetime: this happens
when you load and remove the PCI driver (or instantiate an Etherbone
peer), but also when you reprogram the FPGA with a different binary.
Another issue is that the device drivers may either be concerned with the FPGA
binary as a whole or be interested in each and every individual logic block;
thus, the same
GPIO logic block can be either driven by the host or ignored by it -- because
is is directly used by the soft-core within the synthesized binary.
\subsection{Wb-core and Enumeration}
For the time being, let's call the bus \textit{Wishbone} (this will
definitely be the first implementation we are using, and some specifics
of byte-wide access will need to be dealt with, so let's ignore
generality at this point).
The bus management code will be part of a kernel module called
\texttt{wb-core}. The core includes bus scanning and enumeration
logic, as well as the \textit{match} function that mates devices and
drivers, like every other Linux bus is doing.
When some piece of code detects a new bus, it will register the new
bus instance, claiming to be the associated controller. In addition,
registration specifies the address where SDB records live. The bus and
controller can be removed at any time, like you can remove a USB hub
or a \textit{Compact-PCI} bridge.
Such bus creation and removal will typically happen when the PCI
driver finds its own FPGA carrier board, or when the user tells the system
that at some network address the Etherbone protocol is
supported.
The wishbone core will start enumerating the bus, using
controller-provided operations for the individual I/O transactions;
such enumeration begins at the known address the controller declared.
The controller implements such transactions in the proper way, by
direct reads/writes to PCI or VME memory, or by sending Etherbone frames,
or whatever.
The first SDB record must be an \textit{interconnect} record: thus,
the first bytes at the SDB address are the magic number. If the magic number is not found,
enumeration is aborted. The \textit{interconnect} record is the first
in an array of SDB structures, and it declares how long the array is;
each device then declares its own address range. The system is
designed to never generate invalid memory accesses, but the first
address must be externally provided, and the controller is responsible
for providing a valid address for its own bus; then, non-SDB buses are
handled by simply not finding the magic number (in this case we assume
the bus designer willingly placed another value at that address, by
knowing the host controller is SDB-aware).
During enumeration, all SDB structures are scanned, and the core will
register a device for each and any of those items. If a driver exists
for the associated device, its own probe function is called, in the
usual way. As an alternative, the driver may appear at a later time,
or can be automatically loaded when the device is detected. Again, these
operations follow sound Linux tradition and are well known and safe.
As a special case, the probe function for a Wishbone driver can tell
the controller to stop scanning the bus, by
returning a specific non-zero value. When this happens, the core will stop
enumerating the bus -- but the driver itself is allowed to register
further devices or ask to scan sub-buses.
This feature is designed to allow multi-device blocks to be handled as
a whole. If the FPGA design is a single complex object, with its own
CPU inside and internally-driven peripheral, the Linux driver for the
associated \textit{interconnect} or \textit{integration} record will
get ownership of everything. This prevents generic GPIO or UART
drivers to be probed for by the Linux host, while
still allowing generic logic blocks to be used in the internal design.
Whenever this logic multi-device complex is embedded in an outer bus, where
host-accessible drivers live, such request to stop scanning will not
prevent outer devices to have their own Linux driver loaded. Finally,
if the driver for the logic complex wants to export some inner block
to a host device driver (e.g., an internal GPIO block), it can still
register some internal SDB records and keep other ones private,
according to internal policies.
\subsection{Accessing the Bus}
After the controller registered its own self-described bus and
\texttt{wb-core} is done scanning and probing drivers, applications
need a way to access those resources.
Whenever a driver has taken ownership of a device, it also takes
care of user access. Whether it registered GPIO pins, a tty device
or a network interface, device access is not a problem of \texttt{wb-core}.
To allow generic user-space access to the bus, \texttt{wb-core} offers
a char device interface, compatible with the API already in use within
GSI. The char device is not created by default, but a \textit{sysfs}
attribute for the bus allows to instantiate it, with a user-provided
name. With another \textit{sysfs} attribute, user space can tell the
core whether it wants complete control of the bus or only of those
devices that are not yet driven, the latter behavior being the
default. A \texttt{wb-core} system-wide parameter can be used to always
create the char device, and even always granting whole-bus access
without scanning and registering devices.
Unless it owns the whole bus, the char device will return \texttt{EBUSY} for
all I/O operations that fall in an address space that belongs to a
device driver. This is consistent with the user-space interfaces of
\textit{I2C-char} and \textit{libgpio}; it is a good policy to prevent
unexpected race conditions or other inconsistencies.
When user-space requests access to the whole bus, this will force
unbinding of all the device drivers that are active over the bus.
This is a shortcut over individually unbinding all drivers using
\textit{sysfs} device attributes. The system will also support
a user-access mode by which the whole bus is available to
user space without passing through the unbinding phase; this is
meant as a debugging tool and must be used with great care.
\subsection{Autoprobing Device Drivers}
In order to allow automatic loading of device drivers, not unlike
what already is in place for PCI, USB and other widespread bus
interfaces, we plan to add \textit{modalias} support for wishbone
and, later, for other SDB bus versions.
\subsection{Storage Support}
Another use for SDB we are evaluating these months is a simple yet
effective flash storage organization. SDB records can be used as a
very simple file-system-like interface that can be parsed by a
soft-core CPU with very little overhead.
Such a file-system will be mostly-read and requires no wear-leveling;
still, we sometimes need to update FPGA binary images or some
calibration parameters. In our search for the state of the art, we
didn't find small and simple filesystems that allow in-place
replacement of files, without touching nearby files or layout
information.
If the idea will fly, we'll define storage as a bus type, where each
record describes a file, with both a name and easily-searched device
or class identifier. Within SDB, bridge devices lend themselves to be
used to represent directories, if needed, without any semantic change.
This approach allows serious memory savings in soft-core programs that
must both find whether they have a diagnostic channels in the form of
a UART and whether they have been provided a configuration file, or
other board-dependent parameters.
Another special use of this filesystem is for FMC flash devices: the
standard mandates that the leading part of the flash includes IPMI
information for the card; the driver for the carrier board will thus
be able to scan the trailing part of the device for the SDB magic and
then register a filesystem that only spans the needed part of the
flash, as defined at manufacture time (or by device-specific
software).
Applications will create the SDB filesytem as an image file, will
write them using normal char-device MTD operations and will be able to
mount it with as a specific filesystem driver. When mounted,
individual files will be replaceable in place using the normal Unix
tools and system calls.
\section{SDB Structures}
This section defines the structures that are to be embedded in the
address space of the target bus. The words \textbf{shall},
\textbf{must}, \textbf{should}, \textbf{may}, \textbf{can} have the
usual normative meaning when used in bold face.
\subsection{Definitions}
\begin{description}
\item[SDB Structure] \hfill \\
A 64-byte memory area, located within the bus being described
at a known address. The structure \textbf{must} bit 64-byte aligned
and it \textbf{must} be readable with
32-bit I/O transactions. The bus \textbf{may} allow 64-bit, 16-bit
and 8-bit access to the structure. Code reading the structure
\textbf{should} use 32-bit transfers, and \textbf{can} use different
sizes only when aware of the specifics of the bus.
\item[SDB Record] \hfill \\
A synonym for \textit{SDB structure}.
\item[SDB Array or SDB Table] \hfill \\
An in-memory array of SDB records. The records \textbf{must}
be contiguous with no intervening holes, and the table \textbf{must}
be aligned at a 64-byte boundary.
The first SDB structure in the array \textbf{must} be an \textit{interconnect}
record (for this reason, you \textbf{must} verify the \textit{magic number}
of the array before accessing any other location in the array.
\item[Record Type] \hfill \\
The last byte of every SDB structure (offset 0x3f) represents its type.
When reading any SDB structures, unless it is the first in an array,
software \textbf{must} check the \textit{record type} before making sense
of other fields. Designers \textbf{may} extend this specification with
new record types, and software \textbf{must} ignore those structures
whose type is not known.
\item[SDB Product] \hfill \\
A data structure hosted within some SDB records. All currently defined
record types are \textit{products}.
\item[SDB Component] \hfill \\
A data structure hosted within some SDB records. A \textit{component}
includes a \textit{product} structure and defines an address range.
\end{description}
The following sections define the details of each structure.
\subsection{SDB Product Structure}
The product is embedded in all currently-defined non-empty data structures.
All multi-byte fields \textbf{must} be stored in big-endian byte order.
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{SDB Product Structure (40 bytes, at offset 24)}\label{sdb_product}\centering
\begin{tabular}{| c | c | c | l | c | p{5cm} |} \hline
First & Last & Size & Name & Value & Description \\ \hline
0x18 & 0x1f & 8 & vendor\_id & - & 64-bit vendor ID \\ \hline
0x20 & 0x23 & 4 & device\_id & - & 32-bit vendor specific device ID \\ \hline
0x24 & 0x27 & 4 & version & - & Vendor specific device version number \\ \hline
0x28 & 0x2b & 4 & date & - & The release date (hex format, eg. 0x20120601) \\ \hline
0x2c & 0x3e & 19 & name & - & UTF-8 device name, 0x20 filled, without terminator \\ \hline
0x3f & 0x3f & 1 & record\_type & - & Record type byte (see Table \ref{record_type}) \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\begin{description}
\item[vendor\_id] \hfill \\
This field provides a 64 bit field that identifies the vendor of the device. The vendor may
be an company, organization or an individual. The vendor name spaces is split in two halves;
anybody \textbf{can} pick a vendor ID in the upper half (first bit set), and the
63 bits \textbf{must} be picked as a random number and \textbf{should} be used consistently
in all the vendor's designs.
A registry is still needed to prevent collisions when using community developed designs from
multiple sources, and one should be set up as you read this.
Entities that want a more official vendor
ID than a random number, \textbf{should} apply with the current registry using a number of their choice.
Small
numbers \textbf{should} be avoided, preferring more meaningful strings instead. The
registry \textbf{should} reject numbers smaller than 12 bits, and \textbf{may} reject numbers
according to policies other than collisions with other vendors.
\item[device\_id] \hfill \\
This field specifies a manufacturer defined device ID for the device being described.
Vendors are free to managed these 32 bits as they like, but they \textbf{should} use
the same identifier for fully compatible implementations, using other fields like \textit{version}
and \textit{date} to differentiate them.
\item[version] \hfill \\
This field specifies a manufacturer defined version number for the device. Vendors
\textbf{can} use the bits as they wish; for example, this \textbf{may} be used sequentially
or \textbf{may} be derived from the information provided by the source code management in use
for gateware source code.
\item[date] \hfill \\
Design/release date of the product. This \textbf{must} be either 0 (unspecified) or a 32-bit hex
format number in the format 0xYYYYMMDD. For example, 0x20120501.
\item[name] \hfill \\
The UTF-8 name of the device. As long as the name fits in 19 bytes, designers are free to choose
any string (e.g. both ``\texttt{UART}`` or ``\texttt{8250-like Serial}'' are valid names).
The name \textbf{should} be a single word or an hyphenated word, avoiding spaces, because it \textbf{may}
be used by driver software to generate pathnames. The string \textbf{must} start at offset 0
and \textbf{must} be feature value 0x20 (space) in all trailing bytes.
It \textbf{must not} have a trailing zero byte.
\item[record\_type] \hfill \\
Since the product structure is at the end of the SDB record, it includes the
type field. You can access the field from any SDB record, because all records feature
the type byte at offset 0x3f. Software \textbf{must} verify this field before trying to
make sense of any other field in the SDB record.
There is a record type for each kind
of SDB record, and the header file gives it a symbolic name through \texttt{enum}.
The currently defined record types are listed in Table \ref{record_type}. New
record types will most likely enter this specification over time, without the need
to change the SDB version or overall layout. Users adding new record types \textbf{must}
choose a yet-unused value with the hight bit clear for \textit{component} records (0-127);
users adding new record types of informative value (a \textit{product} or a completely
different structure) \textbf{must} choose a yet-unused value with the high bit set (128-255).
Local or temporary uses \textbf{should} fall in the ranges 0x70-0x7f and 0xf0-0xfe.
Software \textbf{should} report a warning when if finds an
unknown record type in the range 0x00-0x7f is found; unknown records in the range 0x80-0xff
\textbf{can} be ignored silently.
\end{description}
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{SDB Record Types}\label{record_type}\centering
\begin{tabular}{| c | l | p{6cm} |} \hline
Name & Value & Description \\ \hline
sdb\_type\_interconnect & 0x00 & Interconnect record, first of a table \\ \hline
sdb\_type\_device & 0x01 & Device definition \\ \hline
sdb\_type\_bridge & 0x02 & Bridge to a sub-bus \\ \hline
& 0x70-0x7f & Local/temporary use \\ \hline
sdb\_type\_integration & 0x80 & Informative integration structure \\ \hline
& 0xf0-0xfef & Local/temporary use \\ \hline
sdb\_type\_empty & 0xFF & Empty record \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\subsection{SDB Component Structure}
The SDB Component is described by a data structure that includes \textit{product}
information. It provides information regarding the address space used by the
component it describes.
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{SDB Component Structure (56 bytes, at offset 8)}\label{sdb_component}\centering
\begin{tabular}{| c | c | c | l | c | p{5cm} |} \hline
First & Last & Size & Name & Value & Description \\ \hline
0x08 & 0x0f & 8 & addr\_first & - & The first valid address of the component \\ \hline
0x10 & 0x17 & 8 & addr\_last & - & The last valid address of the component \\ \hline
0x18 & 0x3f & 40 & product & - & SDB Product structure (see Table \ref{sdb_product} \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\begin{description}
\item[addr\_first] \hfill \\
The field \textbf{must} represent the first byte address that belongs to this component,
withing the encompassing bus. If the address bits in the bus are less than 64, the
unused most significant bits must be cleared. (e.g.: 0x0000.0000.0400.0000)
\item[addr\_last] \hfill \\
The field \textbf{must} represent the last byte address that belongs to this component,
withing the encompassing bus. If the address bits in the bus are less than 64, the
unused most significant bits must be cleared. (e.g.: 0x0000.0000.0400.ffff).
Thus \textbf{must not} represent the first invalid address (e.g.: 0x0000.0000.0401.0000).
\item[product] \hfill \\
This is the embedded 40 byte product info structure as described in Table \ref{sdb_product}.
\end{description}
\subsection{SDB Records}
This subsection describes the currently defined SDB records that build an SDB array.
These
structures must be instantiated by designers for each logic block in their design and compiled into
a contiguous SDB table, placed at a known address in the bus memory. Most of these structures
include a \textit{component} structure or a \textit{product} structure, and the rules for the
respective fields apply.
\subsubsection{SDB Interconnect}
The \textit{interconnect} record describes the overall bus or bus subset. Every
SDB table \textbf{must} feature such structure as first one in the array.
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{SDB Interconnect Record (64 bytes, type 0x00)}\label{sdb_interconnect}\centering
\begin{tabular}{| c | c | c | l | c | p{4cm} |} \hline
First & Last & Size & Name & Value & Description \\ \hline
0x00 & 0x03 & 4 & sdb\_magic & 0x5344422d & ``SDB-'', used to verify a table is actually there \\ \hline
0x04 & 0x05 & 2 & sdb\_records & - & Number of records in this SDB table (including this one) \\ \hline
0x06 & 0x06 & 1 & sdb\_version & 1 & SDB format version. Currently 1 \\ \hline
0x07 & 0x07 & 1 & sdb\_bus\_type & - & The bus type for all components in the table \\ \hline
0x08 & 0x3f & 56 & sdb\_component & - & SDB Component structure (see Table \ref{sdb_component} \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\begin{description}
\item[sdb\_magic] \hfill \\
The field \textbf{must} be set to 0x5344422d. If you use a similar data structure but
choose not to fully comply to this standard, you \textbf{must} use a different magic
number.
% can people comply with this ``must'' clause, if they choose not to comply with SDB?
\item[sdb\_records] \hfill \\
This field specifies the number of records in the table. It \textbf{must} include
this very record in the count, and the whole address range (this number multplied by 64 bytes)
\textbf{must} be accessible. Note that the array \textbf{may} include empty records at any position.
\item[sdb\_version] \hfill \\
This is the record format version. In the current version of the specification this is the
value 0x1. If software finds an unknown version number it \textbf{must} abort enumeration.
\item[sdb\_bus\_type] \hfill \\
This field specifies the bus type. This field is used when decoding the bus specific information
inside a device record (see below). All records in the array share the same
bus type, bus-specific bits in each device declare the details for data access.
Table \ref{bus_type} lists the currently defined types.
\item[sdb\_component] \hfill \\
An interconnect record describes a \textit{component}, so it embeds a component structure.
The \textit{type} field in the component is 0x00.
\end{description}
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{SDB Bus Types}\label{bus_type}\centering
\begin{tabular}{| c | l | p{5cm} |} \hline
Name & Value & Description \\ \hline
WishBone & 0x00 & Specifies a Wishbone bus type, as commonly used in FPGAs \\ \hline
Storage & 0x01 & Specifies use of SDB records as a simple filesystem \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\subsubsection{Integration Record}
An integration record is a \textit{product} record (not a \textit{component}, because
it has no associated address range).
The structure provides meta-data about the aggregate product of the bus or bus subset.
For example, consider
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
a vendor ID, the release date and the other \textit{product} information.
The integrator record is is described in Table \ref{sdb_integrator}.
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{SDB Integrator Record (64 bytes, type 0x80)}\label{sdb_integrator}\centering
\begin{tabular}{| c | c | c | l | c | p{5cm} |} \hline
First & Last & Size & Name & Value & Description \\ \hline
0x00 & 0x1f & 24 & reserved & - & Reserved/unused space \\ \hline
0x18 & 0x3f & 40 & product & - & SDB Product Info structure \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\begin{description}
\item[reserved] \hfill \\
The initial field in this record is unused, because all needed information is
part of the product structure. Users \textbf{should} fill this area with all bits
clear or all bit set.
\item[product] \hfill \\
This is the \textit{product} structure described in Table \ref{sdb_product}. The
record type for an integration record is 0x80.
\end{description}
\subsubsection{Device Record}
This record type describes a single device or logic block mapped into the memory of the
bus. In a compliant implementation, one device record \textbf{should} exist for each device that is
connected to the bus. Users \textbf{may} choose to aggregate a complex device under a single
description record. The structure of the device record structure is shown below in Table
\ref{sdb_device}.
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{SDB Device Record (64 bytes, type 0x01)}\label{sdb_device}\centering
\begin{tabular}{| c | c | c | l | c | p{5cm} |} \hline
First & Last & Size & Name & Value & Description \\ \hline
0x00 & 0x01 & 2 & abi\_class & - & The ABI class of the device (0 = Custom Device) \\ \hline
0x02 & 0x02 & 1 & abi\_ver\_major & - & The ABI major version \\ \hline
0x03 & 0x03 & 1 & abi\_ver\_minor & - & The ABI minor version \\ \hline
0x04 & 0x07 & 4 & bus\_specific & - & Bus specific field (flags) \\ \hline
0x08 & 0x3f & 56 & sdb\_component & - & SDB Component Info structure \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\begin{description}
\item[abi\_class] \hfill \\
The ABI class, if not 0, tells the kind of standard interface that the device provides. This
allows a single driver to deal with compatible devices designed by different vendors, not unlikely
PCI or USB classes. Currently, no ABI class is defined. Designers \textbf{should} use 0 here,
at this point in time.
\item[abi\_ver\_major] \hfill \\
This is the major version number of the ABI class. Standard interfaces are not compatible between
major version changes. If the class is 0, designers \textbf{can} use this field of driver-specific uses. For
example, a driver can be able to deal with a number of similar devices (all with a different device-ID)
and use the ABI fields as a hint to classify the various devices.
\item[abi\_ver\_minor] \hfill \\
This is the minor version number of the ABI class. Standard interfaces are compatible between
minor version changes. Again, if the class is 0, developers \textbf{can} set this field for internal use.
\item[bus\_specific] \hfill \\
This is a 4-byte field that holds bus-specific information, most likely flags. Currently, only
Wishbone flags are defined; please refer to header files for details.
\item[component] \hfill \\
This is a standard \textit{component} structure (see Table \ref{sdb_component}). The record type
for a device is 0x01.
\end{description}
\subsubsection{Bridge Record}
A bridge record is used to describe a nested bus within the same address space. This is different from
a bus controller which provides access to an entirely different address space altogether. Bus
structures with nested interconnects are typical in complex projects.
The structure of the bridge record is shown in Table \ref{sdb_bridge}.
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{SDB Device Record (64 bytes, type 0x02)}\label{sdb_bridge}\centering
\begin{tabular}{| c | c | c | l | c | p{5cm} |} \hline
First & Last & Size & Name & Value & Description \\ \hline
0x00 & 0x07 & 8 & sdb\_child & - & The relative address of the nested SDB table \\ \hline
0x08 & 0x3f & 56 & sdb\_component & - & SDB Component structure \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\begin{description}
\item[sdb\_child] \hfill \\
This field gives the location of the nested bus' SDB table. This address is a relative address
with respect to the start of the nested bus' address space (stored in the component info structure).
The value \textbf{must} point to an SDB array that begins with an \textit{interconnect} record.
\item[component] \hfill \\
An embedded component info structure, where the type is 0x01 See Table \ref{sdb_component}.
\end{description}
\end{document}
docs/specification/sdwb.tex deleted 100644 → 0
+ 0
− 470
View file @ 1036ae92
\documentclass[a4paper, 12pt]{article}
\usepackage{draftwatermark}
\usepackage{changepage}
%\usepackage{fullpage}
\usepackage{color}
\usepackage{xcolor}
\usepackage{listings}
\usepackage{array}
\usepackage{multirow}
\usepackage{footnote}
\usepackage{graphicx}
\SetWatermarkScale{4}
\usepackage{caption}
\DeclareCaptionFont{white}{\color{white}}
\DeclareCaptionFormat{listing}{\colorbox{gray}{\parbox{\textwidth}{#1#2#3}}}
\captionsetup[lstlisting]{format=listing,labelfont=white,textfont=white}
\lstset{
tabsize=4,
basicstyle=\footnotesize,
columns=fixed,
}
\parindent0pt
\parskip10pt
\makesavenoteenv{tabular}
\title{Self Descriptive Structures for Logic Cores}
\author{Manohar Vanga (BE/CO/HT), Alessandro Rubini (University of Pavia)}
\date{22 June 2011}
\begin{document}
\maketitle
\tableofcontents
\listoftables
\listoffigures
\pagebreak
\section{Introduction}
This document describes a specification for a series of self descriptive
structures that can be used to provide metadata about logic blocks, thus
allowing for upper level abstractions to automatically discover the blocks.
\subsection{Requirements}
The specification designed in this document has been designed with keeping
the following points in mind.
\begin{itemize}
\item Provide support for flexibly defining devices ranging from large and
verbose descriptors to small and efficient ones.
\item Allow for the integration of firmware level metadata into the structures.
This includes information like firmware version and synthesis date.
\item Support for heirarchical definitions where devices express parent-child
relationships.
\item Provide support for proprietary blocks that cannot be modified at the
source level and can possibly contain entire device heirarchies.
\item There should be a minimal sets of constraints placed on designers and
integrators in terms of how and where they can map their designs in memory.
\item There should be no forcible use of external metadata. Relying on external
information quickly leads to outdated and mismatched metadata.
\item Structures should be space efficient and provide support for a wide range
of hardware ranging from the small to the highly complex.
\end{itemize}
\subsection{Definitions}
\begin{description}
\item[Logic Blocks] \hfill \\
Logic blocks refer to specific logic written in a high level hardware-description
language. These are also referred to as IP cores.
\item[Bitstream] \hfill \\
The compiled binary version of a complete HDL design, possibly consisting of
multiple interconnected logic blocks, is referred to as a bitstream in this
document.
\item[Designer] \hfill \\
In this document, the term designer refers to the person who authors logic
blocks in a hardware description language.
\item[Integrator] \hfill \\
In this document, the term integrator refers to the person who is responsible
for taking a set of logic blocks and connecting them together to create the
final topology of the bistream.
\end{description}
\pagebreak
\section{Structures}
The structures of the specification are separated into \emph{block descriptive}
structures and \emph{topology descriptive} structures.
\emph{Block descriptive} structures are used to describe device information that
is static. Examples of information that resides in block descriptive
structures are device and vendor identifiers. This allows manufacturers to
fix this information into logic blocks before distribution and not worry
about providing the ability to modify the contents.
\emph{Topology descriptive} structures are used to describe the topology of blocks
within an address space. These contain information that is defined by the
integrator or designer who describes the high level topology of multiple
logic blocks in a hierarchy. An example of information that resides in
topology descriptive structures is the base address of a logic block in a
mapped address space.
The following are the \emph{block descriptive} structures that are a part of this
specification.
\begin{itemize}
\item Device descriptor blocks
\end{itemize}
The following are the \emph{topology descriptive} structures that are a part of this
specification.
\begin{itemize}
\item Header blocks
\item Identification blocks
\item Child pointer blocks
\end{itemize}
All structures contain variations on the address size to support constrained
devices. The available address sizes in the current specification are 64, 32
and 16 bits.
The following points should be noted:
\begin{itemize}
\item All values are big-endian. This has been chosen as it facilitates easy
human readability of the values. This is true of all values within structures
and should be adhered to carefully.
\item The presence of 64 bit registers within certain structures does not imply
the requirement for a 64 bit wide data bus. Multiple reads can be done using a
smaller data bus width (eg. 2 reads on a 32 bit data bus).
\item The maximum address width is currently 64 bits. While buses such as Wishbone
allow for a theoretically infinite address space, we have stayed within current
practical limits for this. In future versions, this may be increased based on
volatile requirements. This expasibility has been kept in mind throughout the
design of this specification.
\item It is entirely the choice of the designer to choose what size descriptor set
they wish to use for their logic blocks. It is entirely feasible to use a 64 bit
descriptor set for a device that only needs 16 bits of address space.
\end{itemize}
\subsection{Header Blocks}
The header blocks are simple structures that contains the locations of a top-level
child pointer block (see Section \ref{}) and an \emph{identification block} (see Section \ref{}).
Header blocks can be placed at any location within an address space
as long as the location can be found in some way (eg. a constant in HDL).
It is recommended that the address of the header be placed into memory
within the parent bus. For example, a BAR can be used in the case of PCI,
the CR/CSR space in the case of VME and the configuration space in the case
of Etherbone.
\subsubsection{LCSD64 Header Block}
The LCSD64 header block is the one used in a 64 bit address space. The structure
of the LCSD64 header block is described in Table \ref{hdr_block_struct}.
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{LCSD64 header block structure}\label{hdr_block_struct}\centering
\begin{adjustwidth}{-0.3in}{-1in}% adjust the L and R margins by 1 inch
\begin{tabular}{| c | c | l | c | c | p{5cm} |} \hline
Offset & Size & Name & Access & Value & Description \\ \hline
0x00 & 0x04 & MAGIC & RO & 0x53445742L & Magic number used to ensure that there is a valid header present. \\ \hline
0x04 & 0x02 & LCSD\_ATTR & RO & - & Attributes field describing various attributes of the LCSD version used. \\ \hline
0x06 & 0x02 & DEVICE\_COUNT & RO & - & The number of top-level devices. \\ \hline
0x08 & 0x08 & ID\_BLOCK\_ADDR & RO & - & Address of the \emph{identification block}. See section \ref{id_block} for more information. \\ \hline
0x10 & 0x08 & TLCP\_BLOCK\_ADDR & RO & - & Address of the top-level child pointer block. See section \ref{child_pointer_block} for more information. \\ \hline
\end{tabular}
\end{adjustwidth}
\end{table}
\end{savenotes}
\end{center}
\begin{description}
\item[MAGIC] \hfill \\
This field contains a unique value that allows software to ensure that
the header contains valid data. If the magic number does not match the
expected value, the software should abort.
The magic number in the current version of the specification is expected to
be 0x53445742 or the ASCII string "SDWB" (big-endian) without the
string terminator.
\item[LCSD\_ATTR] \hfill \\
This field contains various attributes that allow for identifying the size of
various blocks that has been used. The bits of this field are described in detail
in Table \ref{hdr_block_attr_struct}.
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{LCSD64 header attributes field structure}\label{hdr_block_attr_struct}\centering
\begin{tabular}{| c | l | c | c | p{5cm} |} \hline
Bits & Name & Access & Value & Description \\ \hline
0 - 1 & LCSD\_SIZE & RO & \vtop{\hbox{\strut 00 = 8 bits}\hbox{\strut 01 = 16 bits}\hbox{\strut 10 = 32 bits}\hbox{\strut 11 = 64 bits}} & The size of descriptors used. \\ \hline
2 - 15 & RESERVED & RO & - & Reserved \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\item[DEVICE\_COUNT] \hfill \\
This field contains the count of top level devices. This is used to determine how
far to read into the TLCP block when discovering devices. The two byte size of this
field allows for up to 65,536 top level child devices to be present.
\item[ID\_BLOCK\_ADDR] \hfill \\
This field contains the absolute address of the \emph{identification block} in the memory space (see
Section \ref{id_block} for more information).
\item[TLCP\_BLOCK\_ADDR] \hfill \\
This field contains the absolute address of the top level child pointer block (see
Section \ref{tlcp_block} for more information).
\end{description}
\subsection{LCSD64/32/16/8 Identification Block}\label{id_block}
The \emph{identification block} contains information that identifies the bitstream within the FPGA.
The structure of the \emph{identification block} is described in Table \ref{id_block_struct}.
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{LCSD64 identification block structure}\label{id_block_struct}\centering
\begin{adjustwidth}{-0.4in}{-1in}% adjust the L and R margins by 1 inch
\begin{tabular}{| l | c | l | c | c | p{5cm} |} \hline
Offset & Size (in bytes) & Name & Access & Value & Description \\ \hline
0x00 & 0x08 & BSTREAM\_TYPE & RO & - & The bitstream type identifier. \\ \hline
0x08 & 0x04 & BSTREAM\_VERSION & RO & - & The version of the specific bitstream. \\ \hline
0x0C & 0x04 & BSTREAM\_DATE & RO & - & The synthesis date of the bitstream. \\ \hline
0x10 & 0x10 & BSTREAM\_SOURCE & RO & 0x0 & The source code management (SCM) identifier. \\ \hline
\end{tabular}
\end{adjustwidth}
\end{table}
\end{savenotes}
\end{center}
\begin{description}
\item[BSTREAM\_TYPE (Offset: 0x00)] \hfill \\
The bitstream device type should hold a value that uniquely identifies the type of
bitstream present in the FPGA. Note that different bitstreams can have the
same type with differing versions (see below).
\item[BSTREAM\_VERSION (Offset: 0x08)] \hfill \\
The bitstream version should hold a value that specifies the version of the
bitstream present in the FPGA. This field along with the BSTREAM\_TYPE field,
should uniquely identify a specific bitstream.
\item[BSTREAM\_DATE (Offset: 0x0C)] \hfill \\
The bitstream date should be set to the hex-readable date of synthesis of
the bitstream. An example of a hex-readable date is 0x20111225 (25th December
2011).
\item[BSTREAM\_SOURCE (Offset: 0x10)] \hfill \\
This field should specify an identifier for the revision control software
used to manage the HDL code for the bitstream type.
In the case of SVN repositories, the value of the revision number should
be stored in this field. For example, if the SVN revision is 1024, the
stored value should be 0x400.
In the case of Git repositories, the first 16 bytes (0x10 bytes) of the
160 bit (20 bytes, 0x14 bytes) value of the commit hash should be stored
in this field.
\end{description}
\subsection{LCSD64 Child Pointer Block}\label{cp_block}
The child pointer block is a variable sized array of Child pointers. The LCSD
structure size of this must be the same as that given in the header.
The structure of the child pointers is described in Table \ref{cp_block_struct}
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{LCSD64 child pointer structure}\label{cp_block_struct}\centering
\begin{adjustwidth}{-0.4in}{-1in}% adjust the L and R margins by 1 inch
\begin{tabular}{| l | c | l | c | c | p{5cm} |} \hline
Offset & Size (in bytes) & Name & Access & Value & Description \\ \hline
0x00 & 0x08 & OFFSET & RO & - & The offset of the child from the address of this child pointer structure. \\ \hline
\end{tabular}
\end{adjustwidth}
\end{table}
\end{savenotes}
\end{center}
\subsection{LCSD64 Device Descriptor}\label{device_block}
The device descriptor describes a single device. The device descriptor has a
structure as described in Table \ref{dev_desc_struct}.
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{LCSD64 device descriptor structure}\label{dev_desc_struct}\centering
\begin{tabular}{| l | c | l | c | c | p{5cm} |} \hline
Offset & Size (in bytes) & Name & Access & Value & Description \\ \hline
0x00 & 0x08 & VENDOR & RO & - & The vendor ID of the vendor of the device. \\ \hline
0x08 & 0x04 & DEVICE & RO & - & The device ID of the device. \\ \hline
0x0C & 0x02 & LCSD\_MAGIC & RO & 0x5742 & Magic number used to identify a valid device descriptor. \\ \hline
0x0E & 0x01 & LCSD\_VER\_MAJOR & RO & - & The major version of the descriptor format. \\ \hline
0x0F & 0x01 & LCSD\_VER\_MINOR & RO & - & The minor version of the descriptor format. \\ \hline
0x10 & 0x04 & DEVICE\_OFFSET & RO & - & The offset of this block with respect to the device base address. \\ \hline
0x14 & 0x04 & DEVICE\_FLAGS & RO & 0x0 & Device flags. \\ \hline
0x18 & 0x08 & HDL\_SIZE & RO & - & Size (in bytes) of the device address space. \\ \hline
0x20 & 0x04 & HDL\_CLASS & RO & - & HDL class. \\ \hline
0x24 & 0x04 & HDL\_VERSION & RO & - & HDL version. \\ \hline
0x28 & 0x10 & VENDOR\_NAME & RO & - & Vendor name (ASCII string) \\ \hline
0x38 & 0x10 & DEVICE\_NAME & RO & - & Device name (ASCII string) \\ \hline
0x48 & 0x08 & NUM\_CHILDREN & RO & 0x0 & Number of children this device has. \\ \hline
0x50 & - & DEVICE\_CHILDREN & RO & - & Child pointer block. \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\begin{description}
\item[VENDOR] \hfill \\
The vendor ID of the device.
\item[DEVICE] \hfill \\
The device ID of the device. Together with the vendor ID, the
device ID may be used to match device drivers. The format can be specified
in any way by a vendor as the software reading this field will be
specific to each vendor.
\item[LCSD\_MAGIC] \hfill \\
This is a unique value used to identify a valid device descriptor. If
an invalid magic value is found, that device is ignored.
The magic number in all versions of the specification can be expected to
be 0x5742 or the ASCII string "WB" without the string terminator.
\item[LCSD\_VER\_MAJOR] \hfill \\
The major version of the device descriptor format. This field is incompatible
between versions. This means that a change in the descriptor structure itself
leads to an increase in the major version. An example of a major version change
is the extension of HDL\_BASE and HDL\_SIZE to 16 bytes (128 bits).
\item[LCSD\_VER\_MINOR] \hfill \\
The minor version of the device descriptor format. This field is compatible
between versions. This means that a change only in the minor number means the
structure is preserved. An example of a minor version change is the addition
of a new flag in the DEVICE\_FLAGS field.
\item[DEVICE\_OFFSET] \hfill \\
This field contains the offset of the start of the device descriptor within
the address space of the device. This can be an internal offset, in which
case the offset is subtracted from the address of the descriptor to get the
base address of the device. It may also be an external offset, in which
case the offset is added to the address of the device descriptor to get the
base address of the device. The type is specified by the INTERNAL\_OFFSET
flag in the DEVICE\_FLAGS register.
\item[DEVICE\_FLAGS] \hfill \\
This field contains device specific flags. The structure is given below in
table \ref{dev_flags}.
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{LCSD64 device flags field structure}\label{dev_flags}\centering
\begin{tabular}{| c | l | c | c | p{5cm} |} \hline
Bits & Name & Access & Value & Description \\ \hline
0 & EXTERNAL\_OFFSET & RO & \vtop{\hbox{\strut 0 = Internal}\hbox{\strut 1 = External}} & Specified whether the offset provided in the DEVICE\_OFFSET field is internal of external. \\ \hline
1 & ENDIAN & RO & \vtop{\hbox{\strut 0 = Big Endian}\hbox{\strut 1 = Little Endian}} & Specifies the endianness of the address range of this device. \\ \hline
2 & IGNORE & RO & \vtop{\hbox{\strut 0 = Use this descriptor}\hbox{\strut 1 = Ignore descriptor}} & Specifies whether the device should be considered to be present or not. \\ \hline
4 - 23 & RESERVED & RO & - & Reserved \\ \hline
24 - 27 & GRANULARITY & RO & \vtop{\hbox{\strut 00 = 8 bits}\hbox{\strut 01 = 16 bits}\hbox{\strut 10 = 32 bits}\hbox{\strut 11 = 64 bits}} & The I/O granularity of the device. \\ \hline
28 - 31 & WIDTH & RO & \vtop{\hbox{\strut 00 = 8 bits}\hbox{\strut 01 = 16 bits}\hbox{\strut 10 = 32 bits}\hbox{\strut 11 = 64 bits}} & The data width of the device. \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\item[HDL\_SIZE] \hfill \\
This field contains the size of the address space of this device.
The software reading this field should know what address width to expect.
\item[HDL\_CLASS] \hfill \\
The class of the device. The class is used to identify a device
with a specific register map, so a host driver can handle all devices of
the same class, irrespective of vendor and device numbers. This is similar
to PCI or USB devices.
\item[HDL\_VERSION] \hfill \\
This field specifies the version of the device. The format can be
specified in any way by a vendor as the software reading this field will be
specific to each vendor (selected based on the metadata stored in the
parent board) and is expected to know how to decode this field.
\item[VENDOR\_NAME] \hfill \\
The ASCII string representation of the vendor name. The unused bytes of the
string should be set to the value 0x20. The length of the ASCII string can range
up to the maximum size (16 characters).
\item[DEVICE\_NAME] \hfill \\
The ASCII string representation of the device name. The unused bytes of the
string should be set to the value 0x20. The length of the ASCII string can range
up to the maximum size (16 characters).
\item[NUM\_CHILDREN] \hfill \\
This field specifies the number of children that this device has. The default
value is set to 0. This is used to identify the length of the child pointer
block within the descriptor (see DEVICE\_CHILDREN field).
\item[DEVICE\_CHILDREN] \hfill \\
This field is a variable length child pointer block that provides information
about all children of this device.
\end{description}
\subsubsection{Note on Vendor IDs}
The vendor ID values are taken from a 64 bit address space.
This space is divided into two sections; \emph{reserved} and \emph{free}.
The \emph{reserved} vendor space includes all values with the highest
bit unset (0x0000000000000000 - 0x7FFFFFFFFFFFFFFF).
The \emph{free} vendor space includes all values with the highest
bit set (0x8000000000000000 - 0xFFFFFFFFFFFFFFFF).
Vendors are free to choose any value within the free space. There is no
guarantee of collisions of ID's with other vendors within the free space.
In the future, there could possibly be a central repository that allows
for guaranteed vendor ID's within the reserved space. The current version
of the specification however, provides no guarantee of collisions within
the reserved space. If you wish to use ID's from the reserved space, you
might need to make modifications to your device in future version of this
specification.
It is recommended that the vendor ID be chosen using an established
hashing algorithm by feeding it uniquely identifying fields. The
recommended fields to use are the vendor name string and a 128 bit random
seed. It is recommended to use the MD5 hash of these fields and take the
8 least significant bytes from the resulting hash.
\subsubsection{Note on Optional Fields}
Device descriptors have certain field which are optional. These are HDL\_CLASS,
HDL\_VERSION, VENDOR\_NAME, DEVICE\_NAME.
\section{Example Memory Map}
Figure \ref{fig:wbmap} illustrates the
structure of the Wishbone memory map for a bitstream containing three Wishbone
devices. There is a single header block that has the addresses of the other
blocks. There is a single ID block containing metadata regarding the bitstream
along with a single device descriptor block containing descriptors for the three
devices present in the bitstream.
\begin{figure}[!ht]
\centering
\includegraphics{wbmap.eps}
\caption{Example memory map of a Self-Describing Wishbone bus}
\label{fig:wbmap}
\end{figure}
\end{document}
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