From: adam Date: Tue, 28 Aug 2007 08:57:10 +0000 (+0100) Subject: more archman updates X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=20e2056f1af4e3a1c10eb1e95a0bc8ee4e870159;p=fleet.git more archman updates --- diff --git a/doc/archman.tex b/doc/archman.tex index 9617822..5f669ba 100644 --- a/doc/archman.tex +++ b/doc/archman.tex @@ -1,5 +1,6 @@ \documentclass[10pt,oneside]{article} \reversemarginpar +\usepackage[titles]{tocloft} \usepackage{emp} \DeclareGraphicsRule{*}{mps}{*}{} @@ -67,8 +68,21 @@ necessary to write software and compilers for Fleet. \end{abstract} +%\vfill +%\fbox{\parbox{5in}{\footnotesize +%\begin{center} +%The software described in this memo may be obtained using +%\href{http://www.darcs.net/}{\tt darcs}, with the command: +% +%{\tt darcs get http://research.cs.berkeley.edu/class/fleet/repos/fleet/} +%\end{center} +%}} + +\pagebreak +\tableofcontents + \pagebreak -\section*{Introduction (from \cite{ies02})} +\section{Introduction (from \cite{ies02})} During the past two and a half years, the Fleet architecture has gone through massive changes and improvements. Nonetheless, the @@ -127,7 +141,7 @@ logic makes concurrency available if we can figure out how to use it. \pagebreak -\section*{The Programmer's View of The Ship-Fabric Interface} +\section{The Programmer's View of The Ship-Fabric Interface} The role of the Fleet switch fabric is to carry {\it packets} from {\it sources} to {\it destinations}. @@ -168,9 +182,9 @@ deadlock does not occur. \pagebreak -\section*{Data Formats} +\section{Data Formats} -\subsection*{Path (12 bits)} +\subsection{Path (12 bits)} These bits appear physically within the switch fabric. \footnote{In the Sun Labs implementation, these bits have ``address bit @@ -188,7 +202,7 @@ packet represents a token\footnote{In the Sun Labs \end{bytefield} } -\subsection*{Data Word In Memory (37 bits)} +\subsection{Data Word In Memory (37 bits)} A word of data is 37 bits wide. @@ -200,7 +214,7 @@ A word of data is 37 bits wide. \end{bytefield} } -\subsection*{Packet In Flight (49 bits)} +\subsection{Packet In Flight (49 bits)} {\tt\footnotesize \begin{bytefield}{49} @@ -211,7 +225,7 @@ A word of data is 37 bits wide. \end{bytefield} } -\subsection*{Instruction In Memory (37 bits)} +\subsection{Instruction In Memory (37 bits)} An instruction must be no wider than a memory word. The next section explains the bits in greater detail. The {\tt Instruction Path} is @@ -238,7 +252,7 @@ the instruction. \end{bytefield} } -\subsection*{Instruction Packet In Flight (49 bits)} +\subsection{Instruction Packet In Flight (49 bits)} Note that Fleet simply copies the {\tt Instruction Path} field, bit for bit, into the packet {\tt Path} field in order to ``dispatch'' an @@ -266,7 +280,7 @@ instruction. \setlength{\bitwidth}{5mm} \pagebreak -\section*{Instruction Formats} +\section{Instruction Formats} \begin{wrapfigure}{R}{2in} \epsfig{file=locations,width=2in} \vspace{-0.4in} @@ -283,6 +297,7 @@ successor of the execution point. \vspace{0.3cm} {\bf Kill} +\addcontentsline{toc}{subsection}{Kill} {\tt \begin{bytefield}{26} @@ -306,6 +321,7 @@ is assured that a kill instruction with a count of $n$ will kill $n$ \vspace{0.3cm} {\bf Clog} +\addcontentsline{toc}{subsection}{Clog} {\tt \begin{bytefield}{26} @@ -322,6 +338,7 @@ instructions will be executed until an {\tt unclog} is performed. \vspace{0.3cm} {\bf UnClog} +\addcontentsline{toc}{subsection}{UnClog} {\tt \begin{bytefield}{26} @@ -339,6 +356,7 @@ this occurs, both instructions retire. \vspace{0.3cm} {\bf Literal} +\addcontentsline{toc}{subsection}{Literal} {\tt \begin{bytefield}{26} @@ -355,6 +373,7 @@ in the data latch. \pagebreak {\bf Normal Instruction} +\addcontentsline{toc}{subsection}{Normal Instruction} {\tt \begin{bytefield}{26} @@ -433,23 +452,25 @@ Note how a ``standing'' instruction is encoded as {\tt Count=MAX\_COUNT} \pagebreak -\section*{Opcodes} +\section{Opcodes} Opcodes, as specified in \cite{am25}, are not yet implemented, but should be. -\section*{Bypasses} +\section{Bypasses} Bypasses, as specified in \cite{am27}, are not yet implemented, but should be. -\section*{Sequencing Guarantees} +\section{Sequencing Guarantees} +\addcontentsline{toc}{subsection}{Source Sequence Guarantee} 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}. +\addcontentsline{toc}{subsection}{Instruction 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. @@ -460,7 +481,7 @@ they appear in the fiber. This is known as the {\it instruction will take advantage of the source sequence guarantee in order to fulfill the instruction sequence guarantee. -\section*{Code Bags} +\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 @@ -469,7 +490,7 @@ 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} +\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 @@ -501,7 +522,7 @@ 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} +\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 @@ -514,9 +535,9 @@ to that destination. In other words, the programmer has no completely reliable mechanism for distinguishing between tokens and data items. -\section*{Future Directions} +\section{Future Directions} -\subsection*{The Role of the Count Field} +\subsection{The Role of the Count Field} Looking back on the design of the pump, several things are now apparent which were not initially. In particular, it seems that it @@ -544,12 +565,12 @@ particular instruction: \begin{itemize} \item await and acknowledge a token \item await and acknowledge a datum +\item load the awaited datum into the path latch (top 11 bits) \item load the awaited datum into the data latch -\item load the a literal into the data latch -\item load a value indicated by the instruction into the path latch -\item load the top 11 bits of the data latch into the path latch -\item treat the values in the path latch and data latch as a packet and transmit it -\item treat the value in the path latch as a token and transmit it +\item load a literal into the data latch +\item load a literal into the path latch +\item send the value in the data latch along the path in the path latch +\item send a token along the path in the path latch \item set the count register to a literal value \item decrement the count register \item requeue this instruction if {\tt count>0} @@ -566,15 +587,15 @@ latter feature makes it possible to load the data and destination latches from two distinct data items, allowing ships to create, handle, and consume {\it packets} in the form of a pair of data items. -At this point, it boils down to a question of instruction bit -budgeting. Currently we have a separate instruction form for -literals, so that the literal can use bits which are not otherwise -relevant to literal instructions (for example, {\tt Di}). Adding an -additional instruction form for loading the count register would have -similar advantages. +At this point, the remaining decisions are simply a question of +instruction bit budgeting. Currently we have a separate instruction +form for literals, so that the literal can use bits which are not +otherwise relevant to literal instructions (for example, {\tt Di}). +Adding an additional instruction form for loading the count register +would have similar advantages. -\subsection*{For Just a Little Bit More...} +\subsection{For Just a Little Bit More...} Compared to early revisions of the Fleet architecture, the valves of FleetTwo are substantially more powerful. One might ask, why not add @@ -590,20 +611,20 @@ founded in the geometry of VLSI, and indeed, Euclidean space. Ultimately, the instruction stream for any component of a processor must exist in some physical incarnation -- some geometric extent. If the control flow of a program is linear, with no branching, then the -instruction stream has an optimal spatial mapping which is quite -efficient: it is simply laid out in FIFO fashion. +instruction stream has an optimal spatial mapping which is +efficient: simply lay it out as a FIFO. By contrast, however, a program whose instruction stream has -unrestricted branching is logically a {\it tree} structure. Quite -unfortunately, general trees have no efficient mapping onto +unrestricted branching is logically a {\it tree} structure. +Unfortunately, however, general trees have no efficient mapping onto two-dimensional surfaces. By this, I mean that in every possible mapping, there exists some pair of {\it logically adjacent} instructions whose {\it physical distance} is proportional to the size of the entire program, rather than some constant factor irrespective of the program size. Therefore I conclude that the spatial mapping of a program with unrestricted branching is in an entirely different -class than that of programs with linear control flow. I choose this -distinction as the basis for limiting our valves to linear control +class than that of programs with linear control flow, and I choose this +distinction as the basis for limiting the valves to linear control flow sequences. A similar argument can be made for looping constructs in which two or more loops may be nested within a single parent loop. @@ -619,9 +640,11 @@ the valves. This might take the form of: I feel that this addition would not risk falling down the slippery slope -- instruction streams with predicated instructions (but not -unrestricted branching) preserve the crucial property that they have -an efficient spatial mapping. Any steps beyond this, however, cross a -fairly fundamental line. +unrestricted branching or nested looping) preserve the crucial +property that they have an efficient spatial mapping. Any steps +beyond this, however, cross a fairly fundamental line. + +\addcontentsline{toc}{section}{Ship Descriptions} diff --git a/doc/toolchain.tex b/doc/toolchain.tex index 6974e63..091bc60 100644 --- a/doc/toolchain.tex +++ b/doc/toolchain.tex @@ -1,5 +1,6 @@ \documentclass[10pt,oneside]{article} \reversemarginpar +\usepackage[titles]{tocloft} \usepackage{palatino} \usepackage{wrapfig} \usepackage{epsfig} @@ -18,23 +19,67 @@ {\it The FleetTwo Architecture Manual} \end{thebibliography} + \vspace{3cm} \begin{abstract} -FIXME +Fleet compilers and tools work primarily with representations of two +entities: Ships, Instructions, and Test Cases. In order to promote +greater interoperability, the FleetTwo Toolchain defines both a Java +API and a textual file format for each of these. \end{abstract} +\vfill +\fbox{\parbox{5in}{\footnotesize +\begin{center} +The software described in this memo may be obtained using +\href{http://www.darcs.net/}{\tt darcs}, with the command: + +{\tt darcs get http://research.cs.berkeley.edu/class/fleet/repos/fleet/} +\end{center} +}} \pagebreak -\section*{Fleet Assembly Language} +\tableofcontents -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: +\pagebreak +\section{Introduction} + +Fleet compilers and tools work primarily with representations of two +entities: Ships, Instructions, and Test Cases. In order to promote +greater interoperability, the FleetTwo Toolchain defines both a Java +API and a textual file format for each of these. + +In the case of ships, this takes the form of the {\tt .ship} file +format for describing ships and the {\tt ShipDescription} Java class +which an implementation of Fleet uses to inform the toolchain (such as +the assembler and compiler) of what ships it contains and how they may +be used. A library is provided for parsing the textual file format +into the Java representation. + +In the case of instructions, and more generally programs, this takes +the form of the {\tt .fleet} assembly language file format for +representing Fleet programs and the {\tt Instruction} and {\tt + CodeBag} Java classes for representing programs and manipulating +them. A library is provided for parsing Fleet assembly language +programs into {\tt CodeBag}s of {\tt Instruction}s, and for writing +those objects back out as text. + +Finally, the FleetTwo Toolchain defines a very simple debugging +interface, {\tt Device}, which lets a program dispatch a codebag to a +running Fleet chip and read back the words which arrive at its {\tt + Debug} port. A test harness has been written which makes no +assumptions about the device under test other than that it supports +this debugging interface and that it is capable of describing itself +via the {\tt ShipDescription} API. By meeting these relatively minor +requirements, a new Fleet implementation can immediately take +advantage of a great deal of prebuilt testing infrastructure. This +API has been implemented and is fully functional for both the software +interpreter implementation of Fleet and the FPGA simulation of Fleet. -\verbatiminput{fleet.g} \pagebreak -\section*{FleetDoc} +\section{Representing Ships} +\subsection{Ship Description Files (FleetDoc)} Inspired by JavaDoc, the Fleet software toolchain includes a tool called {\tt FleetDoc}, which processes {\it ship description files} @@ -65,7 +110,7 @@ the ship diagrams -- is generated automatically from the contents of the {\tt .ship} files. \pagebreak -\subsection*{An Example FleetDoc File} +\subsubsection{An Example FleetDoc File} \begin{verbatim} ship: BitFifo @@ -111,18 +156,96 @@ Adam Megacz \pagebreak -\section*{Java APIs} -\subsection*{Representing Code} -\subsection*{Representing Ships} +\subsection{Java API for Ship Descriptions} \pagebreak -\section*{Misc} +\section{Representing Machine Code} +\subsection{Fleet Assembly Language} + +The Fleet Assembly language is designed to be a human-readable +depiction of the bits which comprise a Fleet program. + +\subsubsection{Formal Grammar} +The formal syntax is given below: + +\verbatiminput{fleet.g} + +\subsubsection{Translation To Machine Code} + +Please refer to \cite{ArchMan} for the details of the Fleet +instruction encoding. + +As shown in the grammar above, the start symbol for the grammar ({\tt + s}) yields a {\tt Program} surrounded by optional whitespace. A +program is a sequence of {\tt Directive}s followed by a {\tt + CodeBagBody}. A {\tt CodeBagBody} consists of zero or more +elements, each of which is either a {\tt Fiber} or a (nested) {\tt + CodeBagDef}. + +A {\tt Fiber} is a set of {\tt Instruction}s which all share a common +execution point ({\tt Pump}). Each instruction can be a {\tt unclog}, +{\tt clog}, {\tt kill}, {\tt literal}, or a set of {\tt Command}s. It +should be fairly clear how to translate all but the last sort of +instruction into machine code, based on the encodings in +\cite{ArchMan}. Take particular note of the fact that {\tt literal}s +may have a {\tt RequeueCount} but not a {\tt RepeatCount}. + +The repetition count for an instruction is placed in square brackets +and prefixes the instruction. The requeueing count for an instruction +is placed at the end of the instruction because, {\it conceptually}, +requeueing takes place after the instruction executes. + +A {\tt Command} is either {\tt wait}, {\tt nop}, {\tt discard}, {\tt + recieve}, {\tt take}, {\tt deliver}, {\tt send}, {\tt sendto}, {\tt + notify}, or {\tt notifyLast}. These are compiled as shown below: + +\begin{itemize} +\item[\tt wait] is valid only on an inbox, and sets {\tt Ti=1} +\item[\tt nop] is not valid in combination with any other command; it sets all control bits to {\tt 0} +\item[\tt discard] sets {\tt Di=1,Dc=0} +\item[\tt recieve] is valid only on an input port, and sets {\tt Di=1,Dc=1} +\item[\tt take] is valid only on an output port, and sets {\tt Di=1,Dc=1} +\item[\tt deliver] is valid only on an input port, and sets {\tt Do=1} +\item[\tt send] is valid only on an output port, and sets {\tt Do=1,To=1} +\item[\tt sendto] is valid only on an output port, and sets {\tt Do=1} +\item[\tt notify] sets {\tt To=1} and is not valid in combination with {\tt send} or {\tt sendto} +\item[\tt notifyLast] sets {\tt To=1,Ig=1} and is not valid in combination with {\tt send} or {\tt sendto} +\end{itemize} + +It is an error to specify two commands within a single instruction if +both of the commands attempt to set the same bit (even if they attempt +to set it to the same value). + +Note that un-named (``anonymous'') codebags may appear as literals. +This means that it is possible to write interesting programs such as +the one below: \begin{verbatim} -- sequencing guarantees -- codebag format -- behavior when token arrives at data port, vice versa -- overlapping codebags +#expect 3 + +#ship debug : Debug +#ship memory : Memory + +memory.inCBD: literal { + memory.inCBD: literal { + memory.inCBD: literal { + debug.in: + literal 3; + deliver; + }; deliver; + }; deliver; + }; deliver; \end{verbatim} + + + +\pagebreak +\subsection{Java API for Fleet Machine Code} + +\pagebreak +\section{Test Cases} +\subsection{Test Case File Format} +\subsection{Java API for Controlling Device Under Test} + \end{document}