doc/toolchain.tex

   1 \documentclass[10pt,oneside]{article}
   2 \reversemarginpar
   3 \usepackage[titles]{tocloft}
   4 \usepackage{palatino}
   5 \usepackage{wrapfig}
   6 \usepackage{epsfig}
   7 \usepackage{verbatim}
   8 \usepackage{parskip}
   9 \usepackage{register}
  10 \usepackage{bytefield}
  11 \usepackage[colorlinks=true, pdfstartview=FitV, linkcolor=blue, citecolor=blue, urlcolor=blue]{hyperref}
  12 \renewcommand{\ttdefault}{cmtt}
  13 \title{The FleetTwo Toolchain Manual\\{\normalsize A Compiler Writer's View of Fleet}}
  14 \begin{document}
  15 \maketitle
  16
  17 \begin{thebibliography}{[GDG01]}
  18 \bibitem[ArchMan]{ArchMan}
  19   {\it The FleetTwo Architecture Manual}
  20 \end{thebibliography}
  21
  22
  23 \vspace{3cm}
  24 \begin{abstract}
  25 Fleet compilers and tools work primarily with representations of two
  26 entities: Ships, Instructions, and Test Cases.  In order to promote
  27 greater interoperability, the FleetTwo Toolchain defines both a Java
  28 API and a textual file format for each of these.
  29 \end{abstract}
  30
  31 \vfill
  32 \fbox{\parbox{5in}{\footnotesize
  33 \begin{center}
  34 The software described in this memo may be obtained using
  35 \href{http://www.darcs.net/}{\tt darcs}, with the command:
  36
  37 {\tt darcs get http://research.cs.berkeley.edu/class/fleet/repos/fleet/}
  38 \end{center}
  39 }}
  40
  41 \pagebreak
  42 \tableofcontents
  43
  44 \pagebreak
  45 \section{Introduction}
  46
  47 Fleet compilers and tools work primarily with representations of two
  48 entities: Ships, Instructions, and Test Cases.  In order to promote
  49 greater interoperability, the FleetTwo Toolchain defines both a Java
  50 API and a textual file format for each of these.
  51
  52 In the case of ships, this takes the form of the {\tt .ship} file
  53 format for describing ships and the {\tt ShipDescription} Java class
  54 which an implementation of Fleet uses to inform the toolchain (such as
  55 the assembler and compiler) of what ships it contains and how they may
  56 be used.  A library is provided for parsing the textual file format
  57 into the Java representation.
  58
  59 In the case of instructions, and more generally programs, this takes
  60 the form of the {\tt .fleet} assembly language file format for
  61 representing Fleet programs and the {\tt Instruction} and {\tt
  62   CodeBag} Java classes for representing programs and manipulating
  63 them.  A library is provided for parsing Fleet assembly language
  64 programs into {\tt CodeBag}s of {\tt Instruction}s, and for writing
  65 those objects back out as text.
  66
  67 Finally, the FleetTwo Toolchain defines a very simple debugging
  68 interface, {\tt Device}, which lets a program dispatch a codebag to a
  69 running Fleet chip and read back the words which arrive at its {\tt
  70   Debug} port.  A test harness has been written which makes no
  71 assumptions about the device under test other than that it supports
  72 this debugging interface and that it is capable of describing itself
  73 via the {\tt ShipDescription} API.  By meeting these relatively minor
  74 requirements, a new Fleet implementation can immediately take
  75 advantage of a great deal of prebuilt testing infrastructure.  This
  76 API has been implemented and is fully functional for both the software
  77 interpreter implementation of Fleet and the FPGA simulation of Fleet.
  78
  79
  80 \pagebreak
  81 \section{Representing Ships}
  82 \subsection{Ship Description Files (FleetDoc)}
  83
  84 Inspired by JavaDoc, the Fleet software toolchain includes a tool
  85 called {\tt FleetDoc}, which processes {\it ship description files}
  86 with the extension {\tt .ship}.  These files contain sections for:
  87
  88 \begin{itemize}
  89 \item The name of the ship
  90 \item A list of its ports
  91 \item A prose description of the ship
  92 \item A list of the constants associated with a ship
  93 \item Java source code for a software simulation of the ship
  94 \item Verilog source code for an FPGA simulation of the ship
  95 \item A test case for the ship
  96 \item A list of the contributors to all of the above
  97 \end{itemize}
  98
  99 Keeping all of this information in a single file ensures that changes
 100 to one item -- such as the list of ports -- are propagated to the
 101 other items -- such as the verilog code for simulation purposes.
 102
 103 Keeping this information in {\it machine-readable} format makes it
 104 possible to automatically generate tools which depend on the precise
 105 details of ship ports (such as the Fleet assembler) without the risk
 106 inherent in manual synchronization.
 107
 108 The latter half of the architecture manual \cite{ArchMan} -- including
 109 the ship diagrams -- is generated automatically from the contents of
 110 the {\tt .ship} files.
 111
 112 \pagebreak
 113 \subsubsection{An Example FleetDoc File}
 114 \begin{verbatim}
 115 ship: BitFifo
 116
 117 == Ports ===========================================================
 118 in:   in
 119 in:   inOp
 120   constant lsbFirst: ....................................1
 121   constant msbFirst: ....................................0
 122   constant drop:     .............................uuuuuu..
 123   constant take:     .......................uuuuuu........
 124 ...
 125
 126 == TeX ==============================================================
 127 The BitFifo internally stores some number of bits in a fifo structure.
 128 Its capacity is guaranteed to be at least two full machine words or
 129 more.
 130 ...
 131
 132 == Fleeterpreter ====================================================
 133 public void service() {
 134   if (box_inOp.dataReadyForShip() && box_in.dataReadyForShip()) {
 135   ...
 136
 137 == FPGA ==============================================================
 138 always @(posedge clk) begin
 139   if (!in_r    && in_a)     in_a    <= 0;
 140   if (!inOp_r  && inOp_a)   inOp_a  <= 0;
 141   ...
 142
 143 == Test ==============================================================
 144 #expect 1
 145 #expect 68719476736
 146 #ship debug        : Debug
 147 #ship bitfifo      : BitFifo
 148
 149 bitfifo.outOp:      literal BitFifo.outOp[take=37]; [*] deliver;
 150 ...
 151
 152 == Contributors =========================================================
 153 Amir Kamil <kamil@cs.berkeley.edu>
 154 Adam Megacz <megacz@cs.berkeley.edu>
 155 \end{verbatim}
 156
 157
 158 \pagebreak
 159 \subsection{Java API for Ship Descriptions}
 160
 161 \pagebreak
 162 \section{Representing Machine Code}
 163 \subsection{Fleet Assembly Language}
 164
 165 The Fleet Assembly language is designed to be a human-readable
 166 depiction of the bits which comprise a Fleet program.
 167
 168 \subsubsection{Formal Grammar}
 169 The formal syntax is given below:
 170
 171 \verbatiminput{fleet.g}
 172
 173 \subsubsection{Translation To Machine Code}
 174
 175 Please refer to \cite{ArchMan} for the details of the Fleet
 176 instruction encoding.
 177
 178 As shown in the grammar above, the start symbol for the grammar ({\tt
 179   s}) yields a {\tt Program} surrounded by optional whitespace.  A
 180 program is a sequence of {\tt Directive}s followed by a {\tt
 181   CodeBagBody}.  A {\tt CodeBagBody} consists of zero or more
 182 elements, each of which is either a {\tt Fiber} or a (nested) {\tt
 183   CodeBagDef}.
 184
 185 A {\tt Fiber} is a set of {\tt Instruction}s which all share a common
 186 execution point ({\tt Pump}).  Each instruction can be a {\tt unclog},
 187 {\tt clog}, {\tt kill}, {\tt literal}, or a set of {\tt Command}s.  It
 188 should be fairly clear how to translate all but the last sort of
 189 instruction into machine code, based on the encodings in
 190 \cite{ArchMan}.  Take particular note of the fact that {\tt literal}s
 191 may have a {\tt RequeueCount} but not a {\tt RepeatCount}.
 192
 193 The repetition count for an instruction is placed in square brackets
 194 and prefixes the instruction.  The requeueing count for an instruction
 195 is placed at the end of the instruction because, {\it conceptually},
 196 requeueing takes place after the instruction executes.
 197
 198 A {\tt Command} is either {\tt wait}, {\tt nop}, {\tt discard}, {\tt
 199   recieve}, {\tt take}, {\tt deliver}, {\tt send}, {\tt sendto}, {\tt
 200   notify}, or {\tt notifyLast}.  These are compiled as shown below:
 201
 202 \begin{itemize}
 203 \item[\tt wait] is valid only on an inbox, and sets {\tt Ti=1}
 204 \item[\tt nop] is not valid in combination with any other command; it sets all control bits to {\tt 0}
 205 \item[\tt discard] sets {\tt Di=1,Dc=0}
 206 \item[\tt recieve] is valid only on an input port, and sets {\tt Di=1,Dc=1}
 207 \item[\tt take] is valid only on an output port, and sets {\tt Di=1,Dc=1}
 208 \item[\tt deliver] is valid only on an input port, and sets {\tt Do=1}
 209 \item[\tt send] is valid only on an output port, and sets {\tt Do=1,To=1}
 210 \item[\tt sendto] is valid only on an output port, and sets {\tt Do=1}
 211 \item[\tt notify] sets {\tt To=1} and is not valid in combination with {\tt send} or {\tt sendto}
 212 \item[\tt notifyLast] sets {\tt To=1,Ig=1} and is not valid in combination with {\tt send} or {\tt sendto}
 213 \end{itemize}
 214
 215 It is an error to specify two commands within a single instruction if
 216 both of the commands attempt to set the same bit (even if they attempt
 217 to set it to the same value).
 218
 219 Note that un-named (``anonymous'') codebags may appear as literals.
 220 This means that it is possible to write interesting programs such as
 221 the one below:
 222
 223 \begin{verbatim}
 224 #expect 3
 225
 226 #ship debug  : Debug
 227 #ship memory : Memory
 228
 229 memory.inCBD: literal {
 230     memory.inCBD: literal {
 231         memory.inCBD: literal {
 232             debug.in:
 233               literal 3;
 234               deliver;
 235           }; deliver;
 236       }; deliver;
 237   }; deliver;
 238 \end{verbatim}
 239
 240
 241
 242
 243 \pagebreak
 244 \subsection{Java API for Fleet Machine Code}
 245
 246 \pagebreak
 247 \section{Test Cases}
 248 \subsection{Test Case File Format}
 249 \subsection{Java API for Controlling Device Under Test}
 250
 251 \end{document}