\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 / blobdiff