\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}
