doc/toolchain.tex

   1 \documentclass[10pt,oneside]{article}
   2 \reversemarginpar
   3 \usepackage{palatino}
   4 \usepackage{wrapfig}
   5 \usepackage{epsfig}
   6 \usepackage{verbatim}
   7 \usepackage{parskip}
   8 \usepackage{register}
   9 \usepackage{bytefield}
  10 \usepackage[colorlinks=true, pdfstartview=FitV, linkcolor=blue, citecolor=blue, urlcolor=blue]{hyperref}
  11 \renewcommand{\ttdefault}{cmtt}
  12 \title{The FleetTwo Toolchain Manual\\{\normalsize A Compiler Writer's View of Fleet}}
  13 \begin{document}
  14 \maketitle
  15
  16 \begin{thebibliography}{[GDG01]}
  17 \bibitem[ArchMan]{ArchMan}
  18   {\it The FleetTwo Architecture Manual}
  19 \end{thebibliography}
  20
  21 \vspace{3cm}
  22 \begin{abstract}
  23 FIXME
  24 \end{abstract}
  25
  26
  27 \pagebreak
  28 \section*{Fleet Assembly Language}
  29
  30 The Fleet Assembly language is designed to be a human-readable
  31 depiction of the bits which comprise a Fleet program.  The formal
  32 syntax is given below:
  33
  34 \verbatiminput{fleet.g}
  35
  36 \pagebreak
  37 \section*{FleetDoc}
  38
  39 Inspired by JavaDoc, the Fleet software toolchain includes a tool
  40 called {\tt FleetDoc}, which processes {\it ship description files}
  41 with the extension {\tt .ship}.  These files contain sections for:
  42
  43 \begin{itemize}
  44 \item The name of the ship
  45 \item A list of its ports
  46 \item A prose description of the ship
  47 \item A list of the constants associated with a ship
  48 \item Java source code for a software simulation of the ship
  49 \item Verilog source code for an FPGA simulation of the ship
  50 \item A test case for the ship
  51 \item A list of the contributors to all of the above
  52 \end{itemize}
  53
  54 Keeping all of this information in a single file ensures that changes
  55 to one item -- such as the list of ports -- are propagated to the
  56 other items -- such as the verilog code for simulation purposes.
  57
  58 Keeping this information in {\it machine-readable} format makes it
  59 possible to automatically generate tools which depend on the precise
  60 details of ship ports (such as the Fleet assembler) without the risk
  61 inherent in manual synchronization.
  62
  63 The latter half of the architecture manual \cite{ArchMan} -- including
  64 the ship diagrams -- is generated automatically from the contents of
  65 the {\tt .ship} files.
  66
  67 \pagebreak
  68 \subsection*{An Example FleetDoc File}
  69 \begin{verbatim}
  70 ship: BitFifo
  71
  72 == Ports ===========================================================
  73 in:   in
  74 in:   inOp
  75   constant lsbFirst: ....................................1
  76   constant msbFirst: ....................................0
  77   constant drop:     .............................uuuuuu..
  78   constant take:     .......................uuuuuu........
  79 ...
  80
  81 == TeX ==============================================================
  82 The BitFifo internally stores some number of bits in a fifo structure.
  83 Its capacity is guaranteed to be at least two full machine words or
  84 more.
  85 ...
  86
  87 == Fleeterpreter ====================================================
  88 public void service() {
  89   if (box_inOp.dataReadyForShip() && box_in.dataReadyForShip()) {
  90   ...
  91
  92 == FPGA ==============================================================
  93 always @(posedge clk) begin
  94   if (!in_r    && in_a)     in_a    <= 0;
  95   if (!inOp_r  && inOp_a)   inOp_a  <= 0;
  96   ...
  97
  98 == Test ==============================================================
  99 #expect 1
 100 #expect 68719476736
 101 #ship debug        : Debug
 102 #ship bitfifo      : BitFifo
 103
 104 bitfifo.outOp:      literal BitFifo.outOp[take=37]; [*] deliver;
 105 ...
 106
 107 == Contributors =========================================================
 108 Amir Kamil <kamil@cs.berkeley.edu>
 109 Adam Megacz <megacz@cs.berkeley.edu>
 110 \end{verbatim}
 111
 112
 113 \pagebreak
 114 \section*{Java APIs}
 115 \subsection*{Representing Code}
 116 \subsection*{Representing Ships}
 117
 118 \pagebreak
 119 \section*{Misc}
 120
 121 \begin{verbatim}
 122 - sequencing guarantees
 123 - codebag format
 124 - behavior when token arrives at data port, vice versa
 125 - overlapping codebags
 126 \end{verbatim}
 127
 128 \end{document}