\documentclass[10pt,oneside]{article}
\reversemarginpar
+\usepackage{emp}
+\DeclareGraphicsRule{*}{mps}{*}{}
+
+\ifx\pdftexversion\undefined
+\usepackage[dvips]{graphicx}
+\DeclareGraphicsExtensions{.eps}\else
+\usepackage[pdftex]{graphicx}
+\DeclareGraphicsExtensions{.pdf,.png,.mps,.mp}
+\usepackage{epstopdf}
+\fi
\usepackage{palatino}
\usepackage{wrapfig}
\usepackage{epsfig}
\bibitem[IES14]{ies14}
Sutherland, Ivan,
\href{http://research.cs.berkeley.edu/class/fleet/docs/people/ivan.e.sutherland/ies14-Fleet.Definition.pdf}{\it UCB-IES14: The Fleet Definition}
+\bibitem[AM17]{am17}
+ Megacz, Adam,
+ \href{http://research.cs.berkeley.edu/class/fleet/docs/people/adam.megacz/am17-The.Choice.Ship.pdf}{\it UCB-AM17: The Choice Ship}
\bibitem[IES44]{ies44}
Sutherland, Ivan,
\href{http://research.cs.berkeley.edu/class/fleet/docs/people/ivan.e.sutherland/ies44-Fleet.Definition.pdf}{\it UCB-IES44: The Fleet Definition}
+\bibitem[AM25]{am25}
+ Megacz, Adam,
+ \href{http://research.cs.berkeley.edu/class/fleet/docs/people/adam.megacz/am25.pdf}{\it UCB-AM25: Opcode Ports}
+\bibitem[AM27]{am27}
+ Megacz, Adam,
+ \href{http://research.cs.berkeley.edu/class/fleet/docs/people/adam.megacz/am27.pdf}{\it UCB-AM27: Bypass Paths}
+\bibitem[IES31]{ies31}
+ Sutherland, Ivan,
+ \href{http://research.cs.berkeley.edu/class/fleet/docs/people/ivan.e.sutherland/ies31-Some.SHIPs.pdf}{\it UCB-IES31: Some Ships}
\bibitem[MS68]{WheelOfReincarnation}
Myer, T. and Sutherland, Ivan, {\it On the Design of Display Processors}
Communications of the ACM, Vol 11, No. 6, June 1968 .
\end{thebibliography}
-\vspace{3cm}
+\vspace{1cm}
\begin{abstract}
This manual attempts to detail all those aspects of Fleet which are
visible to a software programmer or compiler backend.
\section*{Introduction (from \cite{ies02})}
During the past two and a half years, the Fleet architecture has gone
-through massive changes and improvements. In spite of this, however,
-the fundamental idea behind Fleet remains unchanged. As Sutherland
-writes in the original Berkeley Fleet description \cite{ies02},
+through massive changes and improvements. Nonetheless, the
+fundamental vision remains unchanged. As Sutherland writes in the
+original Berkeley Fleet description \cite{ies02},
{\it
When computers were new, logic and storage were expensive and wires
\end{center}
\vspace{0.3cm}
-The term {\it port} refers to each interface to the ship, the {\it
+The term {\it port} refers to an interface to the ship, the {\it
valve} connecting it to the switch fabric, and the corresponding
sources and destinations on the switch fabric.
Each valve consists of a {\it data latch}, which is as wide as a
single machine word and a {\it pump}, which is a circular fifo of
-instruction-width latches. The contents of the instruction fifo
+instruction-width latches. The values in the instruction fifo
control the data latch, as future chapters will explain.
Note that the pump in each valve has a destination of its own, and
\subsection*{Path (12 bits)}
-These bits appear physically within the switch fabric, and have
-``address bit timing.'' The {\tt T} bit is the ``tokenhood'' bit; if
-set, this packet represents a token and it does not cause the switch
-fabric data latches to fire.
+These bits appear physically within the switch fabric. \footnote{In
+ the Sun Labs implementation, these bits have ``address bit
+ timing.''} The {\tt T} bit is the ``tokenhood'' bit; if set, this
+packet represents a token\footnote{In the Sun Labs
+ implementation, this bit inhibits the switch fabric data latches
+ from firing.}
{\tt\footnotesize
\begin{bytefield}{49}
point. When this occurs, the instruction at the execution point is
retired and the count field of the {\tt kill} instruction is
decremented. If the {\tt kill} instruction's count was {\tt 0} before
-decrementing, the {\tt kill} instruction is retired.
+decrementing, the {\tt kill} instruction is retired. The programmer
+is assured that a kill instruction with a count of $n$ will kill $n$
+{\it consecutive} instructions.
\vspace{0.3cm}
{\bf Clog}
\end{bytefield}}
When an {\tt unclog} instruction reaches the insertion point, it will wait
there until a {\tt clog} instruction is at the execution point. When
-this occurs, both instructions retire. {\it Note:} this means
-that if an {\tt unclog} instruction enters the instruction fifo
-without a {\tt clog} ahead of it, the pump's insertion point will become
-irretrievably blocked.
+this occurs, both instructions retire.
\vspace{0.3cm}
{\bf Literal}
\pagebreak
-{\bf Normal Instruction (at Execution Point)}
+{\bf Normal Instruction}
{\tt
\begin{bytefield}{26}
\begin{itemize}
- \item [\tt Ti] ({\bf Token Input}) wait for a token and accept
- it\footnote{{\tt Ti}=1,{\tt Di}=1 is invalid on inbox.}
+ \item [\tt Ti] ({\bf Token Input}) wait for a token and acknowledge
+ it\footnote{{\tt Ti}=1,{\tt Di}=1 is invalid on input port.}
- \item [\tt Di] ({\bf Data Input}) wait for a datum and accept it.
+ \item [\tt Di] ({\bf Data Input}) wait for a datum and acknowledge it.
\item [\tt Dc] ({\bf Data Capture}) capture (latch) the accepted
- datum. This bit is ignored if the incoming packet is
+ datum in the data latch. This bit is ignored if the incoming packet is
a token. \footnote{ Note that {\tt Di}=0,{\tt Dc}=1
is meaningless and therefore reserved for other
uses.}
\item [\tt Do] ({\bf Data Output}) emit a datum.
\item [\tt To] ({\bf Token Output}) emit a token.\footnote{ {\tt To}=1,{\tt
- Do}=1 have special meaning on an outbox.}
+ Do}=1 have special meaning on an output port.}
\item [\tt Ig] ({\bf Ignore {\tt To} Until Last Iteration}) ignore
the {\tt To} bit unless {\tt Count=0} \footnote{{\tt
}
}
\end{verbatim}
-Note how a ``standing'' instruction is encoded as {\tt Count=1111111}
+Note how a ``standing'' instruction is encoded as {\tt Count=MAX\_COUNT}
\item [\tt Dest] ({\bf Data/Token Destination})
Normally, this field is copied into the address portion of any
- outgoing packet ({\tt Do} on an outbox or {\tt To}).
+ outgoing packet ({\tt Do} on an output port or {\tt To} on either).
- However, in the special case of an outbox, if {\tt Do=1,To=1}, then
+ However, in the special case of an output port, if {\tt Do=1,To=1}, then
the {\it most significant} {\tt 11} bits of the value in the {\it
data register} are used as a destination address instead.
%\footnote{This
\pagebreak
-\section*{Fleet Assembly Language}
-
-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:
-
-\verbatiminput{fleet.g}
-
-\pagebreak
-\section*{FleetDoc}
-
-Inspired by JavaDoc, the Fleet software toolchain includes a tool
-called {\tt FleetDoc}, which processes {\it ship description files}
-(with the extension {\tt .ship}). These files contain sections for:
-
-\begin{itemize}
-\item The name of the ship
-\item A list of its ports
-\item A prose description of the ship
-\item A list of the constants associated with a ship
-\item Java source code for a software simulation of the ship
-\item Verilog source code for an FPGA simulation of the ship
-\item A test case for the ship
-\item A list of the contributors to all of the above
-\end{itemize}
-
-Keeping all of this information in a single file ensures that changes
-to one item (such as the list of ports) are propagated to the other
-items (such as the verilog code for simulation purposes).
-
-Keeping this information in {\it machine-readable} format makes it
-possible to automatically generate tools which depend on the precise
-details of ship ports (such as the Fleet assembler) without the risk
-inherent in manual synchronization of the spec with the
-implementation.
-
-The latter half of this manual is generated automatically from the
-contents of the {\tt .ship} files.
-
-\pagebreak
-\subsection*{An Example FleetDoc File}
-\begin{verbatim}
-ship: BitFifo
-
-== Ports ===========================================================
-in: in
-in: inOp
- constant lsbFirst: ....................................1
- constant msbFirst: ....................................0
- constant drop: .............................uuuuuu..
- constant take: .......................uuuuuu........
-...
-
-== TeX ==============================================================
-The BitFifo internally stores some number of bits in a fifo structure.
-Its capacity is guaranteed to be at least two full machine words or
-more.
-...
-
-== Fleeterpreter ====================================================
-public void service() {
- if (box_inOp.dataReadyForShip() && box_in.dataReadyForShip()) {
- ...
-
-== FPGA ==============================================================
-always @(posedge clk) begin
- if (!in_r && in_a) in_a <= 0;
- if (!inOp_r && inOp_a) inOp_a <= 0;
- ...
-
-== Test ==============================================================
-#expect 1
-#expect 68719476736
-#ship debug : Debug
-#ship bitfifo : BitFifo
-
-bitfifo.outOp: literal BitFifo.outOp[take=37]; [*] deliver;
-...
-
-== Contributors =========================================================
-Amir Kamil <kamil@cs.berkeley.edu>
-Adam Megacz <megacz@cs.berkeley.edu>
-\end{verbatim}
-
-
-\pagebreak
-\section*{Java APIs}
-\subsection*{Representing Code}
-\subsection*{Representing Ships}
-
-\pagebreak
-\section*{Misc}
+\section*{Opcodes}
+
+Opcodes, as specified in \cite{am25}, are not yet implemented, but
+should be.
+
+\section*{Bypasses}
+
+Bypasses, as specified in \cite{am27}, are not yet implemented, but
+should be.
+
+\section*{Sequencing Guarantees}
+
+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}.
+
+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.
+Any code which dispatches a codebag {\it must} ensure that the
+instructions within a fiber reach their pump in the order in which
+they appear in the fiber. This is known as the {\it instruction
+ sequence guarantee}. Typically the software dispatching a codebag
+will take advantage of the source sequence guarantee in order to
+fulfill the instruction sequence guarantee.
+
+\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
+fibers in such a way that the code bags overlap, sharing memory words
+for these fibers. The codebag descriptors for the two bags will then
+have different addresses and/or sizes, but the ranges which they
+encompass will overlap.
+
+\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
+output port's pump to execute a {\tt send} (not {\tt sendto})
+instruction, which is encoded as {\tt Do=1,To=1}. Because
+instructions are encoded in such a way that their {\tt Instruction
+ Path} appears in the upper 11 bits, the {\tt send} mechanism will
+correctly route the instruction to the pump which ought to execute it.
+
+Currently the {\tt inCBD} port of the {\tt Memory} ship is ideally
+suited for this purpose, although a similar effect can easily be
+achieved using the {\tt BitFifo} ship in conjunction with the {\tt
+ Memory} ship. The only disadvantage to this arrangement is that the
+{\tt out} port must execute {\tt send} a certain number of times, and
+that number of times is determined by the {\tt size} field of the
+codebag descriptor. Unfortunately this value is not known at compile
+time, so it cannot be encoded as a repeat count on the instruction at
+the {\tt out} port. The typical solution is to place a standing ({\tt
+ count=$\infty$}) {\tt send} instruction at the {\tt out} port of one
+{\tt Memory} ship, and reserve that ship exclusively for dispatching
+code bags.
+
+Note that instructions are encoded relative to a particular dispatch
+output port. That is, the {\tt Instruction Path} field of the
+instruction specifies a path to the desired execution pump -- but this
+path is also specified with respect to some source. Therefore the
+instruction can only be correctly dispatched from that particular
+source. However, it is a fairly simple matter two write a software
+program which can ``relocate'' a codebag by replacing the {\tt
+ Instruction Path} fields as needed.
+
+\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
+had been sent to that destination.
+
+When a token is sent to a destination which expects a data item, such
+as a pump destination or an input port destination, the effect will be
+the same as if a data item {\it having an undefined value} were sent
+to that destination. In other words, the programmer has no completely
+reliable mechanism for distinguishing between tokens and data items.
-\begin{verbatim}
-- sequencing guarantees
-- codebag format
-- behavior when token arrives at data port, vice versa
-- overlapping codebags
-\end{verbatim}
-\pagebreak
\section*{Future Directions}
\subsection*{The Role of the Count Field}
--- /dev/null
+\documentclass[10pt,oneside]{article}
+\reversemarginpar
+\usepackage{palatino}
+\usepackage{wrapfig}
+\usepackage{epsfig}
+\usepackage{verbatim}
+\usepackage{parskip}
+\usepackage{register}
+\usepackage{bytefield}
+\usepackage[colorlinks=true, pdfstartview=FitV, linkcolor=blue, citecolor=blue, urlcolor=blue]{hyperref}
+\renewcommand{\ttdefault}{cmtt}
+\title{The FleetTwo Toolchain Manual\\{\normalsize A Compiler Writer's View of Fleet}}
+\begin{document}
+\maketitle
+
+\begin{thebibliography}{[GDG01]}
+\bibitem[ArchMan]{ArchMan}
+ {\it The FleetTwo Architecture Manual}
+\end{thebibliography}
+
+\vspace{3cm}
+\begin{abstract}
+FIXME
+\end{abstract}
+
+
+\pagebreak
+\section*{Fleet Assembly Language}
+
+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:
+
+\verbatiminput{fleet.g}
+
+\pagebreak
+\section*{FleetDoc}
+
+Inspired by JavaDoc, the Fleet software toolchain includes a tool
+called {\tt FleetDoc}, which processes {\it ship description files}
+with the extension {\tt .ship}. These files contain sections for:
+
+\begin{itemize}
+\item The name of the ship
+\item A list of its ports
+\item A prose description of the ship
+\item A list of the constants associated with a ship
+\item Java source code for a software simulation of the ship
+\item Verilog source code for an FPGA simulation of the ship
+\item A test case for the ship
+\item A list of the contributors to all of the above
+\end{itemize}
+
+Keeping all of this information in a single file ensures that changes
+to one item -- such as the list of ports -- are propagated to the
+other items -- such as the verilog code for simulation purposes.
+
+Keeping this information in {\it machine-readable} format makes it
+possible to automatically generate tools which depend on the precise
+details of ship ports (such as the Fleet assembler) without the risk
+inherent in manual synchronization.
+
+The latter half of the architecture manual \cite{ArchMan} -- including
+the ship diagrams -- is generated automatically from the contents of
+the {\tt .ship} files.
+
+\pagebreak
+\subsection*{An Example FleetDoc File}
+\begin{verbatim}
+ship: BitFifo
+
+== Ports ===========================================================
+in: in
+in: inOp
+ constant lsbFirst: ....................................1
+ constant msbFirst: ....................................0
+ constant drop: .............................uuuuuu..
+ constant take: .......................uuuuuu........
+...
+
+== TeX ==============================================================
+The BitFifo internally stores some number of bits in a fifo structure.
+Its capacity is guaranteed to be at least two full machine words or
+more.
+...
+
+== Fleeterpreter ====================================================
+public void service() {
+ if (box_inOp.dataReadyForShip() && box_in.dataReadyForShip()) {
+ ...
+
+== FPGA ==============================================================
+always @(posedge clk) begin
+ if (!in_r && in_a) in_a <= 0;
+ if (!inOp_r && inOp_a) inOp_a <= 0;
+ ...
+
+== Test ==============================================================
+#expect 1
+#expect 68719476736
+#ship debug : Debug
+#ship bitfifo : BitFifo
+
+bitfifo.outOp: literal BitFifo.outOp[take=37]; [*] deliver;
+...
+
+== Contributors =========================================================
+Amir Kamil <kamil@cs.berkeley.edu>
+Adam Megacz <megacz@cs.berkeley.edu>
+\end{verbatim}
+
+
+\pagebreak
+\section*{Java APIs}
+\subsection*{Representing Code}
+\subsection*{Representing Ships}
+
+\pagebreak
+\section*{Misc}
+
+\begin{verbatim}
+- sequencing guarantees
+- codebag format
+- behavior when token arrives at data port, vice versa
+- overlapping codebags
+\end{verbatim}
+
+\end{document}