diff options
| -rw-r--r-- | spec/spec.tex | 640 |
1 files changed, 444 insertions, 196 deletions
diff --git a/spec/spec.tex b/spec/spec.tex index f9d4a015..41838f70 100644 --- a/spec/spec.tex +++ b/spec/spec.tex @@ -36,8 +36,8 @@ &\vert &\kws{SInt}(\pd{width}) &\text{Signed Integer}\\ &\vert &\bundleT{\pd{field*}} &\text{Bundle}\\ &\vert &\pds{type}[\ints] &\text{Vector}\\ -\pd{field} &= &\pd{orientation} \id \kw{:} \pd{type} &\text{Bundle Field}\\ -\pd{orientation}&= &\kws{inward} \vert \kws{outward} &\text{Inward/Outward}\\ +\pd{field} &= &\pd{side} \id \kw{:} \pd{type} &\text{Bundle Field}\\ +\pd{side} &= &\kws{female} \vert \kws{male} &\text{Female/Male}\\ \pd{width} &= &\ints &\text{Known Integer Width}\\ &\vert &\kw{?} &\text{Unknown Width}\\ \pd{stmt} &= &\info \kw{wire} \id \kw{:} \pd{type} &\text{Wire Declaration}\\ @@ -61,6 +61,13 @@ &\vert &\info \id &\text{Reference}\\ &\vert &\info \pds{exp}.\id &\text{Subfield}\\ &\vert &\info \pds{exp}.\ints &\text{Subindex}\\ +\end{array} +\] +\[ +\begin{array}{rrll} + &\vert &\info \pds{pad!}(\pds{exp}, \pds{width}) &\text{Generic Pad to Width}\\ + &\vert &\info \pds{pad!-u}(\pds{exp}, \pds{width}) &\text{Unsigned Pad to Width}\\ + &\vert &\info \pds{pad!-s}(\pds{exp}, \pds{width}) &\text{Signed Pad to Width}\\ &\vert &\info \kws{ReadPort}(\ids, \pds{exp}) &\text{Structural Read Port}\\ &\vert &\info \pds{primop}(\pds{exp*}, \ints\text{*}) &\text{Primitive Operation}\\ \pd{info} &= &\text{filename } \kw{:} \text{line} . \text{col} &\text{File Location}\\ @@ -71,33 +78,34 @@ \[ \begin{array}{rll} \pd{primop} &= \\ - &\kws{add} \vert \kws{add-uu} \vert \kws{add-us} \vert \kws{add-su} \vert \kws{add-ss} &\text{Unsigned/Signed Add}\\ -\vert &\kws{sub} \vert \kws{sub-uu} \vert \kws{sub-us} \vert \kws{sub-su} \vert \kws{sub-ss} &\text{Unsigned/Signed Subtract}\\ -\vert &\kws{mul} \vert \kws{mul-uu} \vert \kws{mul-us} \vert \kws{mul-su} \vert \kws{mul-ss} &\text{Unsigned/Signed Multiply}\\ -\vert &\kws{div} \vert \kws{div-uu} \vert \kws{div-us} \vert \kws{div-su} \vert \kws{div-ss} &\text{Unsigned/Signed Divide}\\ -\vert &\kws{rem} \vert \kws{rem-uu} \vert \kws{rem-us} \vert \kws{rem-su} \vert \kws{rem-ss} &\text{Unsigned/Signed Remainder}\\ -\vert &\kws{quo} \vert \kws{quo-uu} \vert \kws{quo-us} \vert \kws{quo-su} \vert \kws{quo-ss} &\text{Unsigned/Signed Quotient}\\ -\vert &\kws{mod} \vert \kws{mod-uu} \vert \kws{mod-us} \vert \kws{mod-su} \vert \kws{mod-ss} &\text{Unsigned/Signed Modulo}\\ -\vert &\kws{add-mod} \vert \kws{add-mod-uu} \vert \kws{add-mod-us} \vert &\text{Unsigned/Signed Add Modulo}\\ - &\kws{add-mod-su} \vert \kws{add-mod-ss} &\\ -\vert &\kws{sub-mod} \vert \kws{sub-mod-uu} \vert \kws{sub-mod-us} \vert &\text{Unsigned/Signed Subtract Modulo}\\ - &\kws{sub-mod-su} \vert \kws{sub-mod-ss} &\\ -\vert &\kws{lt} \vert \kws{lt-uu} \vert \kws{lt-us} \vert \kws{lt-su} \vert \kws{lt-ss} &\text{Unsigned/Signed Less Than}\\ -\vert &\kws{leq} \vert \kws{leq-uu} \vert \kws{leq-us} \vert \kws{leq-su} \vert \kws{leq-ss} &\text{Unsigned/Signed Less or Equal}\\ -\vert &\kws{gt} \vert \kws{gt-uu} \vert \kws{gt-us} \vert \kws{gt-su} \vert \kws{gt-ss} &\text{Unsigned/Signed Greater Than}\\ -\vert &\kws{geq} \vert \kws{geq-uu} \vert \kws{geq-us} \vert \kws{geq-su} \vert \kws{geq-ss} &\text{Unsigned/Signed Greater or Equal}\\ -\vert &\kws{equal} \vert \kws{equal-uu} \vert \kws{equal-ss} \vert \kws{equal-su} \vert \kws{equal-ss} &\text{Unsigned/Signed Equal}\\ -\vert &\kws{mux} \vert \kws{mux-uu} \vert \kws{mux-ss} &\text{Unsigned/Signed Multiplex}\\ -\vert &\kws{pad} \vert \kws{pad-u} \vert \kws{pad-s} &\text{Unsigned/Signed Pad to Length}\\ -\vert &\kws{as} \vert \kws{as-u} \vert \kws{as-s} &\text{Unsigned/Signed Type Cast}\\ -\vert &\kws{shl} \vert \kws{shl-u} \vert \kws{shl-s} &\text{Unsigned/Signed Shift Left}\\ -\vert &\kws{shr} \vert \kws{shr-u} \vert \kws{shr-s} &\text{Unsigned/Signed Shift Right}\\ -\vert &\kws{convert} &\text{Unsigned to Signed Conversion}\\ -\vert &\kws{and} &\text{Unsigned And}\\ -\vert &\kws{or} &\text{Unsigned Or}\\ -\vert &\kws{xor} &\text{Unsigned Xor}\\ -\vert &\kws{concat} &\text{Unsigned Concatenation}\\ -\vert &\kws{bit} \vert \kws{bits} &\text{Single/Multiple Bit Extraction}\\ + &\kws{add} \vert \kws{add-uu} \vert \kws{add-us} \vert \kws{add-su} \vert \kws{add-ss} &\text{Unsigned/Signed Add}\\ +\vert &\kws{sub} \vert \kws{sub-uu} \vert \kws{sub-us} \vert \kws{sub-su} \vert \kws{sub-ss} &\text{Unsigned/Signed Subtract}\\ +\vert &\kws{mul} \vert \kws{mul-uu} \vert \kws{mul-us} \vert \kws{mul-su} \vert \kws{mul-ss} &\text{Unsigned/Signed Multiply}\\ +\vert &\kws{div} \vert \kws{div-uu} \vert \kws{div-us} \vert \kws{div-su} \vert \kws{div-ss} &\text{Unsigned/Signed Divide}\\ +\vert &\kws{rem} \vert \kws{rem-uu} \vert \kws{rem-us} \vert \kws{rem-su} \vert \kws{rem-ss} &\text{Unsigned/Signed Remainder}\\ +\vert &\kws{quo} \vert \kws{quo-uu} \vert \kws{quo-us} \vert \kws{quo-su} \vert \kws{quo-ss} &\text{Unsigned/Signed Quotient}\\ +\vert &\kws{mod} \vert \kws{mod-uu} \vert \kws{mod-us} \vert \kws{mod-su} \vert \kws{mod-ss} &\text{Unsigned/Signed Modulo}\\ +\vert &\kws{add-wrap} \vert \kws{add-wrap-uu} \vert \kws{add-wrap-us} \vert &\text{Unsigned/Signed Add Wrap}\\ + &\kws{add-wrap-su} \vert \kws{add-wrap-ss} &\\ +\vert &\kws{sub-wrap} \vert \kws{sub-wrap-uu} \vert \kws{sub-wrap-us} \vert &\text{Unsigned/Signed Subtract Wrap}\\ + &\kws{sub-wrap-su} \vert \kws{sub-wrap-ss} &\\ +\vert &\kws{lt} \vert \kws{lt-uu} \vert \kws{lt-us} \vert \kws{lt-su} \vert \kws{lt-ss} &\text{Unsigned/Signed Less Than}\\ +\vert &\kws{leq} \vert \kws{leq-uu} \vert \kws{leq-us} \vert \kws{leq-su} \vert \kws{leq-ss} &\text{Unsigned/Signed Less or Equal}\\ +\vert &\kws{gt} \vert \kws{gt-uu} \vert \kws{gt-us} \vert \kws{gt-su} \vert \kws{gt-ss} &\text{Unsigned/Signed Greater Than}\\ +\vert &\kws{geq} \vert \kws{geq-uu} \vert \kws{geq-us} \vert \kws{geq-su} \vert \kws{geq-ss} &\text{Unsigned/Signed Greater or Equal}\\ +\vert &\kws{equal} \vert \kws{equal-uu} \vert \kws{equal-ss} &\text{Unsigned/Signed Equal}\\ +\vert &\kws{mux} \vert \kws{mux-uu} \vert \kws{mux-ss} &\text{Unsigned/Signed Multiplex}\\ +\vert &\kws{pad} \vert \kws{pad-u} \vert \kws{pad-s} &\text{Unsigned/Signed Pad to Length}\\ +\vert &\kws{asUInt} \vert \kws{asUInt-u} \vert \kws{asUInt-s} &\text{Unsigned/Signed Reinterpret Bits as UInt}\\ +\vert &\kws{asSInt} \vert \kws{asSInt-u} \vert \kws{asSInt-s} &\text{Unsigned/Signed Reinterpret Bits as SInt}\\ +\vert &\kws{shl} \vert \kws{shl-u} \vert \kws{shl-s} &\text{Unsigned/Signed Shift Left}\\ +\vert &\kws{shr} \vert \kws{shr-u} \vert \kws{shr-s} &\text{Unsigned/Signed Shift Right}\\ +\vert &\kws{convert} \vert \kws{convert-u} \vert \kws{convert-s} &\text{Unsigned to Signed Conversion}\\ +\vert &\kws{and} &\text{Unsigned And}\\ +\vert &\kws{or} &\text{Unsigned Or}\\ +\vert &\kws{xor} &\text{Unsigned Xor}\\ +\vert &\kws{concat} &\text{Unsigned Concatenation}\\ +\vert &\kws{bit} \vert \kws{bits} &\text{Single/Multiple Bit Extraction}\\ \end{array} \] @@ -118,11 +126,16 @@ Keep in the mind that the above definition is only the {\em abstract} syntax tre \end{array} \] -All FIRRTL circuits are comprised of a flat list of modules, each representing one hardware block. Each module has a given name, a list of ports, and a statement representing the circuit connections within the module. Externally defined modules consist of a given name, and a list of ports, whose types must match the types defined in the associated Verilog. Module names exist in their own namespace, and all modules must have a unique name. The name of the top-level module must be specified for a circuit. +All FIRRTL circuits are comprised of a flat list of modules, each representing one hardware block. +Each module has a given name, a list of ports, and a statement representing the circuit connections within the module. +Externally defined modules consist of a given name, and a list of ports, whose types must match the types defined in the associated Verilog. +Module names exist in their own namespace, and all modules must have a unique name. The name of the top-level module must be specified for a circuit. -A module port is specified by a direction, which may be input or output, a name, and the data type for the port. The port names exist in the identifier namespace for the module, and must be unique. +A module port is specified by a direction, which may be input or output, a name, and the data type for the port. +The port names exist in the identifier namespace for the module, and must be unique. -The special port name, {\em reset}, is used to carry the module reset signal for circuit initialization, and has special meaning. Circuit initialization is described in section \ref{initialization}. +The special port name, {\em reset}, is used to carry the module reset signal for circuit initialization, and has special meaning. +Circuit initialization is described in section \ref{initialization}. \section{Types} @@ -136,7 +149,9 @@ The special port name, {\em reset}, is used to carry the module reset signal for \end{array} \] -There are only two ground types in FIRRTL, an unsigned and a signed integer type. Both of these types require a given bitwidth, which may be some known integer width, which must be non-negative, or an unknown width. Unknown widths are a declaration for the width to be computed by the FIRRTL width inferencer, instead of manually given by the programmer. +There are only two ground types in FIRRTL, an unsigned and a signed integer type. +Both of these types require a given bitwidth, which may be some known integer width, which must be non-negative, or an unknown width. +Unknown widths are a declaration for the width to be computed by the FIRRTL width inferencer, instead of manually given by the programmer. \subsection{Vector Types} \[ @@ -145,11 +160,15 @@ There are only two ground types in FIRRTL, an unsigned and a signed integer type \end{array} \] -Vector types in FIRRTL indicate a structure consisting of multiple elements of some given type. This is akin to array types in the C programming language. Note that the number of elements must be known, and non-negative. +Vector types in FIRRTL indicate a structure consisting of multiple elements of some given type. +This is akin to array types in the C programming language. +Note that the number of elements must be known, and non-negative. -As an example, the type $\kws{UInt}(16)[10]$ indicates a ten element vector of 16-bit unsigned integers. The type $\kws{UInt}(\kws{?})[10]$ indicates a ten element vector of unsigned integers, with unknown and possibly differing bitwidths. +As an example, the type $\kws{UInt}(16)[10]$ indicates a ten element vector of 16-bit unsigned integers. +The type $\kws{UInt}(\kws{?})[10]$ indicates a ten element vector of unsigned integers, with unknown and possibly differing bitwidths. -Vector types may be nested ad infinitum. The type $\kws{UInt}(16)[10][5]$ indicates a five element vector {\em of} ten element vectors of 16-bit unsigned integers. +Vector types may be nested ad infinitum. +The type $\kws{UInt}(16)[10][5]$ indicates a five element vector {\em of} ten element vectors of 16-bit unsigned integers. \subsection{Bundle Types} \[ @@ -159,12 +178,15 @@ Vector types may be nested ad infinitum. The type $\kws{UInt}(16)[10][5]$ indica \end{array} \] -Bundle types in FIRRTL are composite types formed from an ordered sequence of named, nested types. All fields in a bundle must have a given direction, name, and type. The following is an example of a possible type for representing a complex number. +Bundle types in FIRRTL are composite types formed from an ordered sequence of named, nested types. +All fields in a bundle must have a given direction, name, and type. +The following is an example of a possible type for representing a complex number. \[ \bundleT{\kw{output} \text{real } \kw{:} \kws{SInt}(10), \kw{output} \text{imag } \kw{:} \kws{SInt}(10)} \] -It has two fields, real, and imag, both 10-bit signed integers. Here is an example of a possible type for a decoupled port. +It has two fields, real, and imag, both 10-bit signed integers. +Here is an example of a possible type for a decoupled port. \[ \begin{aligned} \{ \kw{output} &\text{data } \kw{:} \kws{UInt}(10), \\ @@ -174,18 +196,25 @@ It has two fields, real, and imag, both 10-bit signed integers. Here is an examp \] It has a data field that is specified to be a 10-bit unsigned integer, a valid signal that must be a 1-bit unsigned integer, and an {\em input} ready signal that must be a 1-bit unsigned integer. -By convention, we specify the directions within a bundle type consistently with how the fields would be defined if they were {\em output} ports for a module. For this reason, the real and imag fields for the complex number bundle type are both specified to have direction \kws{output}. I.e., if a module were to output a complex number, we would declare it to have an output port real, and an output port imag. Similarly, if a module were to output a value using a decoupled protocol, we would declare the module to have an output port, data, which would contain the value itself, an output port, valid, which would indicate when the value is valid, and accept an {\em input} port, ready, from the receiving component, which would indicate when the component is ready to receive the value. +By convention, we specify the directions within a bundle type consistently with how the fields would be defined if they were {\em output} ports for a module. +For this reason, the real and imag fields for the complex number bundle type are both specified to have direction \kws{output}. +I.e., if a module were to output a complex number, we would declare it to have an output port real, and an output port imag. +Similarly, if a module were to output a value using a decoupled protocol, we would declare the module to have an output port, data, which would contain the value itself, an output port, valid, which would indicate when the value is valid, and accept an {\em input} port, ready, from the receiving component, which would indicate when the component is ready to receive the value. -Note that all field names within a bundle type must be unique. The special field name, {\em init}, is reserved for register initialization and is not available to the user. Register initialization is covered in section \ref{initialization}. +Note that all field names within a bundle type must be unique. +The special field name, {\em init}, is reserved for register initialization and is not available to the user. +Register initialization is covered in section \ref{initialization}. -As in the case of vector types, bundle types may also be nested ad infinitum. I.e., the types of the fields themselves may also be bundle types, which will in turn contain more fields, etc. +As in the case of vector types, bundle types may also be nested ad infinitum. +I.e., the types of the fields themselves may also be bundle types, which will in turn contain more fields, etc. \section{Statements} FIRRTL circuit components are instantiated and connected together using {\em statements}. \subsection{Wires} -A wire is a named combinational circuit element that can connected to using the connect statement. A wire with a given name and type can be instantiated with the following statement. +A wire is a named combinational circuit element that can connected to using the connect statement. +A wire with a given name and type can be instantiated with the following statement. \[ \kw{wire} \text{name } \kw{:} \pd{type} \\ \] @@ -193,7 +222,8 @@ A wire is a named combinational circuit element that can connected to using the Declared wires are {\em bidirectional}, which means that they can be used as both an input (by being on the left-hand side of a connect statement), or as an output (by being on the right-hand side of a connect statement). \subsection{Registers} -A register is a named stateful circuit element. A register with a given name and type can be instantiated with the following statement. +A register is a named stateful circuit element. +A register with a given name and type can be instantiated with the following statement. \[ \kw{reg} \text{name } \kw{:} \pd{type} \\ \] @@ -203,34 +233,47 @@ Like wires, registers are also {\em bidirectional}, which means that they can be The distinguished field, {\em init}, is used to specify the initialization value for a register, and is described in section \ref{initialization}. \subsection{Memories} -A memory is a stateful circuit element containing multiple elements. Unlike registers, memories can {\em only} be read from or written to through {\em accessors}. A memory with a given name and type can be instantiated with the following statement. +A memory is a stateful circuit element containing multiple elements. +Unlike registers, memories can {\em only} be read from or written to through {\em accessors}. +A memory with a given name and type can be instantiated with the following statement. \[ \begin{aligned} \kw{mem} \text{name } \kw{:} \pd{type} \\ \end{aligned} \] -Note that, by definition, memories contain multiple elements, and hence {\em must} be declared with a vector type. It is an error to specify any other type for a memory. Additionally, the type for a memory must be completely specified and cannot contain any unknown widths. +Note that, by definition, memories contain multiple elements, and hence {\em must} be declared with a vector type. +It is an error to specify any other type for a memory. +Additionally, the type for a memory must be completely specified and cannot contain any unknown widths. \subsection{Nodes} -A node is simply a named intermediate value in a circuit. A node with a given name and value can be instantiated with the following statement. +A node is simply a named intermediate value in a circuit. +A node with a given name and value can be instantiated with the following statement. \[ \kw{node} \text{name } = \pd{exp} \\ \] -Unlike wires, nodes can only be used in {\em output} directions. They can be connected from, but not connected to. +Unlike wires, nodes can only be used in {\em output} directions. +They can be connected from, but not connected to. \subsection{Accessors} -Accessors are used for either connecting to or from a vector-typed expression, from some {\em variable} index. An accessor can be instantiated with the following statement. +Accessors are used for either connecting to or from a vector-typed expression, from some {\em variable} index. +An accessor can be instantiated with the following statement. \[ \begin{aligned} \kw{accessor} \text{name } \kw{:} \pds{exp}[\text{index}] \\ \end{aligned} \] -Given a name, an expression to access, and the index at which to access, the above statement creates an accessor that may be used for connecting to or from the expression. The expression must have a vector type, and the index must be an unsigned integer. +Given a name, an expression to access, and the index at which to access, the above statement creates an accessor that may be used for connecting to or from the expression. +The expression must have a vector type, and the index must be an unsigned integer. -Note that, though their directions are not explicitly specified, accessors are {\em not} bidirectional. They may be used as outputs, by being on the right-hand side of a connect statement, in which case the accessor acts as a reader from the given expression at the given index. Or they may be used as inputs, by being on the left-hand side of a connect statement, in which case the accessor acts as a writer to the given expression at the given index. An accessor must consistently be used either as an input, or as an output, but not as both. +Note that, though their directions are not explicitly specified, accessors are {\em not} bidirectional. +They may be used as outputs, by being on the right-hand side of a connect statement, in which case the accessor acts as a reader from the given expression at the given index. +Or they may be used as inputs, by being on the left-hand side of a connect statement, in which case the accessor acts as a writer to the given expression at the given index. +An accessor must consistently be used either as an input, or as an output, but not as both. -The following example demonstrates using accessors to read and write to a memory. The accessor, reader, acts as a memory read port that reads from the index specified by the wire i. The accessor, writer, acts as a memory write port that writes 42 to the index specified by wire j. +The following example demonstrates using accessors to read and write to a memory. +The accessor, reader, acts as a memory read port that reads from the index specified by the wire i. +The accessor, writer, acts as a memory write port that writes 42 to the index specified by wire j. \[ \begin{aligned} &\kw{wire} i : \kws{UInt}(5) \\ @@ -243,30 +286,41 @@ The following example demonstrates using accessors to read and write to a memory \end{aligned} \] -As mentioned previously, the only way to read from or write to a memory is through an accessor. But accessors are not restricted to accessing memories. They can be used to access {\em any} vector-valued type. +As mentioned previously, the only way to read from or write to a memory is through an accessor. +But accessors are not restricted to accessing memories. +They can be used to access {\em any} vector-valued type. \subsection{Instances} -An instance refers to a particular instantiation of a FIRRTL module. An instance with some given name, of a given module can be created using the following statement. +An instance refers to a particular instantiation of a FIRRTL module. +An instance with some given name, of a given module can be created using the following statement. \[ \begin{aligned} \kw{inst} \text{name } \kw{of} \text{module} \end{aligned} \] -The ports of an instance may be accessed using the subfield expression. The output ports of an instance may only be used in output positions, e.g. the right-hand side of a connect statement, and the input ports of an instance may only be used in input positions, e.g. the left-hand side of a connect statement. +The ports of an instance may be accessed using the subfield expression. +The output ports of an instance may only be used in output positions, e.g. the right-hand side of a connect statement, and the input ports of an instance may only be used in input positions, e.g. the left-hand side of a connect statement. -There are restrictions upon which modules the user is allowed to instantiate, so as not to create infinitely recursive hardware. We define a module with no instances as a {\em level 0} module. A module containing only instances of {\em level 0} modules is a {\em level 1} module, and a module containing only instances of {\em level 1} or below modules is a {\em level 2} module. In general, a {\em level n} module is only allowed to contain instances of modules of level $n-1$ or below. +There are restrictions upon which modules the user is allowed to instantiate, so as not to create infinitely recursive hardware. +We define a module with no instances as a {\em level 0} module. +A module containing only instances of {\em level 0} modules is a {\em level 1} module, and a module containing only instances of {\em level 1} or below modules is a {\em level 2} module. +In general, a {\em level n} module is only allowed to contain instances of modules of level $n-1$ or below. \subsection{The Connect Statement} -The connect statement is used to specify a physical wired connection between one hardware component to another, and is the most important statement in FIRRTL. The following statement is used to connect the output of some component, to the input of another component. +The connect statement is used to specify a physical wired connection between one hardware component to another, and is the most important statement in FIRRTL. +The following statement is used to connect the output of some component, to the input of another component. \[ \text{input } \kw{:=} \text{output} \] -For a connection to be legal, the types of the two expressions must match. The component on the right-hand side must be able to be used as an output, and the component on the left-hand side must be able to be used as an input. +For a connection to be legal, the types of the two expressions must match. +The component on the right-hand side must be able to be used as an output, and the component on the left-hand side must be able to be used as an input. \subsection{The Conditional Statement} -The conditional statement is used to specify a condition that must be asserted under which a list of statements hold. The condition must be a 1-bit unsigned integer. The following statement states that the {\em conseq} statements hold only when {\em condition} is assert high, otherwise the {\em alt} statements hold instead. +The conditional statement is used to specify a condition that must be asserted under which a list of statements hold. +The condition must be a 1-bit unsigned integer. +The following statement states that the {\em conseq} statements hold only when {\em condition} is assert high, otherwise the {\em alt} statements hold instead. \[ \begin{aligned} \kw{when} \text{condition } \kw{:} \text{conseq } \kw{else :} \text{alt} @@ -276,7 +330,9 @@ The conditional statement is used to specify a condition that must be asserted u Notationally, for convenience, we omit the \kws{else} branch if it is an empty statement. \subsubsection{Initialization Coverage} -Because of the conditional statement, it is possible for wires to be only partially connected to an expression. In the following example, the wire w is connected to 42 when enable is asserted high, but it is not specified what w is connected to when enable is low. This is an illegal FIRRTL circuit, and will throw a \kws{wire not initialized} error during compilation. +Because of the conditional statement, it is possible for wires to be only partially connected to an expression. +In the following example, the wire w is connected to 42 when enable is asserted high, but it is not specified what w is connected to when enable is low. +This is an illegal FIRRTL circuit, and will throw a \kws{wire not initialized} error during compilation. \[ \begin{aligned} &\kw{wire} w : \kws{UInt}(\kws{?}) \\ @@ -286,9 +342,12 @@ Because of the conditional statement, it is possible for wires to be only partia \] \subsubsection{Scoping} -The conditional statement creates a new {\em scope} within its consequent and alternative branches. It is an error to refer to any component declared within a branch after the branch has ended. +The conditional statement creates a new {\em scope} within its consequent and alternative branches. +It is an error to refer to any component declared within a branch after the branch has ended. -Note that there is still only a single identifier namespace in a module. Thus, there cannot be two components with identical names in the same module, {\em even if} they are in separate scopes. This is to facilitate writing transformational passes, by ensuring that the component name and module name is sufficient to uniquely identify a component. +Note that there is still only a single identifier namespace in a module. +Thus, there cannot be two components with identical names in the same module, {\em even if} they are in separate scopes. +This is to facilitate writing transformational passes, by ensuring that the component name and module name is sufficient to uniquely identify a component. \subsection{Statement Groups} Several statements can be grouped into one using the following construct. @@ -297,10 +356,13 @@ Several statements can be grouped into one using the following construct. (\pd{stmt*}) \end{aligned} \] -Ordering is important in a statement group. Later connect statements take precedence over earlier connect statements, and circuit components cannot be referred to before they are instantiated. +Ordering is important in a statement group. +Later connect statements take precedence over earlier connect statements, and circuit components cannot be referred to before they are instantiated. \subsubsection{Last Connect Semantics} -Because of the connect statement, FIRRTL statements are {\em ordering} dependent. Later connections take precendence over earlier connections. In the following example, the wire w is connected to 42, not 20. +Because of the connect statement, FIRRTL statements are {\em ordering} dependent. +Later connections take precendence over earlier connections. +In the following example, the wire w is connected to 42, not 20. \[ \begin{aligned} &\kw{wire} w : \kws{UInt}(\kws{?}) \\ @@ -309,7 +371,8 @@ Because of the connect statement, FIRRTL statements are {\em ordering} dependent \end{aligned} \] -By coupling the conditional statement with last connect semantics, many circuits can be expressed in a natural style. In the following example, the wire w is connected to 20 unless the enable expression is asserted high, in which case w is connected to 42. +By coupling the conditional statement with last connect semantics, many circuits can be expressed in a natural style. +In the following example, the wire w is connected to 20 unless the enable expression is asserted high, in which case w is connected to 42. \[ \begin{aligned} &\kw{wire} w : \kws{UInt}(\kws{?}) \\ @@ -326,10 +389,12 @@ The empty statement is specified using the following. \kw{skip} \end{aligned} \] -The empty statement does nothing and is used simply as a placeholder where a statement is expected. It is typically used as the alternative branch in a conditional statement. +The empty statement does nothing and is used simply as a placeholder where a statement is expected. +It is typically used as the alternative branch in a conditional statement. \subsection{The LetRec Statement} -The letrec statement is used for declaring {\em structural} elements, and is an important part of {\em lowered form}. It is essentially a netlist representation of a piece of circuitry, but a representation that may exist and that operates correctly together with the other FIRRTL statements. +The letrec statement is used for declaring {\em structural} elements, and is an important part of {\em lowered form}. +It is essentially a netlist representation of a piece of circuitry, but a representation that may exist and that operates correctly together with the other FIRRTL statements. \[ \kw{letrec :} \pd{elem*} \kw{in :} \pd{stmt} @@ -337,32 +402,39 @@ The letrec statement is used for declaring {\em structural} elements, and is an A letrec statement is defined by a given list of structural elements, which are described in the following section (section \ref{elements}), and a body which contain statements that may refer to the structural elements. -Unlike in a statement group, the ordering of the structural elements have no meaning. The structural elements can be thought of as being declared {\em simultaneously}, and any structural element may refer to any other structural element, no matter the order in which they are declared. +Unlike in a statement group, the ordering of the structural elements have no meaning. +The structural elements can be thought of as being declared {\em simultaneously}, and any structural element may refer to any other structural element, no matter the order in which they are declared. [TODO: No combinational loops] \section{Structural Elements} \label{elements} -Structural elements appear in letrec statements, and are simply circuit components whose input connections are fully specified upon declaration. They {\em cannot} be used as inputs, and hence can never be on the left-hand side of a connect statement. +Structural elements appear in letrec statements, and are simply circuit components whose input connections are fully specified upon declaration. +They {\em cannot} be used as inputs, and hence can never be on the left-hand side of a connect statement. \subsection{Structural Register} \[ \kw{reg} \text{name } \kw{:} \pd{type} = \kws{Register}(\text{value}, \text{enable}) \] -A structural register is specified given a name, a type, the input value for the register, and the enable signal for the register. The type must be a ground type, the value must be of the given ground type, and the enable signal must be a 1-bit unsigned integer. +A structural register is specified given a name, a type, the input value for the register, and the enable signal for the register. +The type must be a ground type, the value must be of the given ground type, and the enable signal must be a 1-bit unsigned integer. \subsection{Structural Node} \[ \kw{node} \text{name } \kw{:} \pd{type} = \pd{exp} \] -A structural node is specified given a name, a type, and its value. The type must be a ground type, and the given value must match the ground type. +A structural node is specified given a name, a type, and its value. +The type must be a ground type, and the given value must match the ground type. \subsection{Structural Memory} \[ \kw{mem} \text{name } \kw{:} \pd{type} = \kws{Memory}(\kws{WritePort}(\text{index}, \text{value}, \text{enable})\text{*}) \] -A structural memory is specified given a name, a type, and a list of write ports. The given type must be a vector of some ground type. Each write port must specify the index at which to write the value, the value to write, and the enable signal determining when to write the value. The index must be an unsigned integer, the value must match the declared ground type of the memory, and the enable signal must be a 1-bit unsigned integer. +A structural memory is specified given a name, a type, and a list of write ports. +The given type must be a vector of some ground type. +Each write port must specify the index at which to write the value, the value to write, and the enable signal determining when to write the value. +The index must be an unsigned integer, the value must match the declared ground type of the memory, and the enable signal must be a 1-bit unsigned integer. The only method of reading from a structural memory is through the \kws{ReadPort} expression. @@ -370,7 +442,8 @@ The only method of reading from a structural memory is through the \kws{ReadPort \[ \kw{inst} \text{name} = \text{module}(\kws{Input}(\text{field},\pds{exp})\text{*}) \] -A structural instance is specified given the instance name, the name of the module, and a list of the expressions to connect to the instance's input ports. An expression must be specified for every one of the instance's input ports, and the expression's type must match the port type. +A structural instance is specified given the instance name, the name of the module, and a list of the expressions to connect to the instance's input ports. +An expression must be specified for every one of the instance's input ports, and the expression's type must match the port type. \section{Expressions} @@ -382,7 +455,8 @@ A value of type \kws{UInt} can be directly created using the following expressio \[ \kws{UInt}(\text{value}, \text{width}) \] -The given value must be non-negative, and the given width, if known, must be large enough to hold the value. If the width is specified as unknown, then FIRRTL infers the minimum possible width necessary to hold the value. +The given value must be non-negative, and the given width, if known, must be large enough to hold the value. +If the width is specified as unknown, then FIRRTL infers the minimum possible width necessary to hold the value. \subsection{Signed Integers} @@ -390,13 +464,15 @@ A value of type \kws{SInt} can be directly created using the following expressio \[ \kws{SInt}(\text{value}, \text{width}) \] -The given width, if known, must be large enough to hold the given value in two's complement format. If the width is specified as unknown, then FIRRTL infers the minimum possible width necessary to hold the value. +The given width, if known, must be large enough to hold the given value in two's complement format. +If the width is specified as unknown, then FIRRTL infers the minimum possible width necessary to hold the value. \subsection{References} \[ \text{name} \] -A reference is simply a name that refers to some declared circuit component. A reference may refer to a port, a node, a wire, a register, an instance, a memory, a structural node, a structural wire, a structural register, or a structural instance. +A reference is simply a name that refers to some declared circuit component. +A reference may refer to a port, a node, a wire, a register, an instance, a memory, a structural node, a structural wire, a structural register, or a structural instance. \subsection{Subfields} \[ @@ -413,190 +489,333 @@ The subfield expression may be used for one of three purposes: \[ \pds{exp}.\text{index} \] -The subindex expression is used for referring to a specific element within a vector-valued expression. It is legal to use the subindex expression on any vector-valued expression, except for structural and non-structural memories. +The subindex expression is used for referring to a specific element within a vector-valued expression. +It is legal to use the subindex expression on any vector-valued expression, except for structural and non-structural memories. \subsection{Structural Read Port} \[ \kws{ReadPort}(\text{mem}, \text{index}) \] -The structural read port expression is used to read from declared structural memories. A read port is created given the name of a declared structural memory, and the index at which to read from. +The structural read port expression is used to read from declared structural memories. +A read port is created given the name of a declared structural memory, and the index at which to read from. \subsection{Primitive Operation} \[ \pds{primop}(\pds{exp*}, \ints\text{*}) \] -There are a number of different primitive operations supported by FIRRTL. Each operation takes some number of expressions, along with some number of integer literals. Section \ref{primitives} will describe the format and semantics of each operation. +There are a number of different primitive operations supported by FIRRTL. +Each operation takes some number of expressions, along with some number of integer literals. +Section \ref{primitives} will describe the format and semantics of each operation. \section{Primitive Operations} \label{primitives} + \subsection{Add Operation} \[ -\begin{aligned} -\kws{add}(\pds{exp}, \pds{exp}) \\ -\kws{addu}(\pds{exp}, \pds{exp}) \\ -\kws{adds}(\pds{exp}, \pds{exp}) \\ -\end{aligned} +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\kws{add}( \pds{op1}, \pds{op2}) & UInt|SInt & max(width(op1),width(op2)) + 1 \\ +\kws{add-uu}(\pds{op1}, \pds{op2}) & UInt & max(width(op1),width(op2)) + 1 \\ +\kws{add-us}(\pds{op1}, \pds{op2}) & SInt & max(width(op1),width(op2)) + 1 \\ +\kws{add-su}(\pds{op1}, \pds{op2}) & SInt & max(width(op1),width(op2)) + 1 \\ +\kws{add-ss}(\pds{op1}, \pds{op2}) & SInt & max(width(op1),width(op2)) + 1 \\ +\end{array} \] -FIRRTL supports generic, unsigned, and signed versions of the add operation. The generic version supports adding of either two unsigned, or two signed integers, the unsigned version supports adding only unsigned integers, and the signed version supports adding only signed integers. +FIRRTL supports generic, unsigned, and signed versions of the add operation. +The generic version supports adding of any combination of two unsigned or signed integers. The other versions support only a specific permutation of operand types. -If the two operands differ in width, the operand of narrower width is automatically padded to be the same width as the wider operand. The resultant value is 1-bit larger than the wider of the two operands. +If the two operands differ in width, the operand of narrower width is automatically padded to be the same width as the wider operand. +The resultant's value is 1-bit larger than the wider of the two operands and has a signed type if either operand is signed (otherwise is unsigned). \subsection{Subtract Operation} \[ -\begin{aligned} -\kws{sub}(\pds{exp}, \pds{exp}) \\ -\kws{subu}(\pds{exp}, \pds{exp}) \\ -\kws{subs}(\pds{exp}, \pds{exp}) \\ -\end{aligned} +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\kws{sub}( \pds{op1}, \pds{op2}) & SInt & max(width(op1),width(op2)) + 1 \\ +\kws{sub-uu}(\pds{op1}, \pds{op2}) & SInt & max(width(op1),width(op2)) + 1 \\ +\kws{sub-us}(\pds{op1}, \pds{op2}) & SInt & max(width(op1),width(op2)) + 1 \\ +\kws{sub-su}(\pds{op1}, \pds{op2}) & SInt & max(width(op1),width(op2)) + 1 \\ +\kws{sub-ss}(\pds{op1}, \pds{op2}) & SInt & max(width(op1),width(op2)) + 1 \\ +\end{array} \] The subtraction operation works similarly to the add operation. \subsection{Multiply Operation} \[ -\begin{aligned} -\kws{mul}(\pds{exp}, \pds{exp}) \\ -\kws{mulu}(\pds{exp}, \pds{exp}) \\ -\kws{muls}(\pds{exp}, \pds{exp}) \\ -\end{aligned} +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\kws{mul}( \pds{op1}, \pds{op2}) & UInt|SInt & width(op1) + width(op2) \\ +\kws{mul-uu}(\pds{op1}, \pds{op2}) & UInt & width(op1) + width(op2) \\ +\kws{mul-us}(\pds{op1}, \pds{op2}) & SInt & width(op1) + width(op2) \\ +\kws{mul-su}(\pds{op1}, \pds{op2}) & SInt & width(op1) + width(op2) \\ +\kws{mul-ss}(\pds{op1}, \pds{op2}) & SInt & width(op1) + width(op2) \\ +\end{array} \] -As with add and subtract, there is a generic, unsigned, and signed version of the multiply operation. The resultant value has width equal to the sum of the widths of its two operands. +As with add and subtract, there is a generic, unsigned, and signed version of the multiply operation. +The resultant value has width equal to the sum of the widths of its two operands. \subsection{Divide Operation} \[ -\begin{aligned} -\kws{div}(\pds{exp}, \pds{exp}) \\ -\kws{divu}(\pds{exp}, \pds{exp}) \\ -\kws{divs}(\pds{exp}, \pds{exp}) \\ -\end{aligned} +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\kws{div}( \pds{op1}, \pds{op2}) & UInt|SInt & width(op1)|width(op1) + 1 \\ +\kws{div-uu}(\pds{op1}, \pds{op2}) & UInt & width(op1) \\ +\kws{div-us}(\pds{op1}, \pds{op2}) & SInt & width(op1) + 1 \\ +\kws{div-su}(\pds{op1}, \pds{op2}) & SInt & width(op1) \\ +\kws{div-ss}(\pds{op1}, \pds{op2}) & SInt & width(op1) + 1 \\ +\end{array} \] -The first argument is the dividend, the second argument is the divisor. The resultant value of a divide operation has width equal to the width of the dividend minus the width of the divisor. +The first argument is the dividend, the second argument is the divisor. +The resultant value of a divide operation has width equal to the width of the dividend minus the width of the divisor. \subsection{Modulo Operation} \[ -\begin{aligned} -\kws{mod}(\pds{exp}, \pds{exp}) \\ -\kws{modu}(\pds{exp}, \pds{exp}) \\ -\kws{mods}(\pds{exp}, \pds{exp}) \\ -\end{aligned} -\] -The first argument is the dividend, the second argument is the divisor. The resultant value of a modulo operation has the same width as the divisor. - -\subsection{Add Modulo Operation} -\[ -\begin{aligned} -\kws{add-mod}(\pds{exp}, \pds{exp}) \\ -\kws{add-modu}(\pds{exp}, \pds{exp}) \\ -\kws{add-mods}(\pds{exp}, \pds{exp}) \\ -\end{aligned} +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\kws{mod}( \pds{op1}, \pds{op2}) & UInt|SInt & width(op1)|width(op2) - 1 \\ +\kws{mod-uu}(\pds{op1}, \pds{op2}) & UInt & width(op2) \\ +\kws{mod-us}(\pds{op1}, \pds{op2}) & SInt & width(op2) - 1? \\ +\kws{mod-su}(\pds{op1}, \pds{op2}) & UInt & width(op2) \\ +\kws{mod-ss}(\pds{op1}, \pds{op2}) & SInt & width(op2) - 1? \\ +\end{array} \] -The add modulo operation works identically to the normal add operation except that the resultant width is the maximum of the width of the two operands, instead of 1 bit greater than the maximum. In the case of overflow, the result silently rolls over. -\subsection{Subtract Modulo Operation} +\subsection{Quotient Operation} \[ -\begin{aligned} -\kws{sub-mod}(\pds{exp}, \pds{exp}) \\ -\kws{sub-modu}(\pds{exp}, \pds{exp}) \\ -\kws{sub-mods}(\pds{exp}, \pds{exp}) \\ -\end{aligned} +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\kws{quo}( \pds{op1}, \pds{op2}) & UInt|SInt & width(?) \\ +\kws{quo-uu}(\pds{op1}, \pds{op2}) & UInt & width(?) \\ +\kws{quo-us}(\pds{op1}, \pds{op2}) & SInt & width(?) \\ +\kws{quo-su}(\pds{op1}, \pds{op2}) & SInt & width(?) \\ +\kws{quo-ss}(\pds{op1}, \pds{op2}) & SInt & width(?) \\ +\end{array} \] -Similarly to the add modulo operation, the subtract modulo operation works identically to the normal subtract operation except that the resultant width is the maximum of the width of the two operands. In the case of overflow, the result silently rolls over. +The first argument is the dividend, the second argument is the divisor. +The resultant value of a divide operation has width equal to the width of the dividend minus the width of the divisor. -\subsection{Comparison Operations} +\subsection{Remainder Operation} \[ -\begin{aligned} -\kws{lt}(\pds{exp}, \pds{exp}) \\ -\kws{ltu}(\pds{exp}, \pds{exp}) \\ -\kws{lts}(\pds{exp}, \pds{exp}) \\ -\kws{leq}(\pds{exp}, \pds{exp}) \\ -\kws{lequ}(\pds{exp}, \pds{exp}) \\ -\kws{leqs}(\pds{exp}, \pds{exp}) \\ -\kws{gt}(\pds{exp}, \pds{exp}) \\ -\kws{gtu}(\pds{exp}, \pds{exp}) \\ -\kws{gts}(\pds{exp}, \pds{exp}) \\ -\kws{geq}(\pds{exp}, \pds{exp}) \\ -\kws{gequ}(\pds{exp}, \pds{exp}) \\ -\kws{geqs}(\pds{exp}, \pds{exp}) \\ -\end{aligned} +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\kws{rem}( \pds{op1}, \pds{op2}) & UInt|SInt & width(op2)|min(width(op1),width(op2)) \\ +\kws{rem-uu}(\pds{op1}, \pds{op2}) & UInt & min(width(op1),width(op2)) \\ +\kws{rem-us}(\pds{op1}, \pds{op2}) & SInt & width(op2) \\ +\kws{rem-su}(\pds{op1}, \pds{op2}) & UInt & width(op2) \\ +\kws{rem-ss}(\pds{op1}, \pds{op2}) & SInt & width(op2) \\ +\end{array} \] -Generic, unsigned, and signed versions of the less than (\kws{lt}), less than or equal to (\kws{leq}), greater than (\kws{gt}), and greater than or equal to (\kws{geq}) comparison operations are provided. The generic versions of each operation accept either two unsigned integers, or two signed integers, but not a mixture of the two. The resultant value is a single-bit unsigned integer. +The first argument is the dividend, the second argument is the divisor. +The resultant value of a modulo operation has the same width as the divisor. -\subsection{Padding Operation} +\subsection{Add Wrap Operation} \[ -\begin{aligned} -\kws{pad}(\pds{exp}, \text{int}) \\ -\kws{padu}(\pds{exp}, \text{int}) \\ -\kws{pads}(\pds{exp}, \text{int}) \\ -\end{aligned} +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\kws{add-wrap}( \pds{op1}, \pds{op2}) & UInt|SInt & max(width(op1),width(op2)) \\ +\kws{add-wrap-uu}(\pds{op1}, \pds{op2}) & UInt & max(width(op1),width(op2)) \\ +\kws{add-wrap-us}(\pds{op1}, \pds{op2}) & SInt & max(width(op1),width(op2)) \\ +\kws{add-wrap-su}(\pds{op1}, \pds{op2}) & SInt & max(width(op1),width(op2)) \\ +\kws{add-wrap-ss}(\pds{op1}, \pds{op2}) & SInt & max(width(op1),width(op2)) \\ +\end{array} \] -A generic, unsigned, and signed version of the pad operation is provided which pads some expression to a specified width. The unsigned pad operation zero-extends the given value until the specified width, while the signed pad operation sign-extends the given value. The generic operation performs either zero-extension or sign-extension depending on the type of its operand. The given width must be equal to or greater than the existing width of the expression. +The add wrap operation works identically to the normal add operation except that the resultant width is the maximum of the width of the two operands, instead of 1 bit greater than the maximum. +In the case of overflow, the result silently rolls over. -\subsection{Bitwise Operations} +\subsection{Subtract Wrap Operation} \[ -\begin{aligned} -\kws{and}(\pds{exp}, \pds{exp}) \\ -\kws{or}(\pds{exp}, \pds{exp}) \\ -\kws{xor}(\pds{exp}, \pds{exp}) \\ -\end{aligned} +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\kws{sub-wrap}( \pds{op1}, \pds{op2}) & UInt|SInt & max(width(op1),width(op2)) \\ +\kws{sub-wrap-uu}(\pds{op1}, \pds{op2}) & UInt & max(width(op1),width(op2)) \\ +\kws{sub-wrap-us}(\pds{op1}, \pds{op2}) & SInt & max(width(op1),width(op2)) \\ +\kws{sub-wrap-su}(\pds{op1}, \pds{op2}) & SInt & max(width(op1),width(op2)) \\ +\kws{sub-wrap-ss}(\pds{op1}, \pds{op2}) & SInt & max(width(op1),width(op2)) \\ +\end{array} \] -The above operations correspond to bitwise and, or, and exclusive or respectively. The operands must be unsigned integers, and the resultant width is equal to the width of the wider of the two operands. +Similarly to the add wrap operation, the subtract wrap operation works identically to the normal subtract operation except that the resultant width is the maximum of the width of the two operands. +In the case of overflow, the result silently rolls over. -\subsection{Concatenation} +\subsection{Comparison Operations} \[ -\begin{aligned} -\kws{concat}(\pds{exp}, \pds{exp}) \\ -\end{aligned} +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\kws{lt} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{lt-uu} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{lt-us} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{lt-su} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{lt-ss} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{leq} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{leq-uu} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{leq-us} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{leq-su} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{leq-ss} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{gt} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{gt-uu} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{gt-us} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{gt-su} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{gt-ss} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{geq} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{geq-uu} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{geq-us} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{geq-su} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{geq-ss} (\pds{op1}, \pds{op2}) & UInt & 1 \\ +\end{array} \] -The concatenation operator accepts two unsigned integers and returns the bitwise concatenation of the two values as an unsigned integer. The resultant width is the sum of the widths of the two operands. +Generic, unsigned, and signed versions of the less than (\kws{lt}), less than or equal to (\kws{leq}), greater than (\kws{gt}), and greater than or equal to (\kws{geq}) comparison operations are provided. +The generic versions of each operation accept either two unsigned integers, or two signed integers, but not a mixture of the two. +The resultant value is a single-bit unsigned integer. \subsection{Equality Comparison} \[ -\kws{equal}(\pds{exp}, \pds{exp}) \\ +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\kws{equal} (\pds{op1}, \pds{op2}) & UInt|SInt & 1 \\ +\kws{equal-u}(\pds{op1}, \pds{op2}) & UInt & 1 \\ +\kws{equal-s}(\pds{op1}, \pds{op2}) & SInt & 1 \\ +\end{array} \] -The equality comparison operator accepts either two unsigned or two signed integers and checks whether they are bitwise equivalent. The resulting value is a 1-bit unsigned integer. +The equality comparison operator accepts either two unsigned or two signed integers and checks whether they are bitwise equivalent. +The resulting value is a 1-bit unsigned integer. The two operands may differ in width, in which case the narrower of the two operands is padded to the width of the larger operand. +If an arithmetic equals between a signed and unsigned integer is desired, one must first use convert on the unsigned integer, then use the equal-s primop. + \subsection{Multiplex} \[ -\kws{multiplex}(\text{condition}, \text{high-value}, \text{low-value}) +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\kws{mux} (\pds{condition}, \pds{op1}, \pds{op2}) & UInt|SInt & width(op1) \\ +\kws{mux-u}(\pds{condition}, \pds{op1}, \pds{op2}) & UInt & width(op1) \\ +\kws{mux-s}(\pds{condition}, \pds{op1}, \pds{op2}) & SInt & width(op1) \\ +\end{array} +\] +The multiplex operation accepts three signals, a 1-bit unsigned integer for the condition expression, followed by either two unsigned integers, or two signed integers. +If the condition is high, then the result is equal to the first of the two following operands. +If the condition is low, then the result is the second of the two following operands. + +This operation is the only primop where the two operands may not differ in width. The output is of the same width as the inputs. + +\subsection{Padding Operation} +\[ +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\kws{pad}(\pds{op}, \text{num}) & UInt|SInt & num \\ +\kws{pad-u}(\pds{op}, \text{num}) & UInt & num \\ +\kws{pad-s}(\pds{op}, \text{num}) & SInt & num \\ +\end{array} +\] +A generic, unsigned, and signed version of the pad operation is provided which pads some expression to a specified width. +The unsigned pad operation zero-extends the given value until the specified width, while the signed pad operation sign-extends the given value. +The generic operation performs either zero-extension or sign-extension depending on the type of its operand. +The given width must be equal to or greater than the existing width of the expression. + +\subsection{Reinterpret Bits as UInt} +\[ +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\kws{asUInt}(\pds{op1}) & UInt & width(op1) \\ +\kws{asUInt-u}(\pds{op1}) & UInt & width(op1) \\ +\kws{asUInt-s}(\pds{op1}) & UInt & width(op1) \\ +\end{array} \] -The multiplex operation accepts three signals, a 1-bit unsigned integer for the condition expression, followed by either two unsigned integers, or two signed integers. If the condition is high, then the result is equal to the first of the two following operands. If the condition is low, then the result is the second of the two following operands. +A generic, unsigned and signed version of asUInt is provided. All versions return a UInt with the same width as the operand. -The two operands may differ in width, in which case the narrower of the two operands is padded to the width of the larger operand. +\subsection{Reinterpret Bits as SInt} +\[ +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\kws{asSInt}(\pds{op1}) & SInt & width(op1) \\ +\kws{asSInt-u}(\pds{op1}) & SInt & width(op1) \\ +\kws{asSInt-s}(\pds{op1}) & SInt & width(op1) \\ +\end{array} +\] +A generic, unsighed and signed version of asSInt is provided. All versions return a SInt with the same width as the operand. \subsection{Shift Left Operation} \[ -\kws{shl}(\pds{exp}, \text{int}) +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\pd{shl} & UInt|SInt & width(op) + num \\ +\pd{shl-u} & UInt & width(op) + num \\ +\pd{shl-s} & SInt & width(op) + num \\ +\end{array} \] -The shift left operation accepts either an unsigned or a signed integer, plus a non-negative integer literal specifying the number of bits to shift. The resultant value has the same type as the operand. The output of a shift left operation is equal to the original signal concatenated with $n$ zeros at the end, where $n$ is the shift amount. +The shift left operation accepts either an unsigned or a signed integer, plus a non-negative integer literal specifying the number of bits to shift. +The resultant value has the same type as the operand. +The output of a shift left operation is equal to the original signal concatenated with $n$ zeros at the end, where $n$ is the shift amount. \subsection{Shift Right Operation} \[ -\kws{shr}(\pds{exp}, \text{int}) +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\pd{shr} & UInt|SInt & width(op) - num \\ +\pd{shr-u} & UInt & width(op) - num \\ +\pd{shr-s} & SInt & width(op) - num \\ +\end{array} +\] +The shift right operation accepts either an unsigned or a signed integer, plus a non-negative integer literal specifying the number of bits to shift. +The resultant value has the same type as the operand. +The shift amount must be less than or equal to the width of the operand. +The output of a shift right operation is equal to the original signal with the least significant $num$ bits truncated, where $num$ is the shift amount. + +\subsection{Bitwise Operations} +\[ +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\kws{and} (\pds{op1}, \pds{op2}) & UInt & max(width(op1),width(op2)) \\ +\kws{or} (\pds{op1}, \pds{op2}) & UInt & max(width(op1),width(op2)) \\ +\kws{xor} (\pds{op1}, \pds{op2}) & UInt & max(width(op1),width(op2)) \\ +\end{array} +\] +The above operations correspond to bitwise and, or, and exclusive or respectively. +The operands must be unsigned integers, and the resultant width is equal to the width of the wider of the two operands. + +\subsection{Concatenation} +\[ +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\kws{concat}(\pds{op1}, \pds{op2}) & UInt & width(op1) + width(op2) \\ +\end{array} \] -The shift right operation accepts either an unsigned or a signed integer, plus a non-negative integer literal specifying the number of bits to shift. The resultant value has the same type as the operand. The shift amount must be less than or equal to the width of the operand. The output of a shift right operation is equal to the original signal with the last $n$ bits truncated, where $n$ is the shift amount. +The concatenation operator accepts two unsigned integers and returns the bitwise concatenation of the two values as an unsigned integer. +The resultant width is the sum of the widths of the two operands. \subsection{Bit Extraction Operation} \[ -\kws{bit}(\pds{exp}, \text{index}) +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\kws{bit}(\pds{op}, \text{index}) & UInt & 1 \\ +\end{array} \] -The bit extraction operation accepts either an unsigned or a signed integer, plus an integer literal specifying the index of the bit to extract. The resultant value is a 1-bit unsigned integer. The index must be non-negative and less than the width of the operand. An index of zero indicates the least significant bit in the operand, and an index of one less than the width the operand indicates the most significant bit in the operand. +The bit extraction operation accepts either an unsigned or a signed integer, plus an integer literal specifying the index of the bit to extract. +The resultant value is a 1-bit unsigned integer. +The index must be non-negative and less than the width of the operand. +An index of zero indicates the least significant bit in the operand, and an index of one less than the width the operand indicates the most significant bit in the operand. \subsection{Bit Range Extraction Operation} \[ -\kws{bits}(\pds{exp}, \text{high-index}, \text{low-index}) +\begin{array}{rll} +\kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\ +\kws{bits}(\pds{op}, \text{high}, \text{low}) & UInt & high - low \\ +\end{array} \] -The bit range extraction operation accepts either an unsigned or a signed integer, plus two integer literals that specify the high (inclusive) and low (inclusive) index of the bit range to extract. Regardless of the type of the operand, the resultant value is a $n$-bit unsigned integer, where $n = \text{high-index} - \text{low-index} + 1$. +The bit range extraction operation accepts either an unsigned or a signed integer, plus two integer literals that specify the high (inclusive) and low (inclusive) index of the bit range to extract. +Regardless of the type of the operand, the resultant value is a $n$-bit unsigned integer, where $n = \text{high} - \text{low} + 1$. \section{Circuit Initialization} \label{initialization} This section describes FIRRTL's facilities for expressing circuit initialization, and how it is customized through the reset port for modules, and the init field for registers. \subsection{Register Initialization} -On circuit reset, registers are automatically set to their {\em initialization value}. By default, a register's initialization value is set to be equal to the value of the register itself. Hence, the default reset behavior for registers is to maintain their current value. +On circuit reset, registers are automatically set to their {\em initialization value}. +By default, a register's initialization value is set to be equal to the value of the register itself. +Hence, the default reset behavior for registers is to maintain their current value. -However, an explicit initialization value can be provided for a register by connecting an expression to the register's init field. The following example demonstrates declaring a register, and changing its initialization value to forty two. +However, an explicit initialization value can be provided for a register by connecting an expression to the register's init field. +The following example demonstrates declaring a register, and changing its initialization value to forty two. \[ \begin{aligned} & \kw{reg} r : \kws{UInt}(10) \\ @@ -604,12 +823,17 @@ However, an explicit initialization value can be provided for a register by conn \end{aligned} \] -The type of the initialization value must match the declared type of the register. In the above example, the register, r, will be set to forty two when the circuit is reset. Note that structural registers declared within letrec statements do not have an init field. +The type of the initialization value must match the declared type of the register. +In the above example, the register, r, will be set to forty two when the circuit is reset. +Note that structural registers declared within letrec statements do not have an init field. \subsection{Module Reset Port} -Every module has an input reset port declared to be a 1-bit unsigned integer. If the user chooses, the reset port may be explicitly declared. If the user does not explicitly declare a reset port, then FIRRTL will implicitly insert a reset port for the module. +Every module has an input reset port declared to be a 1-bit unsigned integer. +If the user chooses, the reset port may be explicitly declared. +If the user does not explicitly declare a reset port, then FIRRTL will implicitly insert a reset port for the module. -When an instance of a module with an implicit reset is created, the reset signal of the module in which the instance was created is automatically connected to the instance's reset port. Consider the following example: +When an instance of a module with an implicit reset is created, the reset signal of the module in which the instance was created is automatically connected to the instance's reset port. +Consider the following example: \[ \begin{aligned} &\kw{module} A : \\ @@ -620,7 +844,8 @@ When an instance of a module with an implicit reset is created, the reset signal &\quad a.\text{x} \kw{ :=} \kws{UInt}(42, \kws{?}) \\ \end{aligned} \] -The module A has an implicit reset port, and the module B creates an instance of A. In this case, there is an implicit connect statement inserted, connecting the instance's reset port to the implicit reset port of B. +The module A has an implicit reset port, and the module B creates an instance of A. +In this case, there is an implicit connect statement inserted, connecting the instance's reset port to the implicit reset port of B. \[ \begin{aligned} &\kw{inst} a \kw{ of} A \\ @@ -640,7 +865,9 @@ The user may choose to explicitly override this default behavior by explicitly c \] The above code explicitly connects the instance's reset port to zero, indicating that its registers are {\em never} reset. -Should the user choose to explicitly declare the reset port for a module, then the port {\em must} be appropriately declared as an {\em input} port with a declared type of unsigned integer with width one. Additionally, if the user explicitly declares the reset port for a module, then all instances of that module must have its reset port connected explicitly. For example, the following code +Should the user choose to explicitly declare the reset port for a module, then the port {\em must} be appropriately declared as an {\em input} port with a declared type of unsigned integer with width one. +Additionally, if the user explicitly declares the reset port for a module, then all instances of that module must have its reset port connected explicitly. +For example, the following code \[ \begin{aligned} &\kw{module} A : \\ @@ -652,11 +879,13 @@ Should the user choose to explicitly declare the reset port for a module, then t &\quad a.\text{x} \kw{ :=} \kws{UInt}(42, \kws{?}) \\ \end{aligned} \] -is not legal. The module, A, has an explicitly declared reset port, but the reset port for its instance, a, is not explicitly connected to any value. +is not legal. +The module, A, has an explicitly declared reset port, but the reset port for its instance, a, is not explicitly connected to any value. \section{Lowered Form} -To simplify the writing of transformation passes, FIRRTL provides a {\em lowering} pass, which rewrites any FIRRTL circuit into an equivalent {\em lowered form}. The lowered form has the advantage of not having any high-level constructs or composite types, and hence is a minimal representation that is convenient for low-level transforms. +To simplify the writing of transformation passes, FIRRTL provides a {\em lowering} pass, which rewrites any FIRRTL circuit into an equivalent {\em lowered form}. +The lowered form has the advantage of not having any high-level constructs or composite types, and hence is a minimal representation that is convenient for low-level transforms. In lowered form, every module has exactly the following form. \[ @@ -670,33 +899,45 @@ In lowered form, every module has exactly the following form. \end{aligned} \] -The body of the module must consist of a single letrec statement, in which every component within the module is declared as a structural element. The only statements that may appear in the body of the letrec statement are connect statements for each of the module's output ports. The following restrictions also hold for modules in lowered form. +The body of the module must consist of a single letrec statement, in which every component within the module is declared as a structural element. +The only statements that may appear in the body of the letrec statement are connect statements for each of the module's output ports. +The following restrictions also hold for modules in lowered form. \subsection{No Nested Expressions} -In the declaration of the structural elements, the only nested expressions allowed are references, and unsigned and signed literals. All other nested expressions must be lifted to a named structural node, and referred to through a reference. +In the declaration of the structural elements, the only nested expressions allowed are references, and unsigned and signed literals. +All other nested expressions must be lifted to a named structural node, and referred to through a reference. \subsection{No Composite Types} -No module port may be declared with a bundle or vector type. The lowering pass will recursively expand ports into its constituent elements until all ports are declared with ground types. Additionally, by virtue of requiring all module components to be declared as structural elements, which support ground types only, there will be no composite types left in lowered form. +No module port may be declared with a bundle or vector type. +The lowering pass will recursively expand ports into its constituent elements until all ports are declared with ground types. +Additionally, by virtue of requiring all module components to be declared as structural elements, which support ground types only, there will be no composite types left in lowered form. \subsection{No Unknown Widths} -No port or structural element may be declared with unknown width. The FIRRTL width inferencer will compute the widths for all structural elements and ports. If a width for some element cannot be calculated, then the lowering pass will fail with an error. +No port or structural element may be declared with unknown width. +The FIRRTL width inferencer will compute the widths for all structural elements and ports. +If a width for some element cannot be calculated, then the lowering pass will fail with an error. \subsection{Explicit Resets} All modules will contain an explicitly declared reset port and the structural instances within a module will explicitly specify the values connected to their reset ports. \section{Inlined Lowered Form} -A further pass provided by FIRRTL is the inlining pass, which recursively inlines all instances in the top-level module until the top-level module is the only remaining module in the circuit. Inlined lowered form is essentially a flat netlist which specifies every component used in a circuit and their input connections. +A further pass provided by FIRRTL is the inlining pass, which recursively inlines all instances in the top-level module until the top-level module is the only remaining module in the circuit. +Inlined lowered form is essentially a flat netlist which specifies every component used in a circuit and their input connections. \section{Concrete Syntax}\label{concrete} This section describes the text format for FIRRTL that is supported by the provided readers and writers. \subsection*{General Principles} -FIRRTL's text format is human-readable and uses indentation to indicate block structuring. The following characters are allowed in identifiers: upper and lower case letters, digits, as well as the punctuation characters \verb|~!@#$%^*-_+=?/|. Identifiers cannot begin with a digit. +FIRRTL's text format is human-readable and uses indentation to indicate block structuring. +The following characters are allowed in identifiers: upper and lower case letters, digits, as well as the punctuation characters \verb|~!@#$%^*-_+=?/|. +Identifiers cannot begin with a digit. -Comments begin with a semicolon and extend until the end of the line. Commas are treated as whitespace, and may be used by the user for clarity if desired. +Comments begin with a semicolon and extend until the end of the line. +Commas are treated as whitespace, and may be used by the user for clarity if desired. -Statements are grouped into statement groups using parenthesis, however a colon at the end of a line will automatically surround the next indented region with parenthesis. This mechanism is used for indicating block structuring. +Statements are grouped into statement groups using parenthesis, however a colon at the end of a line will automatically surround the next indented region with parenthesis. +This mechanism is used for indicating block structuring. \subsection*{Circuits and Modules} A circuit is specified the following way. @@ -713,7 +954,8 @@ A module is specified the following way. \begin{verbatim} module name : (ports ... stmts ...) \end{verbatim} -The module body consists of a sequence of ports followed immediately by a sequence of statements. If there is more than one statement they are grouped into a statement group by the parser. +The module body consists of a sequence of ports followed immediately by a sequence of statements. +If there is more than one statement they are grouped into a statement group by the parser. By using indentation structuring: \begin{verbatim} module name : @@ -730,7 +972,8 @@ module mymodule : \end{verbatim} \subsection*{Types} -The unsigned and signed integer types are specified the following way. The following examples demonstrate a unsigned integer with known bitwidth, signed integer with known bitwidth, an unsigned integer with unknown bitwidth, and signed integer with unknown bitwidth. +The unsigned and signed integer types are specified the following way. +The following examples demonstrate a unsigned integer with known bitwidth, signed integer with known bitwidth, an unsigned integer with unknown bitwidth, and signed integer with unknown bitwidth. \begin{verbatim} UInt(42) SInt(42) @@ -738,14 +981,17 @@ UInt(?) SInt(?) \end{verbatim} -The bundle type consists of a number of fields surrounded with parenthesis. The following shows an example of a decoupled bundle type. Note that the commas are for clarity only and are not necessary. +The bundle type consists of a number of fields surrounded with parenthesis. +The following shows an example of a decoupled bundle type. +Note that the commas are for clarity only and are not necessary. \begin{verbatim} {output data: UInt(10), output valid: UInt(1), input ready: UInt(1)} \end{verbatim} -The vector type is specified by immediately postfixing a type with a bracketed integer literal. The following example demonstrates a ten-element vector of 16-bit unsigned integers. +The vector type is specified by immediately postfixing a type with a bracketed integer literal. +The following example demonstrates a ten-element vector of 16-bit unsigned integers. \begin{verbatim} UInt(16)[10] \end{verbatim} @@ -793,7 +1039,8 @@ else : x := w \end{verbatim} -Letrec statements are expressed using the \verb|letrec| keyword. The following example demonstrates a letrec statement containing the four structural elements. +Letrec statements are expressed using the \verb|letrec| keyword. +The following example demonstrates a letrec statement containing the four structural elements. \begin{verbatim} letrec : reg r : UInt(4) = Register(x, e) @@ -806,7 +1053,8 @@ in : \subsection*{Expressions} -The UInt and SInt constructors create literal integers from a given value and bitwidth. The following examples demonstrate creating literal integers of both known and unknown bitwidth. +The UInt and SInt constructors create literal integers from a given value and bitwidth. +The following examples demonstrate creating literal integers of both known and unknown bitwidth. \begin{verbatim} UInt(42, 4) SInt(-42, 4) |