Newer
Older
\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}
\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 Description Structures for Logic Cores}
\author{Manohar Vanga (BE/CO/HT), Wesley Terpstra (GSI),\\
Alessandro Rubini (Independent Consultant)}
\date{June 20th 2012}
\begin{document}
\maketitle
\tableofcontents
%\listoftables
%\listoffigures
\pagebreak
\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
\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 ridiculously small
because the model of the respective consortia is based on artificial scarcity.
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. This
choice is taken in order to make life easier for some developers (the poor
guys and dolls that sometimes need to look at binary dumps one byte at a time)
and to make life harder for other developers (the poor guys and dolls that work
on the PC and think all the world is \textit{little endian}). Actually,
by choosing the less common endianness we aim for code to be more
portable, because code ignoring byte ordering will simply not work
when compiled on the most common platforms.
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 is not \textit{official} in any way: it just
documents what we are doing and why we do it like this. We believe
in free circulation of ideas and we think the good ones will flourish.
Everybody is welcome to use the data structures defined in this specification
and give feedback, both positive and negative.
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
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 the 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 using a standard
\textit{interconnect} logic block to declare its own
identifiers and integration date for the whole FPGA design; as
such we expect to find it only in the description of the
outer bus description level.
\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.
\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 soon going to be used in 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 oue 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 attrobutes.
\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;
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
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}
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
\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.
he first SDB structure in the array \textbf{must} be an \textit{interconnect}
record.
\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}
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{SDB Product Info Structure (40 bytes)}\label{sdwb_product_struct}\centering
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
\begin{tabular}{| c | c | l | c | p{5cm} |} \hline
Offset & Size (bytes) & Name & Value & Description \\ \hline
0x00 & 8 & VENDOR\_ID & - & 64-bit vendor ID \\ \hline
0x08 & 4 & DEVICE\_ID & - & 32-bit vendor specific device ID \\ \hline
0x0C & 4 & VERSION & - & Vendor specific device version number \\ \hline
0x10 & 4 & DATE & - & The release date (hex format, eg. 0x20120601) \\ \hline
0x14 & 19 & NAME & - & ASCII device name without NULL terminator \\ \hline
0x27 & 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 size of this field has been kept at 64
bits to prevent collisions in the long term.
A registry is still needed to prevent collisions when using community developed designs from
multiple sources and one will be set up in the near future. However, use of the registry is
not mandated. To allow for this, the 64 bit ID space is split into two parts. All ID's with
the most significant bit set are considered free to use. No guarantees are provided regarding
collisions when using this space during integration of designs with externally provided
components.
The second part of the ID space with the most significant bit unset is reserved for use with
the registry.
\item[DEVICE\_ID] \hfill \\
This field specifies a manufacturer defined device ID for the device being described.
\item[VERSION] \hfill \\
This field specifies a manufacturer defined version number for the device. For example, this
may be derived from the information provided by the source code management being used.
\item[DATE] \hfill \\
This field specified the release date of the device being described. This must be a 32-bit hex
format number in the format 0xYYYYMMDD. For example, 0x20120101 specifies the first day of the
year 2012.
\item[NAME] \hfill \\
The ASCII name of the device. No NULL terminator need be provided in this field. The name length
may be a maximum length of 19 characters. Unused bytes should be set to 0x20 (or ASCII SPACE).
\item[RECORD\_TYPE] \hfill \\
Since the product info structure is embedded within various types of record structures, this
field specifies the type of the encapsulating structure. There is a record type for each kind
of SDB record as well as one to specify an empty record. The various record types are described
in Table \ref{record_type}.
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{SDB Record Types}\label{record_type}\centering
\begin{tabular}{| c | l | p{5cm} |} \hline
Name & Value & Description \\ \hline
INTERCONNECT & 0x00 & Interconnect record type \\ \hline
DEVICE & 0x01 & Device record type \\ \hline
BRIDGE & 0x02 & Bridge record type \\ \hline
INTEGRATOR & 0x80 & Integrator record type \\ \hline
EMPTY & 0xFF & Empty record type \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\end{description}
\subsection{SDB Component Info}
The Component Info structure is a 56 byte structure which, in addition to embedding product
information, also additionally provides information regarding the address space used by the
device. When a particular record type requires address space information in addition to product
information, this structure is embedded.
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{SDB Component Info Structure (56 bytes)}\label{sdwb_component_struct}\centering
\begin{tabular}{| c | c | l | c | p{5cm} |} \hline
Offset & Size (bytes) & Name & Value & Description \\ \hline
0x00 & 8 & ADDR\_BEGIN & - & The start address of the component \\ \hline
0x08 & 8 & ADDR\_LAST & - & The last valid address of the component \\ \hline
0x10 & 40 & PRODUCT & - & SDB Product Info structure (see Table \ref{sdwb_product_struct} \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\begin{description}
\item[ADDR\_BEGIN] \hfill \\
The start address of the memory area occupied by the device.
\item[ADDR\_LAST] \hfill \\
The last valid address in memory that is occupied by the device. For example, a device that takes
up the entire 64-bit space has its last address at 0xffffffffffffffff
\item[PRODUCT] \hfill \\
This is the embedded 40 byte product info structure as described in Table \ref{sdwb_product_struct}.
\end{description}
\subsection{SDB Records}
This subsection describes the different SDB records that compose the SDB table structure. These
structures must be instantiated by designers for each logic block in their design and compiled into
a contiguous SDB table that gets placed in the bus memory.
\subsubsection{Interconnect Record}
The interconnect record describes the high level bus that has child devices connected to it. This
structure should be the "header" or first record in the SDB table. It provides, among other things,
information regarding the SDB table (eg. the number of following records).
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{SDB Interconnect Record Structure}\label{sdwb_interconnect_struct}\centering
\begin{tabular}{| c | c | l | c | p{5cm} |} \hline
Offset & Size (bytes) & Name & Value & Description \\ \hline
0x00 & 4 & MAGIC & 0x53445742 & Magic value for checking validity \\ \hline
0x04 & 2 & NUM\_RECORDS & - & Number of records in this SDB table \\ \hline
0x06 & 1 & SDB\_VERSION & 0x1 & SDB format version. Current is 0x1 \\ \hline
0x07 & 1 & SDB\_BUS\_TYPE & - & The last valid address of the component \\ \hline
0x08 & 56 & COMPONENT & - & SDB Component Info structure (see Table \ref{sdwb_component_struct} \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\begin{description}
\item[MAGIC] \hfill \\
This field is a unique number to ensure that the record being read is valid. The default
value for this in this version of the specification is 0x53445742 or the ASCII characters
\item[NUM\_RECORDS] \hfill \\
This field specifies the number of records in the table. The number must take into account
this header (interconnect) record as well. The other records following the header may be
any combination of device, bridge and integrator records.
\item[SDB\_VERSION] \hfill \\
This is the record format version. In the current version of the specification this is the
value 0x1.
\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). In the current version of the specification, the only
supported bus is Wishbone. Other buses may be added in the future.
\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 \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\item[COMPONENT] \hfill \\
An interconnect record has a component info structure embedded within it which can be used
to provide additional meta-data regarding the interconnect itself.
\end{description}
\subsubsection{Integrator Record}
An integrator record gives meta-data about the aggregate product of the bus. 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 integrator record.
This record is important as it helps to clearly distinguish product information of devices and of
their aggregated products. Since this is the only main requirement of the integrator record, it
only contains a product info structure without the additional address space information (as this
can easily be gleaned from the records for the specific devices that compose the aggregate). The
structure of the integrator record is described in Table \ref{sdwb_integrator_struct}.
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{SDB Integrator Record Structure}\label{sdwb_integrator_struct}\centering
\begin{tabular}{| c | c | l | c | p{5cm} |} \hline
Offset & Size (bytes) & Name & Value & Description \\ \hline
0x00 & 24 & RESERVED & - & Reserved bytes \\ \hline
0x18 & 40 & PRODUCT & - & SDB Product Info structure (see Table \ref{sdwb_product_struct} \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\begin{description}
\item[PRODUCT] \hfill \\
An integrator record has a product info structure embedded within it which can be used
to provide meta-data that aids in identifying the aggregating interconnect.
\end{description}
\subsubsection{Device Record}
This record type describes a single device or logic block mapped into the memory of the
bus. In a correct implementation, one device record should exist for each device that is
connected to the bus. The structure of the device record structure is shown below in Table
\ref{sdwb_dev_struct}.
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{SDB Device Record Structure}\label{sdwb_dev_struct}\centering
\begin{tabular}{| c | c | l | c | p{5cm} |} \hline
Offset & Size (bytes) & Name & Value & Description \\ \hline
0x00 & 2 & ABI\_CLASS & - & The ABI class of the device (0 = Custom Device) \\ \hline
0x02 & 1 & ABI\_VER\_MAJOR & - & The ABI major version \\ \hline
0x03 & 1 & ABI\_VER\_MINOR & - & The ABI minor version \\ \hline
0x04 & 4 & BUS\_SPECIFIC & - & Bus specific field \\ \hline
0x08 & 56 & COMPONENT & - & SDB Component Info structure (see Table \ref{sdwb_component_struct} \\ \hline
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\begin{description}
\item[ABI\_CLASS] \hfill \\
The ABI class, if specified, tells the kind of standard interface that the device provides. The
currently available types of ABI classes are specified in Table \ref{abi_class_list}.
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{ABI Classes}\label{abi_class_list}\centering
\begin{tabular}{| c | l | p{5cm} |} \hline
Value & ABI Class & Description \\ \hline
0 & Custom Device & Used when the device does not conform to any standard interface \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\item[ABI\_VER\_MAJOR] \hfill \\
This is the major version number of the ABI class. Standard interfaces are not compatible between
major version changes.
\item[ABI\_VER\_MINOR] \hfill \\
This is the minor version number of the ABI class. Standard interfaces are compatible between
minor version changes.
\item[BUS\_SPECIFIC] \hfill \\
This is a 4-byte field that holds bus-specific information. The bus specific information for different
supported buses is described in Table \ref{bus_specific}.
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{Wishbone -- Bus Specific Information}\label{bus_specific}\centering
\begin{tabular}{| c | l | p{5cm} |} \hline
Bit Offset & Name & Description \\ \hline
0 & ENDIAN & Specifies the endianness of the device (0 = big endian, 1 = little endian) \\ \hline
\end{tabular}
\end{table}
\end{savenotes}
\end{center}
\item[COMPONENT] \hfill \\
An embedded component info structure for providing meta-data about the device being described.
\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
controllers should be treated and handled as devices and not bridges. The structure of the bridge record
is shown in Table \ref{sdwb_bridge_struct}.
\begin{center}
\begin{savenotes}
\begin{table}[!ht]\footnotesize
\caption{SDB Bridge Structure}\label{sdwb_bridge_struct}\centering
\begin{tabular}{| c | c | l | c | p{5cm} |} \hline
Offset & Size (bytes) & Name & Value & Description \\ \hline
0x00 & 8 & SDB\_CHILD & - & The relative address of the nested SDB table \\ \hline
0x08 & 56 & COMPONENT & - & SDB Component Info structure (see Table \ref{sdwb_component_struct} \\ \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).
\item[COMPONENT] \hfill \\
An embedded component info structure for providing meta-data about the bridge being described.
\end{description}
\end{document}