Major revisions to spec. Bumped to v0.1.2

9 files changed, 310 insertions, 184 deletions

diff --git a/Makefile b/Makefile
index 780c1223..b0c200d5 100644
--- a/Makefile
+++ b/Makefile
@@ -48,8 +48,12 @@ clean:
 riscv:
 	cd $(test_dir)/riscv-mini && lit -v . --path=$(root_dir)/utils/bin/
 
-push:
-	scp test/chisel3/*.v adamiz@a5:/scratch/adamiz/firrtl-all/riscv-mini/generated-fir-src
+units = ALUTop Datapath Control Core
+v     = $(addsuffix .fir.v, $(units))
+
+$(units): % :
+	firrtl -X verilog -i test/chisel3/$*.fir -o test/chisel3/$*.fir.v
+	scp test/chisel3/$*.fir.v adamiz@a5:/scratch/adamiz/firrtl-all/riscv-mini/generated-src/$*.v
 
 done:
 	say "done"
diff --git a/TODO b/TODO
index 0997c219..6c343dcf 100644
--- a/TODO
+++ b/TODO
@@ -6,7 +6,6 @@
 Add print, assert
 move width inference earlier
    Required for subword assignment, consistent vec width inference, and supporting the new constructs of tobits/frombits
-Low FIRRTL pass analysis
 Temp elimination needs to count # uses
 Declared references needs to understand scope <= check in high form check
 Check for recursively defined instances
@@ -17,6 +16,7 @@ Add Unit Tests for each pass
    write test that checks instance types are correctly lowered
 Scaling
 Do name-mangling differently, use _xEF or something like that
+Add alpha transform pass
 
 ======== Verilog Backend Notes ========
 * 1) Emit module. No Parameters. Include clk and reset signals
@@ -39,16 +39,13 @@ Checks:
 
    
 ======== Update Core ==========
-Add vptype
+Add bi-accessor
 Add readwriteport
 
 ======== Check Passes ==========
 High-Firrtl
    No combinational loops
 After adding dynamic assertions, insert bounds check with accessor expansion
-Well-formed low firrtl
-   All things only assigned to once
-   Register/ReadPort/WritePort are only in correct spots
 Width inference
    No names
    No Unknowns
@@ -77,19 +74,18 @@ expanding mems (consider changing defmem to be size, and element type)
 Multi-streams for print statements/asserts (Jack)
 Consider def female node. (Patrick) 
 Add FIFOs to the IR (Palmer)
-Think about supporting generic primops on bundles and vecs (Adam) (wait until front-end more completed)
 Union Types
 Enums?
 Convert to scala
 Firrtl interpreter (in scala)
 
 ======== Update Spec ========
-Look through all primops
-change parser to other unknown thing for vptype?
-Add optional type to node
-add assertions and printfs
-cannot connect directly to a mem (loc can never contain a mem)
-Front-end needs to guarantee unique names per module.
+add printfs
+think about subword on accessors
+think about mems in lowered form - change ReadPort's reference to mem to be either exp or id
+add explanation about mems
+think about ROMS
+
 FIRRTL rule: No name can be a prefix of any other name.
 Future questions to address in spec:
    Introduction – motivation, and intended usage
@@ -126,14 +122,6 @@ Schedulable
 Scheduler
 
 ======== Notes ========
-Only for MUXES, AS, and __ can width inference go backwards:
-  reg r : UInt<5>
-  r := MUX(p,UInt<?>(1),UInt<?>(2))
-  ==>
-  reg r : UInt<5>
-  r := MUX(p,UInt<5>(1),UInt<5>(2))
-
-
 Which ones
 Treat everything as just bits - the only operators that should exist are ones that emit different bits
 Go through all primops with Andrew
diff --git a/notes/memory.txt b/notes/memory.txt
index 22fb95dc..8a9e758e 100644
--- a/notes/memory.txt
+++ b/notes/memory.txt
@@ -24,13 +24,13 @@ Masks?
    How do we do this? Try not expanding mems, but expanding accessors.
    e.g.
 
-mem m : { tag : UInt<10> data : UInt<128> }
+mem m : { tag : UInt<10> data : UInt<128> }[128]
 accessor r = m[i]
 accessor w = m[i]
 
 ==>
 
-mem m : { tag : UInt<10> data : UInt<128> }
+mem m : { tag : UInt<10> data : UInt<128> }[128]
 accessor r#tag = m.tag[i]
 accessor r#data = m.data[i]
 accessor w#tag = m.tag[i]
diff --git a/spec/spec.pdf b/spec/spec.pdf
index 67e9236f..34b5e878 100644
--- a/spec/spec.pdf
+++ b/spec/spec.pdf
diff --git a/spec/spec.tex b/spec/spec.tex
index 2930e3c8..656025d6 100644
--- a/spec/spec.tex
+++ b/spec/spec.tex
@@ -1,20 +1,40 @@
-\title{Specification for the FIRRTL Language: Version 0.1.1}
-\author{Patrick S. Li, Adam M. Izraelevitz, Jonathan Bachrach}
-\documentclass[12pt]{article}
+\title{Specification for the FIRRTL Language:\\ Version 0.1.2 \\ PRE-RELEASE VERSION, DO NOT DISTRIBUTE}
+\author{Patrick S. Li \\ \href{mailto:psli@eecs.berkeley.edu}{psli@eecs.berkeley.edu}
+   \and Adam M. Izraelevitz \\ \href{mailto:adamiz@eecs.berkeley.edu}{adamiz@eecs.berkeley.edu} 
+   \and Jonathan Bachrach \\ \href{mailto:jrb@eecs.berkeley.edu}{jrb@eecs.berkeley.edu} }
+\documentclass[10pt]{article}
 \usepackage{listings}
 \usepackage{amsmath}
 \usepackage{proof}
 \usepackage{amsfonts}
+\usepackage{enumitem}
+\usepackage{hyperref}
+\hypersetup{
+    colorlinks=true,
+    linkcolor=blue,
+    filecolor=magenta,      
+    urlcolor=cyan,
+}
 \usepackage[pdftex]{graphicx}
+\usepackage{fancyhdr}
+\pagestyle{fancy}
+\lhead{Specification for the FIRRTL Language}
+\rhead{Version 0.1.2}
+\cfoot{\thepage \\ \em{PRE-RELEASE VERSION, DO NOT DISTRIBUTE}}
+\renewcommand{\headrulewidth}{0.4pt}
+\renewcommand{\footrulewidth}{0.4pt}
 \lstset{basicstyle=\footnotesize\ttfamily,breaklines=true}
 
 \begin{document}
 \maketitle
+\tableofcontents
+\newpage
 
 %Useful Macros
 \newcommand{\id}{\text{id }}
 \newcommand{\ids}{\text{id}}
 \newcommand{\ints}{\text{int}}
+\newcommand{\intsp}{\text{int }}
 \newcommand{\kw}[1]{\text{\bf #1\ }}
 \newcommand{\kws}[1]{\text{\bf #1}}
 \newcommand{\pd}[1]{\text{\em #1\ }}
@@ -22,6 +42,14 @@
 \newcommand{\bundleT}[1]{\{#1\}}
 \newcommand{\info}{[\pds{info}]\ }
 
+\section{Introduction and Philosophy}
+
+This is our philosophy placeholder.
+
+\section{Acknowledgements}
+
+The FIRRTL language could not have been developed without the help of many of the faculty and students in the ASPIRE lab, including but not limited to Andrew Waterman, Stephen Twigg, Palmer Dabbelt, Eric Love, Scott Beamer, Chris Celio, Krste Asanovic, and many many others. We'd also like to thank our sponsors XXXX, and the UC Berkeley University.
+
 \section{FIRRTL Language Definition}
 
 \subsection{Abstract Syntax Tree}
@@ -31,39 +59,40 @@
 \pd{module}     &=     &\info \kw{module}  \id \kw{:} (\pd{port*} \pd{stmt})                          &\text{Module}\\
                 &\vert &\info \kw{exmodule}  \id \kw{:} (\pd{port*})                                  &\text{External Module}\\
 \pd{port}       &=     &\info \pd{dir} \id \kw{:} \pd{type}                                           &\text{Port}\\
-\pd{dir}        &=     &\kws{input} \vert \kws{output}                                                &\text{Input/Output}\\
-\pd{type}       &=     &\kws{UInt}<\pd{width}>                                                        &\text{Unsigned Integer}\\
-                &\vert &\kws{SInt}<\pd{width}>                                                        &\text{Signed Integer}\\
+\pd{dir}        &=     &\kws{input} \vert \kws{output} \vert \kws{clk}                                &\text{Input/Output}\\
+\pd{type}       &=     &\kws{UInt} \kws{$<$} \pds{width} \kws{$>$}                                    &\text{Unsigned Integer}\\
+                &\vert &\kws{SInt} \kws{$<$} \pds{width} \kws{$>$}                                    &\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{default} \vert \kws{reverse}                                             &\text{Orientation}\\
 \pd{width}      &=     &\ints                                                                         &\text{Known Integer Width}\\
                 &\vert &\kw{?}                                                                        &\text{Unknown Width}\\
-\pd{atype}      &=     &\kws{read} \vert \kws{write} \vert \kws{unknown}                              &\text{Accessor Type}\\
 \pd{stmt}       &=     &\info \kw{wire} \id \kw{:} \pd{type}                                          &\text{Wire Declaration}\\
-                &\vert &\info \kw{reg} \id \kw{:} \pd{type}                                           &\text{Register Declaration}\\
-                &\vert &\info \kw{mem} \id \kw{:} \pd{type}                                           &\text{Memory Declaration}\\
-                &\vert &\info \kw{inst} \id \kw{:} \id                                               &\text{Instance Declaration}\\
+                &\vert &\info \kw{reg} \id \kw{:}  \pds{type} , \ids , \pds{exp}                      &\text{Register Declaration}\\
+                &\vert &\info \kw{smem} \id \kw{:} \pds{type} , \ids                                  &\text{Sequential Memory Declaration}\\
+                &\vert &\info \kw{cmem} \id \kw{:} \pds{type} , \ids                                  &\text{Combinational Memory Declaration}\\
+                &\vert &\info \kw{inst} \id \kw{:} \id                                                &\text{Instance Declaration}\\
                 &\vert &\info \kw{node} \id  = \pd{exp}                                               &\text{Node Declaration}\\
-                &\vert &\info \pd{atype}  \kw{accessor} \id = \pds{exp}[\pds{exp}]                    &\text{Accessor Declaration}\\
+                &\vert &\info \kw{accessor} \id = \pds{exp}[\pds{exp}]                                &\text{Accessor Declaration}\\
+                &\vert &\info \kw{bi-accessor} \id = \pds{exp}[\pds{exp}]                             &\text{Bi-Accessor Declaration}\\
                 &\vert &\info \pd{exp} \kw{:=} \pd{exp}                                               &\text{Connect}\\
-                &\vert &\info \kw{on-reset} \pd{exp} \kw{:=} \pd{exp}                                 &\text{On Reset}\\
+                &\vert &\info \kw{onreset} \pd{exp} \kw{:=} \pd{exp}                                  &\text{On-Reset Connect}\\
+                &\vert &\info \pd{exp} \kw{$<>$} \pd{exp}                                             &\text{Bulk Connect}\\
                 &\vert &\info \kw{when} \pd{exp} \kw{:} \pd{stmt} \kw{else :} \pd{stmt}               &\text{Conditional}\\
-                &\vert &\info (\pd{stmt*})                                                            &\text{Statement Group}\\
+                &\vert &\info \pds{exp}[\intsp  \kw{through} \ints] \ \kw{:=} \pds{exp}               &\text{Sub-Word Assignment}\\
+                &\vert &\info \kw{assert} \pd{exp}                                                    &\text{Assert Statement}\\
                 &\vert &\info \kw{skip}                                                               &\text{Empty Statement}\\
-\pd{exp}        &=     &\info \kws{UInt}<\pds{width}>(ints)                                           &\text{Literal Unsigned Integer}\\
-                &\vert &\info \kws{SInt}<\pds{width}>(ints)                                           &\text{Literal Signed Integer}\\
+                &\vert &\info (\pd{stmt*})                                                            &\text{Statement Group}\\
+\pd{exp}        &=     &\info \kws{UInt} \kws{$<$} \pds{width} \kws{$>$}(ints)                        &\text{Literal Unsigned Integer}\\
+                &\vert &\info \kws{SInt} \kws{$<$} \pds{width} \kws{$>$}(ints)                        &\text{Literal Signed Integer}\\
                 &\vert &\info \id                                                                     &\text{Reference}\\
                 &\vert &\info \pds{exp}.\id                                                           &\text{Subfield}\\
                 &\vert &\info \pds{exp}[\ints]                                                        &\text{Subindex}\\
-                &\vert &\info \kws{Register}(\pds{exp}, \pds{exp})                                    &\text{Structural Register}\\
-                &\vert &\info \kws{WritePort}(\id, \pds{exp}, \pds{exp})                              &\text{Write Port}\\
-                &\vert &\info \kws{ReadPort}(\id, \pds{exp}, \pds{exp})                               &\text{Read Port}\\
-\end{array}
-\]
-\[
-\begin{array}{rrll}
+                &\vert &\info \kws{Register}(\pds{exp}, \pds{exp}, \id)                               &\text{Structural Register}\\
+                &\vert &\info \kws{WritePort}(\pds{exp}, \pds{exp}, \pds{exp})                        &\text{Write Port}\\
+                &\vert &\info \kws{ReadPort}(\pds{exp}, \pds{exp}, \pds{exp})                         &\text{Read Port}\\
+                &\vert &\info \kws{RdWrPort}(\pds{exp}, \pds{exp}, \pds{exp}, \pds{exp}, \pds{exp})   &\text{Read/Write Port}\\
                 &\vert &\info \pds{primop}(\pds{exp*}, \ints\text{*})                                 &\text{Primitive Operation}\\
 \pd{info}       &=     &\text{filename } \kw{:} \text{line} . \text{col}                              &\text{File Location}\\
                 &\vert &\kw{noinfo}                                                                   &\text{No File Location}\\
@@ -75,13 +104,13 @@
 \pd{primop}     &= \\
                 &\kws{add}            &\text{Unsigned/Signed Add}\\
 \vert           &\kws{sub}            &\text{Unsigned/Signed Subtract}\\
+\vert           &\kws{addw}           &\text{Unsigned/Signed Add Wrap}\\
+\vert           &\kws{subw}           &\text{Unsigned/Signed Subtract Wrap}\\
 \vert           &\kws{mul}            &\text{Unsigned/Signed Multiply}\\
 \vert           &\kws{div}            &\text{Unsigned/Signed Divide}\\
 \vert           &\kws{rem}            &\text{Unsigned/Signed Remainder}\\
 \vert           &\kws{quo}            &\text{Unsigned/Signed Quotient}\\
 \vert           &\kws{mod}            &\text{Unsigned/Signed Modulo}\\
-\vert           &\kws{add-wrap}       &\text{Unsigned/Signed Add Wrap}\\
-\vert           &\kws{sub-wrap}       &\text{Unsigned/Signed Subtract Wrap}\\
 \vert           &\kws{lt}             &\text{Unsigned/Signed Less Than}\\
 \vert           &\kws{leq}            &\text{Unsigned/Signed Less or Equal}\\
 \vert           &\kws{gt}             &\text{Unsigned/Signed Greater Than}\\
@@ -94,25 +123,32 @@
 \vert           &\kws{asSInt}         &\text{Unsigned/Signed Reinterpret Bits as SInt}\\
 \vert           &\kws{shl}            &\text{Unsigned/Signed Shift Left}\\
 \vert           &\kws{shr}            &\text{Unsigned/Signed Shift Right}\\
-\vert           &\kws{toSInt}        &\text{Unsigned/Signed to Signed Conversion}\\
+\vert           &\kws{dshl}           &\text{Unsigned/Signed Dynamic Shift Left}\\
+\vert           &\kws{dshr}           &\text{Unsigned/Signed Dynamic Shift Right}\\
+\vert           &\kws{cvt}            &\text{Unsigned/Signed to Signed Logical Conversion}\\
 \vert           &\kws{neg}            &\text{Unsigned/Signed Negate}\\
-\vert           &\kws{bit-not}        &\text{Unsigned Not}\\
-\vert           &\kws{bit-and}        &\text{Unsigned And}\\
-\vert           &\kws{bit-or}         &\text{Unsigned Or}\\
-\vert           &\kws{bit-xor}        &\text{Unsigned Xor}\\
-\vert           &\kws{bit-and-reduce} &\text{Unsigned And}\\
-\vert           &\kws{bit-or-reduce}  &\text{Unsigned Or}\\
-\vert           &\kws{bit-xor-reduce} &\text{Unsigned Xor}\\
-\vert           &\kws{cat}         &\text{Unsigned Concatenation}\\
+\vert           &\kws{not}            &\text{Unsigned Not}\\
+\vert           &\kws{and}            &\text{Unsigned And}\\
+\vert           &\kws{or}             &\text{Unsigned Or}\\
+\vert           &\kws{xor}            &\text{Unsigned Xor}\\
+\vert           &\kws{andr}           &\text{Unsigned And Reduce}\\
+\vert           &\kws{orr}            &\text{Unsigned Or Reduce}\\
+\vert           &\kws{xorr}           &\text{Unsigned Xor Reduce}\\
+\vert           &\kws{cat}            &\text{Unsigned Concatenation}\\
 \vert           &\kws{bit}            &\text{Single Bit Extraction}\\
 \vert           &\kws{bits}           &\text{Multiple Bit Extraction}\\
 \end{array}
 \]
 
 \subsection{Notation}
-The above definition specifies the structure of the abstract syntax tree corresponding to a FIRRTL circuit. Nodes in the abstract syntax tree are {\em italicized}. Keywords are shown in {\bf bold}. The special productions, id and int, indicates an identifier and an integer literal respectively. Tokens followed by an asterisk, {\em e.g.} \pds{field}*, indicates a list formed from repeated occurences of the token.
+The above definition specifies the structure of the abstract syntax tree corresponding to a FIRRTL circuit.
+Nodes in the abstract syntax tree are {\em italicized}.
+Keywords are shown in {\bf bold}.
+The special productions, id and int, indicates an identifier and an integer literal respectively.
+Tokens followed by an asterisk, {\em e.g.} \pds{field}*, indicates a list formed from repeated occurences of the token.
 
-Keep in the mind that the above definition is only the {\em abstract} syntax tree, and is a representation of the in-memory FIRRTL datastructure. Readers and writers are provided for converting a FIRRTL datastructure into a purely textual representation, and is defined in section \ref{concrete}.
+Keep in the mind that the above definition is only the {\em abstract} syntax tree, and is a representation of the in-memory FIRRTL datastructure.
+Readers and writers are provided for converting a FIRRTL datastructure into a purely textual representation, and is defined in section \ref{concrete}.
 
 
 \section{Circuits and Modules}
@@ -131,28 +167,29 @@ Each module has a given name, a list of ports, and a statement representing the
 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.
+A module port is specified by a direction, which may be input or output or clock, a name, and the data type for the port.
 The port names exist in the identifier namespace for the module, and must be unique.
 In addition, all references within a module 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 clock port direction is special, in that it has the same conceptual direction as an input port, but cannot be used to connect to any element in the circuit except to other clock ports of declared instances.
+In addition, can be referenced in the \kws{reg}, \kws{cmem}, \kws{smem} declarations, as explained in section \ref{statements}.
 
 \section{Types}
 
 \subsection{Ground Types}
 \[
 \begin{array}{rrl}
-\pd{type}       &=     &\kws{UInt}<\pd{width}>      \\
-                &\vert &\kws{SInt}<\pd{width}>      \\
+\pd{type}       &=     &\kws{UInt}\kws{$<$} \pds{width} \kws{$>$}      \\
+                &\vert &\kws{SInt}\kws{$<$} \pds{width} \kws{$>$}      \\
 \pd{width}      &=     &\ints                       \\
                 &\vert &\kw{?}                      \\
 \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.
+Both of these types require a given bitwidth, which may be some known integer width, which must be non-negative and greater than zero, 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.
+Zero-valued widths are currently not supported, but future versions will likely support them.
 
 \subsection{Vector Types}
 \[
@@ -165,11 +202,11 @@ Vector types in FIRRTL indicate a structure consisting of multiple elements of s
 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 but the same bitwidths.
+As an example, the type $\kws{UInt}\kws{$<$} 16 \kws{$>$}[10]$ indicates a ten element vector of 16-bit unsigned integers.
+The type $\kws{UInt}\kws{$<$} \kws{?} \kws{$>$}[10]$ indicates a ten element vector of unsigned integers, with unknown but the same 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.
+The type $\kws{UInt}\kws{$<$} 16 \kws{$>$}[10][5]$ indicates a five element vector {\em of} ten element vectors of 16-bit unsigned integers.
 
 \subsection{Bundle Types}
 \[
@@ -184,16 +221,16 @@ Bundle types in FIRRTL are composite types formed from an ordered sequence of na
 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{default} \text{real } \kw{:} \kws{SInt}<10>,
-         \kw{default} \text{imag } \kw{:} \kws{SInt}<10>}
+\bundleT{\kw{default} \text{real } \kw{:} \kws{SInt}\kws{$<$} 10 \kws{$>$},
+         \kw{default} \text{imag } \kw{:} \kws{SInt}\kws{$<$} 10 \kws{$>$}}
 \]
 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{default} &\text{data } \kw{:} \kws{UInt}<10>, \\
-   \kw{default} &\text{valid } \kw{:} \kws{UInt}<1>, \\
-   \kw{reverse} &\text{ready } \kw{:} \kws{UInt}<1>\} \\
+\{ \kw{default} &\text{data } \kw{:} \kws{UInt}\kws{$<$} 10 \kws{$>$}, \\
+   \kw{default} &\text{valid } \kw{:} \kws{UInt}\kws{$<$} 1 \kws{$>$}, \\
+   \kw{reverse} &\text{ready } \kw{:} \kws{UInt}\kws{$<$} 1 \kws{$>$}\} \\
 \end{aligned}
 \]
 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 a flipped ready signal that must be a 1-bit unsigned integer.
@@ -207,12 +244,12 @@ Note that all field names within a bundle type must be unique.
 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}
+\section{Statements} \label{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 is a named combinational circuit element that can be 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} \\
@@ -222,22 +259,30 @@ Declared wires are {\em bidirectional}, which means that they can be used as bot
 
 \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 with a given name, type, clock port name, and reset reference, can be instantiated with the following statement.
 \[
-\kw{reg} \text{name } \kw{:} \pd{type} \\
+\kw{reg} \text{name } \kw{:} \pds{type},\text{ clk, } \pds{reset} \\
 \]
 
 Like wires, registers are also {\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). 
 
-The statement {\em on-reset} is used to specify the initialization value for a register, and is described in section \ref{initialization}. 
+The statement {\em onreset} is used to specify the initialization value for a register, which is assigned to the register when the declared \pds{reset} signal is asserted.
 
 \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.
+Memories always have a synchronous write, but can either be declared to be read combinatorially or synchronously.
+A synchronously read memory with a given name, type and clock port name can be instantiated with the following statement.
 \[
 \begin{aligned}
-\kw{mem} \text{name } \kw{:} \pd{type} \\
+\kw{smem} \text{name } \kw{:} \pds{type},\text{ clk} \\
+\end{aligned}
+\]
+
+A combinatorially read memory with a given name, type and clock port name can be instantiated with the following statement.
+\[
+\begin{aligned}
+\kw{cmem} \text{name } \kw{:} \pds{type},\text{ clk} \\
 \end{aligned}
 \]
 
@@ -247,7 +292,7 @@ However, the internal type to the vector type may be a non-ground type, with the
 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 is simply a named intermediate value in a circuit, and is akin to a pointer in the C programming language.
 A node with a given name and value can be instantiated with the following statement.
 \[
 \kw{node} \text{name } = \pd{exp} \\
@@ -261,34 +306,64 @@ Accessors are used for either connecting to or from a vector-typed expression, f
 An accessor can be instantiated with the following statement.
 \[
 \begin{aligned}
-\pd{atype}  \kw{accessor} \text{name} = \pds{exp}[\text{index}] \\
-\pd{atype}      &=     &\kws{read} \vert \kws{write} \vert \kws{unknown}   \\
+&\kw{accessor} \text{name} = \pds{exp}[\text{index}] \\
 \end{aligned}
 \]
-Given a name, an expression to access, the index at which to access, and optionally the accessor type, 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 variable with a UInt type.
+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 variable of UInt type.
 
-An untyped (unknown) accessor or a read accessor 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, an untyped accessor or a write accessor 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.
+An accessor is conceptually one-way; it must be consistently used to connect to, or to connect from, but not both.
 
-The following example demonstrates using untyped 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, \pds{reader}, acts as a memory read port that reads from the index specified by the wire \pds{i}.
+The accessor, \pds{writer}, acts as a memory write port that writes 42 to the index specified by wire \pds{j}.
 \[
 \begin{aligned}
-&\kw{wire} i : \kws{UInt}<5> \\
-&\kw{wire} j : \kws{UInt}<5> \\
-&\kw{mem} m : \kws{UInt}<10>[10] \\
+&\kw{wire} i : \kws{UInt}\kws{$<$} 5 \kws{$>$} \\
+&\kw{wire} j : \kws{UInt}\kws{$<$} 5 \kws{$>$} \\
+&\kw{mem} m : \kws{UInt}\kws{$<$} 10 \kws{$>$}[10] \\
 &\kw{accessor} reader = m[i] \\
 &\kw{accessor} writer = m[j] \\
-&writer := \kws{UInt}<?>(42) \\
+&writer := \kws{UInt}\kws{$<$} \kws{?} \kws{$>$}(42) \\
 &\kw{node} temp = reader \\
 \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.
+However, accessors are not restricted to accessing memories.
+They can be used to access {\em any} vector-valued type. 
+
+
+\subsection{Bi-Accessors}
+Bi-accessors are used for connecting to and from a vector-typed expression, from some {\em variable} index.
+A bi-accessor can be instantiated with the following statement.
+\[
+\begin{aligned}
+&\kw{bi-accessor} \text{name} = \pds{exp}[\text{index}] \\
+\end{aligned}
+\]
+Given a name, an expression to access, and the index at which to access, the above statement creates a bi-accessor that may be used for connecting to or from the expression.
+The expression must have a vector type, and the index must be a variable with a UInt type.
+
+A bi-accessor is conceptually two-way; it can be used to connect to, to connect from, or both, {\em but not on the same cycle}.
+If it is written to and read from on the same cycle, its behavior is undefined.
+
+The following example demonstrates using bi-accessors to read and write to a memory.
+The bi-accessor, \pds{readwrite}, acts as a memory read and write port that read/writes from the index specified by the wire \pds{i}.
+\[
+\begin{aligned}
+&\kw{wire} i : \kws{UInt}\kws{$<$} 5 \kws{$>$} \\
+&\kw{wire} value : \kws{UInt}\kws{$<$} 10 \kws{$>$} \\
+&\kw{mem} m : \kws{UInt}\kws{$<$} 10 \kws{$>$}[10] \\
+&\kw{bi-accessor} readwrite = m[j] \\
+&\kw{when} p : \\
+&\quad readwrite := \kws{UInt}\kws{$<$} \kws{?} \kws{$>$}(42) \\
+&\kw{else} : \\
+&\quad value := readwrite \\
+\end{aligned}
+\]
+
+Bi-accessors are not restricted to accessing memories.
 They can be used to access {\em any} vector-valued type. 
 
 \subsection{Instances}
@@ -317,17 +392,54 @@ The following statement is used to connect the output of some component, to the
 \text{input } \kw{:=} \text{output} 
 \]
 
-For a connection to be legal, the types of the two expressions must match exactly, including all field flips if the wires contain bundle types.
+For a connection to be legal, the types of the two expressions must match exactly, including all field orientations if the elements contain bundle types.
 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 On Reset Statement}
-The on-reset statement is used to specify the default value for a register. Its semantics are described in Section \ref{initialization}.
+\subsection{The Bulk Connect Statement}
+The bulk connect statement is a connect statement that does not require both expressions to be the same type. 
+During the lowering pass, the bulk connect will expand to some number of connect statements, possibly zero statements.
+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 bulk connect between two components of a bundle-type, fields that are of the same type, orientation, and name will be connected.
+Fields that do not match will not be connected.
+For a bulk connect between two components of a vector-type, the number of connected elements will be equal to the length of the shorter vector.
+A bulk connect between two components of the same ground type is equivalent to a normal connect statement.
+All other combinations of types will not error, but will not generate any connect statements.
+
+\subsection{The On-Reset Connect Statement}
+The on-reset connect statement is used to specify the default value for a \kws{reg} element.
+\[
+\kw{onreset} \text{r } \kw{:=} \text{output} 
+\]
+
+For a connection to be legal, the types of the two expressions must match exactly, including all field orientations if the elements contain bundle types.
+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 a \kws{reg} element.
+Memories cannot be initialized with this construct.
+
+By default, a \kws{reg} will not have a initialization value and will maintain their current value under the reset signal specified in their declaration.
+The following example demonstrates declaring a \kws{reg}, and changing its initialization value to forty two.
+
+\[
+\begin{aligned}
+& \kw{reg} r : \kws{UInt}\kws{$<$} 10 \kws{$>$} \kws{(} clk, \ reset \kws{)}\\
+& \kw{onreset} r := \kws{UInt}\kws{$<$} \kws{?} \kws{$>$}(42)
+\end{aligned}
+\]
+
+Note that structural registers, kws{Register}, cannot be assigned an initial value because they can only be used on the right side of a connect statement.
+
+\subsection{The Sub-Word Connect Statement}
+The subword connect statement is used to assigned to a range of bits within a ground-typed element.
 \[
-\kw{on-reset} \text{reg } \kw{:=} \text{output} 
+\text{exp}[\intsp \kw{through} \ints] \ \kw{:=} \text{output} 
 \]
 
-For a connection to be legal, the types of the two expressions must match exactly, including all field flips if the wires contain bundle types.
-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, and must be a reg.
+The subword is always UInt type, so for a connection to be legal, the expression on the right must also be of UInt type.
+The expression 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.
+In addition, the expression on the left-hand side must be a ground type, although this restriction may be relaxed in future spec releases.
 
 \subsection{The Conditional Statement}
 The conditional statement is used to specify a condition that must be asserted under which a list of statements hold.
@@ -347,9 +459,9 @@ In the following example, the wire w is connected to 42 when enable is asserted
 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{?}> \\
+&\kw{wire} w : \kws{UInt}\kws{$<$} \kws{?} \kws{$>$} \\
 &\kw{when} enable : \\
-&\quad w := \kws{UInt}<\kws{?}>(42) \\
+&\quad w := \kws{UInt}\kws{$<$} \kws{?} \kws{$>$}(42) \\
 \end{aligned}
 \]
 
@@ -377,9 +489,9 @@ 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{?}) \\
-&w := \kws{UInt}<\kws{?}>(20) \\
-&w := \kws{UInt}<\kws{?}>(42) \\
+&\kw{wire} w : \kws{UInt}\kws{$<$} \kws{?} \kws{$>$} \\
+&w := \kws{UInt}\kws{$<$} ? \kws{$>$}(20) \\
+&w := \kws{UInt}\kws{$<$} ? \kws{$>$}(42) \\
 \end{aligned}
 \]
 
@@ -387,10 +499,10 @@ By coupling the conditional statement with last connect semantics, many circuits
 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{?}) \\
-&w := \kws{UInt}<\kws{?}>(20) \\
+&\kw{wire} w : \kws{UInt}\kws{$<$} \kws{?} \kws{$>$} \\
+&w := \kws{UInt}\kws{$<$} \kws{?} \kws{$>$}(20) \\
 &\kw{when} enable : \\
-&\quad w := \kws{UInt}<\kws{?}>(42) \\
+&\quad w := \kws{UInt}\kws{$<$} \kws{?} \kws{$>$}(42) \\
 \end{aligned}
 \]
 
@@ -403,7 +515,7 @@ The empty statement is specified using the following.
 \]
 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. 
-In addition, it is useful for transformational pass writers.
+In addition, it is useful for transformation pass writers.
 
 \section{Expressions}
 
@@ -413,7 +525,7 @@ FIRRTL expressions are used for creating values corresponding to the ground type
 
 A value of type \kws{UInt} can be directly created using the following expression.
 \[
-\kws{UInt}<\text{width}>(\text{value})
+\kws{UInt}\kws{$<$} \pds{width} \kws{$>$}(\text{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.
@@ -422,7 +534,7 @@ If the width is specified as unknown, then FIRRTL infers the minimum possible wi
 
 A value of type \kws{SInt} can be directly created using the following expression.
 \[
-\kws{SInt}<\text{width}>(\text{value})
+\kws{SInt}\kws{$<$} \pds{width} \kws{$>$}(\text{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.
@@ -453,9 +565,9 @@ It is legal to use the subindex expression on any vector-valued expression, exce
 
 \subsection{Structural Register}
 \[
-\kws{Register}(\text{value}, \text{enable})   
+\kws{Register}(\text{value}, \text{enable}, \text{clk})
 \]
-A structural register is an unnamed register specified by the input value for the register and the enable signal for the register.
+A structural register is an unnamed register specified by the input value for the register, the enable signal for the register, and the clock port for the register.
 The type of the input must be a ground type and the enable signal must be a 1-bit unsigned integer. 
 
 \subsection{WritePort}
@@ -475,6 +587,17 @@ A read port is specified given the memory it accesses, the index into the memory
 The index must be an expression with an unsigned integer type and the enable signal must be a 1-bit unsigned integer. 
 The type of the ReadPort is the inside type of the memory's vector type.
 A ReadPort can only be used as an input (on the right side of a connect statement).
+A ReadPort's value when the enable signal is not asserted is undefined.
+
+\subsection{RdWrPort}
+\[
+\kws{RdWrPort}(\text{mem},\text{index},\text{wenable},\text{wdata},\text{renable})
+\]
+A read/write port is specified given the memory it accesses, the index into the memory, the write-enable signal determining when to write the write-data, the write-data, and the read-enable signal determining when to read the value.
+The index must be an expression with an unsigned integer type and both enable signals must be a 1-bit unsigned integer. 
+The type of the RdWrPort is the inside type of the memory's vector type.
+A RdWrPort can only be used as an input (on the right side of a connect statement).
+A RdWrPort's value is undefined when the renable signal is not asserted, or when both the renable and wenable are asserted.
 
 \subsection{Primitive Operation}
 \[
@@ -768,13 +891,13 @@ The output width of a dynamic shift right operation is the width of the original
 \[
 \begin{array}{rll}
 \kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\
-\kws{toSInt}(\pds{op}:UInt)      & SInt & width(op) + 1 \\
-\kws{toSInt}(\pds{op}:SInt)      & SInt & width(op) \\
+\kws{convert}(\pds{op}:UInt)      & SInt & width(op) + 1 \\
+\kws{convert}(\pds{op}:SInt)      & SInt & width(op) \\
 \end{array}
 \]
-The toSInt operation accepts either an unsigned or a signed integer.
+The convert operation accepts either an unsigned or a signed integer.
 The resultant value is always a signed integer.
-The output of a toSInt operation will be the same arithmetic value as the input value.
+The output of a convert operation will be the same arithmetic value as the input value.
 The output width is the same as the input width if the input is signed, and increased by one if the input is unsigned.
 
 \subsection{Negate}
@@ -792,10 +915,10 @@ If the input type is SInt, primop returns -1 * input value, as an SInt with the
 \[
 \begin{array}{rll}
 \kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\
-\kws{bit-not}     (\pds{op1:UInt}) & UInt & width(op1)    \\
-\kws{bit-and}     (\pds{op1:UInt}, \pds{op2:UInt}) & UInt & max(width(op1),width(op2))    \\
-\kws{bit-or}      (\pds{op1:UInt}, \pds{op2:UInt}) & UInt & max(width(op1),width(op2))    \\
-\kws{bit-xor}     (\pds{op1:UInt}, \pds{op2:UInt}) & UInt & max(width(op1),width(op2))    \\
+\kws{not}     (\pds{op1:UInt}) & UInt & width(op1)    \\
+\kws{and}     (\pds{op1:UInt}, \pds{op2:UInt}) & UInt & max(width(op1),width(op2))    \\
+\kws{or}      (\pds{op1:UInt}, \pds{op2:UInt}) & UInt & max(width(op1),width(op2))    \\
+\kws{xor}     (\pds{op1:UInt}, \pds{op2:UInt}) & UInt & max(width(op1),width(op2))    \\
 \end{array}
 \]
 The above operations correspond to bitwise not, and, or, and exclusive or respectively.
@@ -805,9 +928,9 @@ The operands must be unsigned integers, and the resultant width is equal to the
 \[
 \begin{array}{rll}
 \kws{primop} & \kws{Resultant Type} & \kws{Resultant Width} \\
-\kws{bit-and-reduce}     (\pds{op:UInt}*) & UInt & max(width(op)*)    \\
-\kws{bit-or-reduce}      (\pds{op:UInt}*) & UInt & max(width(op)*)    \\
-\kws{bit-xor-reduce}     (\pds{op:UInt}*) & UInt & max(width(op)*)    \\
+\kws{andr}     (\pds{op:UInt}*) & UInt & max(width(op)*)    \\
+\kws{orr}      (\pds{op:UInt}*) & UInt & max(width(op)*)    \\
+\kws{xorr}     (\pds{op:UInt}*) & UInt & max(width(op)*)    \\
 \end{array}
 \]
 The above operations correspond to bitwise not, and, or, and exclusive or respectively, reduced over a list of unsigned integers.
@@ -847,65 +970,42 @@ An index of zero indicates the least significant bit in the operand, and an inde
 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 on-reset construct for registers.
+\section{FIRRTL Forms}
 
-\subsection{Module Initialization}
-As stated before, all modules must have a port named reset defined.
+To simplify the writing of transformation passes, FIRRTL provides a {\em resolving} pass, which resolves all types, widths, and checks the legality of the circuit, and a {\em lowering} pass, which rewrites any FIRRTL circuit into an equivalent {\em lowered form}.
 
-\subsection{Register Initialization}
-By default, a register will not have a initialization value and will not be enabled during reset.
-Hence, the default reset behavior for registers is to maintain their current value.
+\subsection{Resolved Circuit}
 
-However, an explicit initialization value can be provided for a register by connecting an expression to the register via the on-reset construct.
-The following example demonstrates declaring a register, and changing its initialization value to forty two.
-\[
-\begin{aligned}
-& \kw{reg} r : \kws{UInt}<10> \\
-& on-reset r := \kws{UInt}<\kws{?}>(42)
-\end{aligned}
-\]
+The resolved form is guaranteed to be well-formed, meaning all restrictions to a FIRRTL circuit have been checked. In addition, all unknown widths have been resolved.
 
-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 cannot be assigned an initial value because they can only be used on the right side of a connect statement.
+\subsection{Lowered Circuit}
 
-\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. 
 
-In lowered form, every module has exactly the following form.
+In lowered form, every module has exactly the following form:
 \[
 \begin{aligned}
 &\kw{module} \text{name} :                                 \\
 &\quad \pds{port} \ldots                                   \\
-&\quad \kw{wire} \ldots                                    \\
-&\quad \text{connections to output ports} \ldots           \\
+&\quad \text{declarations} \  \vert \  \text{connections} \ldots   \\
 \end{aligned}
 \]
 
-The body of the module must consist of a list of wire declarations, followed by a series of connect statements.
+The body of the module must consist of a list of wire, node, memory and instance declarations, as well as a series of connect statements.
 The following restrictions also hold for modules in lowered form.
 
-\subsection{No Nested Expressions}
+\subsubsection{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 node, and referred to through a reference. 
 
-\subsection{No Composite Types}
+\subsubsection{No Composite Types}
 No module port or wire 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.
 
-\subsection{Single Connect}
+\subsubsection{Single Connect}
 Every wire declared can only be assigned to once within a module.
 
-\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.
-
-\section{Inlined Lowered Form}
+\subsection{Inlined Lowering Form}
 A further (and optional) 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. 
 
@@ -952,6 +1052,7 @@ The following shows an example of a simple module.
 module mymodule :
    input a: UInt<1>
    output b: UInt<1>
+   clock clk: UInt<1>
    b := a
 \end{verbatim}
 
@@ -969,9 +1070,9 @@ 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}
-{data: UInt<10>,
- valid: UInt<1>,
- flip ready: UInt<1>} 
+{default data: UInt<10>,
+ default valid: UInt<1>,
+ reverse ready: UInt<1>} 
 \end{verbatim}
 
 The vector type is specified by immediately postfixing a type with a bracketed integer literal.
@@ -981,13 +1082,14 @@ UInt<16>[10]
 \end{verbatim}
 
 \subsection*{Statements}
-The following examples demonstrate declaring wires, registers, memories, nodes, instances, and accessors. 
+The following examples demonstrate declaring wires, registers, memories, nodes, instances, accessors and bi-accessors. 
 \begin{verbatim}
 wire mywire : UInt<10>
-reg myreg : UInt<10>
-mem mymem : UInt<10>[16]
+reg myreg : UInt<10>, clk, reset
+mem mymem : UInt<10>[16], clk2
 inst myinst : MyModule
 accessor myaccessor = e[i]
+bi-accessor myaccessor = e[i]
 \end{verbatim}
 
 The connect statement is specified using the \verb|:=| operator.
@@ -995,9 +1097,19 @@ The connect statement is specified using the \verb|:=| operator.
 x := y
 \end{verbatim}
 
-The on-reset statement is specified using the on-reset keyword and  the \verb|:=| operator.
+The on-reset connect statement is specified using the onreset keyword and the \verb|:=| operator.
+\begin{verbatim}
+onreset x := y
+\end{verbatim}
+
+The bulk connect statement is specified using the \verb|<>| operator.
 \begin{verbatim}
-on-reset x := y
+x <> y
+\end{verbatim}
+
+The subword connect statement is specified with \verb|[| \verb|]| brackets after the expression on the left of the \verb|:=| operator. Within the brackets is the high bit index, followed by the keyword \verb|through|, followed by the low bit index.
+\begin{verbatim}
+x[3 through 0] := y
 \end{verbatim}
 
 The conditional statement is specified with the \verb|when| keyword.
@@ -1054,6 +1166,11 @@ Subindicies are expressed using the \verb|[]| operator.
 x[10]
 \end{verbatim}
 
+Structural registers are expressed using the Register constructor.
+\begin{verbatim}
+ReadPort(m, index, enable, clk)
+\end{verbatim}
+
 Read ports are expressed using the ReadPort constructor.
 \begin{verbatim}
 ReadPort(m, index, enable)
@@ -1064,6 +1181,11 @@ Write ports are expressed using the WritePort constructor.
 WritePort(m, index, enable)
 \end{verbatim}
 
+Read/Write ports are expressed using the RdWrPort constructor.
+\begin{verbatim}
+RdWrPort(m, index, wenable, wdata, renable)
+\end{verbatim}
+
 Primitive operations are expressed by following the name of the primitive with a list containing the operands. 
 \begin{verbatim}
 add(x, y)
@@ -1071,5 +1193,17 @@ add(x, add(x, y))
 shl(x, 42)
 \end{verbatim}
 
+\section{Future FIRRTL Specification Plans}
+Some choices were made during the design of this specification which were intentionally conservative, so that future versions could lift the restrictions if suitable semantics and implementations are determined. By restricting this version and potentially lifting them in future versions, all existing FIRRTL circuits will remain valid.
+
+The follow design decisions could potentially be changed in future spec revisions:
+\begin{enumerate}[topsep=3pt,itemsep=-0.5ex,partopsep=1ex,parsep=1ex]
+\item Disallowing subword assignments to non-ground-typed elements.
+\item Disallowing zero-width types
+\item Always expanding memories into smaller memories (if the type within the vector type is a non-ground-type)
+\item Not including a \kws{printf} node
+\item Not including a \kws{ROM} node
+\end{enumerate}
 
 \end{document}
+
diff --git a/src/lib/stanza.zip b/src/lib/stanza.zip
index 3a0be7ea..9549a65a 100644
--- a/src/lib/stanza.zip
+++ b/src/lib/stanza.zip
diff --git a/src/main/stanza/passes.stanza b/src/main/stanza/passes.stanza
index 53ef2f47..d7232996 100644
--- a/src/main/stanza/passes.stanza
+++ b/src/main/stanza/passes.stanza
@@ -1949,8 +1949,8 @@ public defn special-rename (original-sym:Symbol,new-sym:Symbol,c:Circuit) :
          else :
             if substring(st,0,length(os)) == os :
                add(y,ns)
-               println(st)
-               println(substring(st,length(os),length(st)))
+               ;println(st)
+               ;println(substring(st,length(os),length(st)))
                rename(substring(st,length(os),length(st)))
             else : 
                add(y,substring(st,0,1))
diff --git a/test/chisel3/ALUTop.fir b/test/chisel3/ALUTop.fir
index 2cb4c32e..a6fdfd95 100644
--- a/test/chisel3/ALUTop.fir
+++ b/test/chisel3/ALUTop.fir
@@ -100,19 +100,19 @@ circuit ALUTop :
     node alu_op2 = mux(T_233, UInt<4>(11), T_232)
     alu_op := alu_op2
   module ALUTop : 
-    input io_B : UInt<32>
-    output io_out : UInt<32>
-    input io_A : UInt<32>
-    input io_opcode : UInt<7>
-    input io_funct : UInt<3>
-    input io_add_rshift_type : UInt<1>
+    input B : UInt<32>
+    output out : UInt<32>
+    input A : UInt<32>
+    input opcode : UInt<7>
+    input funct : UInt<3>
+    input add_rshift_type : UInt<1>
     
     inst alu of ALU
     inst alu_dec of ALUdec
-    alu_dec.opcode := io_opcode
-    alu_dec.funct := io_funct
-    alu_dec.add_rshift_type := io_add_rshift_type
-    alu.A := io_A
-    alu.B := io_B
-    io_out := alu.out
+    alu_dec.opcode := opcode
+    alu_dec.funct := funct
+    alu_dec.add_rshift_type := add_rshift_type
+    alu.A := A
+    alu.B := B
+    out := alu.out
     alu.alu_op := alu_dec.alu_op
diff --git a/test/passes/to-verilog/gcd.fir b/test/passes/to-verilog/gcd.fir
index 170e7866..23a2d4f5 100644
--- a/test/passes/to-verilog/gcd.fir
+++ b/test/passes/to-verilog/gcd.fir
@@ -1,4 +1,4 @@
-; RUN: firrtl -i %s -o %s.v -X verilog -p c | tee %s.out | FileCheck %s
+; RUN: firrtl -i %s -o %s.v -X verilog -p cw  tee %s.out | FileCheck %s
 
 ;CHECK: Verilog
 circuit top :