\documentclass[10pt,oneside]{article}
\reversemarginpar
+\usepackage[titles]{tocloft}
\usepackage{emp}
\DeclareGraphicsRule{*}{mps}{*}{}
\end{abstract}
+%\vfill
+%\fbox{\parbox{5in}{\footnotesize
+%\begin{center}
+%The software described in this memo may be obtained using
+%\href{http://www.darcs.net/}{\tt darcs}, with the command:
+%
+%{\tt darcs get http://research.cs.berkeley.edu/class/fleet/repos/fleet/}
+%\end{center}
+%}}
+
+\pagebreak
+\tableofcontents
+
\pagebreak
-\section*{Introduction (from \cite{ies02})}
+\section{Introduction (from \cite{ies02})}
During the past two and a half years, the Fleet architecture has gone
through massive changes and improvements. Nonetheless, the
\pagebreak
-\section*{The Programmer's View of The Ship-Fabric Interface}
+\section{The Programmer's View of The Ship-Fabric Interface}
The role of the Fleet switch fabric is to carry {\it packets} from
{\it sources} to {\it destinations}.
\pagebreak
-\section*{Data Formats}
+\section{Data Formats}
-\subsection*{Path (12 bits)}
+\subsection{Path (12 bits)}
These bits appear physically within the switch fabric. \footnote{In
the Sun Labs implementation, these bits have ``address bit
\end{bytefield}
}
-\subsection*{Data Word In Memory (37 bits)}
+\subsection{Data Word In Memory (37 bits)}
A word of data is 37 bits wide.
\end{bytefield}
}
-\subsection*{Packet In Flight (49 bits)}
+\subsection{Packet In Flight (49 bits)}
{\tt\footnotesize
\begin{bytefield}{49}
\end{bytefield}
}
-\subsection*{Instruction In Memory (37 bits)}
+\subsection{Instruction In Memory (37 bits)}
An instruction must be no wider than a memory word. The next section
explains the bits in greater detail. The {\tt Instruction Path} is
\end{bytefield}
}
-\subsection*{Instruction Packet In Flight (49 bits)}
+\subsection{Instruction Packet In Flight (49 bits)}
Note that Fleet simply copies the {\tt Instruction Path} field, bit
for bit, into the packet {\tt Path} field in order to ``dispatch'' an
\setlength{\bitwidth}{5mm}
\pagebreak
-\section*{Instruction Formats}
+\section{Instruction Formats}
\begin{wrapfigure}{R}{2in}
\epsfig{file=locations,width=2in}
\vspace{-0.4in}
\vspace{0.3cm}
{\bf Kill}
+\addcontentsline{toc}{subsection}{Kill}
{\tt
\begin{bytefield}{26}
\vspace{0.3cm}
{\bf Clog}
+\addcontentsline{toc}{subsection}{Clog}
{\tt
\begin{bytefield}{26}
\vspace{0.3cm}
{\bf UnClog}
+\addcontentsline{toc}{subsection}{UnClog}
{\tt
\begin{bytefield}{26}
\vspace{0.3cm}
{\bf Literal}
+\addcontentsline{toc}{subsection}{Literal}
{\tt
\begin{bytefield}{26}
\pagebreak
{\bf Normal Instruction}
+\addcontentsline{toc}{subsection}{Normal Instruction}
{\tt
\begin{bytefield}{26}
\pagebreak
-\section*{Opcodes}
+\section{Opcodes}
Opcodes, as specified in \cite{am25}, are not yet implemented, but
should be.
-\section*{Bypasses}
+\section{Bypasses}
Bypasses, as specified in \cite{am27}, are not yet implemented, but
should be.
-\section*{Sequencing Guarantees}
+\section{Sequencing Guarantees}
+\addcontentsline{toc}{subsection}{Source Sequence Guarantee}
If two packets leave the same source and have the same path, they will
arrive at their common destination {\it in the same order in which
they left the source}. This assurance is referred to as the {\it
source sequence guarantee}.
+\addcontentsline{toc}{subsection}{Instruction Sequence Guarantee}
CodeBags in memory consist of an unordered set of {\it fibers}. A
fiber is an ordered set of instructions which all share the same
instruction path, and therefore will be executed by the same pump.
will take advantage of the source sequence guarantee in order to
fulfill the instruction sequence guarantee.
-\section*{Code Bags}
+\section{Code Bags}
Code bags may overlap in memory. If the assembler determines that two
code bags share a set of fibers, it may feel free to re-order those
have different addresses and/or sizes, but the ranges which they
encompass will overlap.
-\subsection*{Dispatching Code Bags}
+\subsection{Dispatching Code Bags}
A codebag is ``dispatched'' by causing its constitutent words to
arrive at the data latch of some output port, and then causing that
program which can ``relocate'' a codebag by replacing the {\tt
Instruction Path} fields as needed.
-\subsection*{Tokens and Data Items}
+\subsection{Tokens and Data Items}
When a data item is sent to a destination which expects a token, such
as an output port destination, the effect will be the same as if a token
reliable mechanism for distinguishing between tokens and data items.
-\section*{Future Directions}
+\section{Future Directions}
-\subsection*{The Role of the Count Field}
+\subsection{The Role of the Count Field}
Looking back on the design of the pump, several things are now
apparent which were not initially. In particular, it seems that it
\begin{itemize}
\item await and acknowledge a token
\item await and acknowledge a datum
+\item load the awaited datum into the path latch (top 11 bits)
\item load the awaited datum into the data latch
-\item load the a literal into the data latch
-\item load a value indicated by the instruction into the path latch
-\item load the top 11 bits of the data latch into the path latch
-\item treat the values in the path latch and data latch as a packet and transmit it
-\item treat the value in the path latch as a token and transmit it
+\item load a literal into the data latch
+\item load a literal into the path latch
+\item send the value in the data latch along the path in the path latch
+\item send a token along the path in the path latch
\item set the count register to a literal value
\item decrement the count register
\item requeue this instruction if {\tt count>0}
latches from two distinct data items, allowing ships to create,
handle, and consume {\it packets} in the form of a pair of data items.
-At this point, it boils down to a question of instruction bit
-budgeting. Currently we have a separate instruction form for
-literals, so that the literal can use bits which are not otherwise
-relevant to literal instructions (for example, {\tt Di}). Adding an
-additional instruction form for loading the count register would have
-similar advantages.
+At this point, the remaining decisions are simply a question of
+instruction bit budgeting. Currently we have a separate instruction
+form for literals, so that the literal can use bits which are not
+otherwise relevant to literal instructions (for example, {\tt Di}).
+Adding an additional instruction form for loading the count register
+would have similar advantages.
-\subsection*{For Just a Little Bit More...}
+\subsection{For Just a Little Bit More...}
Compared to early revisions of the Fleet architecture, the valves of
FleetTwo are substantially more powerful. One might ask, why not add
Ultimately, the instruction stream for any component of a processor
must exist in some physical incarnation -- some geometric extent. If
the control flow of a program is linear, with no branching, then the
-instruction stream has an optimal spatial mapping which is quite
-efficient: it is simply laid out in FIFO fashion.
+instruction stream has an optimal spatial mapping which is
+efficient: simply lay it out as a FIFO.
By contrast, however, a program whose instruction stream has
-unrestricted branching is logically a {\it tree} structure. Quite
-unfortunately, general trees have no efficient mapping onto
+unrestricted branching is logically a {\it tree} structure.
+Unfortunately, however, general trees have no efficient mapping onto
two-dimensional surfaces. By this, I mean that in every possible
mapping, there exists some pair of {\it logically adjacent}
instructions whose {\it physical distance} is proportional to the size
of the entire program, rather than some constant factor irrespective
of the program size. Therefore I conclude that the spatial mapping of
a program with unrestricted branching is in an entirely different
-class than that of programs with linear control flow. I choose this
-distinction as the basis for limiting our valves to linear control
+class than that of programs with linear control flow, and I choose this
+distinction as the basis for limiting the valves to linear control
flow sequences. A similar argument can be made for looping constructs
in which two or more loops may be nested within a single parent loop.
I feel that this addition would not risk falling down the slippery
slope -- instruction streams with predicated instructions (but not
-unrestricted branching) preserve the crucial property that they have
-an efficient spatial mapping. Any steps beyond this, however, cross a
-fairly fundamental line.
+unrestricted branching or nested looping) preserve the crucial
+property that they have an efficient spatial mapping. Any steps
+beyond this, however, cross a fairly fundamental line.
+
+\addcontentsline{toc}{section}{Ship Descriptions}
\documentclass[10pt,oneside]{article}
\reversemarginpar
+\usepackage[titles]{tocloft}
\usepackage{palatino}
\usepackage{wrapfig}
\usepackage{epsfig}
{\it The FleetTwo Architecture Manual}
\end{thebibliography}
+
\vspace{3cm}
\begin{abstract}
-FIXME
+Fleet compilers and tools work primarily with representations of two
+entities: Ships, Instructions, and Test Cases. In order to promote
+greater interoperability, the FleetTwo Toolchain defines both a Java
+API and a textual file format for each of these.
\end{abstract}
+\vfill
+\fbox{\parbox{5in}{\footnotesize
+\begin{center}
+The software described in this memo may be obtained using
+\href{http://www.darcs.net/}{\tt darcs}, with the command:
+
+{\tt darcs get http://research.cs.berkeley.edu/class/fleet/repos/fleet/}
+\end{center}
+}}
\pagebreak
-\section*{Fleet Assembly Language}
+\tableofcontents
-The Fleet Assembly language is designed to be a human-readable
-depiction of the bits which comprise a Fleet program. The formal
-syntax is given below:
+\pagebreak
+\section{Introduction}
+
+Fleet compilers and tools work primarily with representations of two
+entities: Ships, Instructions, and Test Cases. In order to promote
+greater interoperability, the FleetTwo Toolchain defines both a Java
+API and a textual file format for each of these.
+
+In the case of ships, this takes the form of the {\tt .ship} file
+format for describing ships and the {\tt ShipDescription} Java class
+which an implementation of Fleet uses to inform the toolchain (such as
+the assembler and compiler) of what ships it contains and how they may
+be used. A library is provided for parsing the textual file format
+into the Java representation.
+
+In the case of instructions, and more generally programs, this takes
+the form of the {\tt .fleet} assembly language file format for
+representing Fleet programs and the {\tt Instruction} and {\tt
+ CodeBag} Java classes for representing programs and manipulating
+them. A library is provided for parsing Fleet assembly language
+programs into {\tt CodeBag}s of {\tt Instruction}s, and for writing
+those objects back out as text.
+
+Finally, the FleetTwo Toolchain defines a very simple debugging
+interface, {\tt Device}, which lets a program dispatch a codebag to a
+running Fleet chip and read back the words which arrive at its {\tt
+ Debug} port. A test harness has been written which makes no
+assumptions about the device under test other than that it supports
+this debugging interface and that it is capable of describing itself
+via the {\tt ShipDescription} API. By meeting these relatively minor
+requirements, a new Fleet implementation can immediately take
+advantage of a great deal of prebuilt testing infrastructure. This
+API has been implemented and is fully functional for both the software
+interpreter implementation of Fleet and the FPGA simulation of Fleet.
-\verbatiminput{fleet.g}
\pagebreak
-\section*{FleetDoc}
+\section{Representing Ships}
+\subsection{Ship Description Files (FleetDoc)}
Inspired by JavaDoc, the Fleet software toolchain includes a tool
called {\tt FleetDoc}, which processes {\it ship description files}
the {\tt .ship} files.
\pagebreak
-\subsection*{An Example FleetDoc File}
+\subsubsection{An Example FleetDoc File}
\begin{verbatim}
ship: BitFifo
\pagebreak
-\section*{Java APIs}
-\subsection*{Representing Code}
-\subsection*{Representing Ships}
+\subsection{Java API for Ship Descriptions}
\pagebreak
-\section*{Misc}
+\section{Representing Machine Code}
+\subsection{Fleet Assembly Language}
+
+The Fleet Assembly language is designed to be a human-readable
+depiction of the bits which comprise a Fleet program.
+
+\subsubsection{Formal Grammar}
+The formal syntax is given below:
+
+\verbatiminput{fleet.g}
+
+\subsubsection{Translation To Machine Code}
+
+Please refer to \cite{ArchMan} for the details of the Fleet
+instruction encoding.
+
+As shown in the grammar above, the start symbol for the grammar ({\tt
+ s}) yields a {\tt Program} surrounded by optional whitespace. A
+program is a sequence of {\tt Directive}s followed by a {\tt
+ CodeBagBody}. A {\tt CodeBagBody} consists of zero or more
+elements, each of which is either a {\tt Fiber} or a (nested) {\tt
+ CodeBagDef}.
+
+A {\tt Fiber} is a set of {\tt Instruction}s which all share a common
+execution point ({\tt Pump}). Each instruction can be a {\tt unclog},
+{\tt clog}, {\tt kill}, {\tt literal}, or a set of {\tt Command}s. It
+should be fairly clear how to translate all but the last sort of
+instruction into machine code, based on the encodings in
+\cite{ArchMan}. Take particular note of the fact that {\tt literal}s
+may have a {\tt RequeueCount} but not a {\tt RepeatCount}.
+
+The repetition count for an instruction is placed in square brackets
+and prefixes the instruction. The requeueing count for an instruction
+is placed at the end of the instruction because, {\it conceptually},
+requeueing takes place after the instruction executes.
+
+A {\tt Command} is either {\tt wait}, {\tt nop}, {\tt discard}, {\tt
+ recieve}, {\tt take}, {\tt deliver}, {\tt send}, {\tt sendto}, {\tt
+ notify}, or {\tt notifyLast}. These are compiled as shown below:
+
+\begin{itemize}
+\item[\tt wait] is valid only on an inbox, and sets {\tt Ti=1}
+\item[\tt nop] is not valid in combination with any other command; it sets all control bits to {\tt 0}
+\item[\tt discard] sets {\tt Di=1,Dc=0}
+\item[\tt recieve] is valid only on an input port, and sets {\tt Di=1,Dc=1}
+\item[\tt take] is valid only on an output port, and sets {\tt Di=1,Dc=1}
+\item[\tt deliver] is valid only on an input port, and sets {\tt Do=1}
+\item[\tt send] is valid only on an output port, and sets {\tt Do=1,To=1}
+\item[\tt sendto] is valid only on an output port, and sets {\tt Do=1}
+\item[\tt notify] sets {\tt To=1} and is not valid in combination with {\tt send} or {\tt sendto}
+\item[\tt notifyLast] sets {\tt To=1,Ig=1} and is not valid in combination with {\tt send} or {\tt sendto}
+\end{itemize}
+
+It is an error to specify two commands within a single instruction if
+both of the commands attempt to set the same bit (even if they attempt
+to set it to the same value).
+
+Note that un-named (``anonymous'') codebags may appear as literals.
+This means that it is possible to write interesting programs such as
+the one below:
\begin{verbatim}
-- sequencing guarantees
-- codebag format
-- behavior when token arrives at data port, vice versa
-- overlapping codebags
+#expect 3
+
+#ship debug : Debug
+#ship memory : Memory
+
+memory.inCBD: literal {
+ memory.inCBD: literal {
+ memory.inCBD: literal {
+ debug.in:
+ literal 3;
+ deliver;
+ }; deliver;
+ }; deliver;
+ }; deliver;
\end{verbatim}
+
+
+
+\pagebreak
+\subsection{Java API for Fleet Machine Code}
+
+\pagebreak
+\section{Test Cases}
+\subsection{Test Case File Format}
+\subsection{Java API for Controlling Device Under Test}
+
\end{document}
projects / fleet.git / commitdiff