From: adam Date: Tue, 28 Aug 2007 00:22:54 +0000 (+0100) Subject: major updates to manuals X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=7a9896ade2db76ca658f10fc42020d0fbacbc4e2;p=fleet.git major updates to manuals --- diff --git a/doc/archman.tex b/doc/archman.tex index 888456e..9617822 100644 --- a/doc/archman.tex +++ b/doc/archman.tex @@ -1,5 +1,15 @@ \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} @@ -20,15 +30,27 @@ \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. @@ -49,9 +71,9 @@ necessary to write software and compilers for Fleet. \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 @@ -129,13 +151,13 @@ destinations which can send and recieve only tokens -- not data items \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 @@ -150,10 +172,12 @@ deadlock does not occur. \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} @@ -276,7 +300,9 @@ wait there for a non-{\tt clog} instruction to reach the execution 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} @@ -309,10 +335,7 @@ instructions will be executed until an {\tt unclog} is performed. \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} @@ -331,7 +354,7 @@ in the data latch. \pagebreak -{\bf Normal Instruction (at Execution Point)} +{\bf Normal Instruction} {\tt \begin{bytefield}{26} @@ -351,13 +374,13 @@ in the data latch. \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.} @@ -365,7 +388,7 @@ in the data latch. \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 @@ -392,13 +415,13 @@ if (Count==0) { } } \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 @@ -410,107 +433,87 @@ Note how a ``standing'' instruction is encoded as {\tt Count=1111111} \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 -Adam Megacz -\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} diff --git a/doc/toolchain.tex b/doc/toolchain.tex new file mode 100644 index 0000000..6974e63 --- /dev/null +++ b/doc/toolchain.tex @@ -0,0 +1,128 @@ +\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 +Adam Megacz +\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}