proposal: more beef, still not the tech part

docs/specification/proposal.tex

@@ -56,14 +56,14 @@ 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 would enumerate its own
+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 like \texttt{lspci} or \texttt{lsusb};
+\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 driver within soft cores;
 \item Better decoupling of gateware and software development.
@@ -76,13 +76,13 @@ 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 the
+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 and FPGA, either. On one side, they assume devices are
-enumerated by other means, whereas we need to be able to scan a flat
-address space; on the other their vendor ID space is ridiculously small,
+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.
@@ -90,8 +90,9 @@ The vendor space is spit in two parts, and everybody is free to elect their
 own vendor number and start designing using the spec, provided the most-significant
 bit is set.
 
-We acknowledge the usefulness of a central vendor registry, so the
-vendor-ID space with the first bit zeroed is reserved for numbers that
+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.
@@ -99,7 +100,7 @@ have already been used.
 All multi-byte values are stored in \textit{big endian} order.  This
 choice is designed to make the life easier some developers (the poor
 guys that sometimes need to look at binary dumps one byte at a time)
-and to make like harder for other developers (the poor guys that work
+and to make life harder for other developers (the poor guys that work
 on the PC and think all the world is \textit{little endian}).  Actually,
 by choosing the less common endianness we think it's easier to write
 portable code, because code ignoring byte ordering will simply not work
@@ -108,17 +109,17 @@ when compiled on the PC.
 All data structures are 64 byte large and are similar in their
 internal layout; the last byte in the 64-wide slot identifies the type
 of each structure, to allow very simple parsing code and easy extension
-to new types of structures.  The size os a power of two in order to
-avoid multiplication and division in calculating array sizes, as the
+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 it is done like it is.  We believe
+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 used in this specification
+Everybody is welcome to use the data structures defined  in this specification
 and give feedback, both positive and negative.
 
 The document (with the notable exception of this section) is written
@@ -139,12 +140,103 @@ computer or network.
 
 \subsection{The Overall System Structure}
 
-%FIXME: describe bus, device, driver, controller etc
+The bus described by the structures defined herein is set up as a
+flag address space. Our initial target is the \textit{Wishbone} bus,
+as used in our own FPGA projects, but the overall situation is
+pretty general.
+
+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, using an array
+of data structures (one per sub-block).
+
+Some of those blocks in turn may be bridges to another address
+demultiplexer; to support this the structures allow for a different
+array of structures to be indexed from any array of structures,
+to allow nesting at arbitrary levels.
+
+The structures themselves are expected to be readable at some address
+that is part bus itself (i.e., the interconnect blocks are expected to
+be able to route bus access to their own internal ROM data).
+
+Only the bus designer knows where the outer-level data structure is to
+be found, and such information is expected to be known but 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 handle
+to self description lives; an \textit{Etherbone} bus master will
+comply to its own packet-format standard, so it can as well know
+where to start enumerating the bus from.
+
+We can therefore define the following items to build the
+self-description framework:
+
+\begin{description}
+\item[Product] \hfill \\
+Every structure includes \textit{product} fields. They are
+the vendor and device identifiers, version and date, an UTF-8
+name.
+
+\item[Component] \hfill \\
+A component is a product with an associated address range. Its
+structure lists the first and last valid addresses within
+the encompassing address space.
+
+\item[Interconnect] \hfill \\
+The interconnect is a component representing an address demultiplexer.
+The associated data structure heads an array of product descriptions,
+it features a magic number, bus type, version and the number of
+structures in the array.
+
+\item[Device] \hfill \\
+The device component identifies a peripheral block, with
+its class, ABI version and bus-specific flags.
+
+\item[Bridge] \hfill \\
+The bridge component marks a memory area leading to a lower-level
+address demultiplexer (i.e. \textit{interconnect}). Its data
+structure declares the address where the self-description of the
+sub-bus is found.
+
+\item[Integration] \hfill \\
+The optional integration product describes the aggregate bus.
+It is a \textit{product} record, not a
+\textit{component}, so 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 description
+array is found.  There is no controller concept for soft-cores
+self-scanning their own address space.
+
+\end{description}
 
 \subsection{Current Implementations}
 
-Etherbone
-%FIXME: describe etherbone implementation
+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{SDWB Header Material}
 
@@ -158,7 +250,7 @@ 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.
+long as the binary representation of the data matches this one.
 
 %FIXME: header material in the document