[docs] touchups (llvm#3194)

Lots of small fixes to documentation.

docs/Charter.md

@@ -3,7 +3,7 @@
 ## Abstract
 
 Recent trends in computer architecture have resulted in two core problems.
-Firstly, how do we design complex, heterogenous systems-on-chip mixing
+Firstly, how do we design complex, heterogeneous systems-on-chip mixing
 general purpose and specialized components?  Secondly, how do we
 program them?  We believe that design tools that represent and
 manipulate a wide variety of abstractions are central to solving these
@@ -134,7 +134,7 @@ transformation performed on RTL descriptions.
 
 ### Finite-State Machine + Datapath (FSMD)
 
-High-Level synthesis(HLS) of RTL designs from C code has become a common
+High-Level synthesis (HLS) of RTL designs from C code has become a common
 paradigm for accelerator design.
 Typically generating a high-performance implementation requires analysis
 and scheduling of the FSMD model in order to understand the performance

docs/GettingStarted.md

@@ -45,7 +45,7 @@ $ git submodule update
 *Note:* The repository is set up so that `git submodule update` performs a 
 shallow clone, meaning it downloads just enough of the LLVM repository to check 
 out the currently specified commit. If you wish to work with the full history of
-the LLVM repository, you can manually "unshallow" the the submodule:
+the LLVM repository, you can manually "unshallow" the submodule:
 
 ```
 $ cd llvm
@@ -116,7 +116,7 @@ the right thing.
 
 [Verilator](https://github.com/verilator/verilator) can be used to check
 SystemVerilog code. To run the tests, build or install a **recent** version
-of Verilator (at least v4.034, ideally v1.110 or later to avoid a known bug).
+of Verilator (at least v4.034, ideally v4.110 or later to avoid a known bug).
 (Some Linux distributions have *ancient* versions.) If Verilator is in your
 PATH, `build check-circt` should run the tests which require Verilator.
 
@@ -135,9 +135,8 @@ dependencies are installed on your system. They are:
 
 7) **Install Cap'nProto** (optional, affects ESI dialect only)
 
-Some of the ESI dialect code requires [libcapnp](https://capnproto.org/).
-(Specifically, the [cosimulation](ESI/cosim.md) component.) That code
-requires a version of libcapnp which is not yet part of a release. Most of
+Some of the ESI dialect code requires [libcapnp](https://capnproto.org/), 0.9.1 or newer.
+(Specifically, the [cosimulation](ESI/cosim.md) component.) Most of
 the ESI cosim integration tests also require the python bindings: pycapnp.
 The `utils/get-capnp.sh` script downloads, compiles, and installs a known
 good version to a directory within the circt source code. It optionally
@@ -151,10 +150,10 @@ Alternatively, you can use a docker image we provide via
 software suite for (mathematical) optimization. It provides a uniform interface
 to several open-source and commercial solvers, e.g. for linear programs and
 satisfiability problems. Here, it is optionally used in the static scheduling
-instructure. Binary distributions often do not include the required CMake build
-info. The `utils/get-or-tools.sh` script downloads, compiles, and installs a
-known good version to a directory within the CIRCT source code, where it is then
-picked up automatically by the build.
+infrastructure. Binary distributions often do not include the required CMake
+build info. The `utils/get-or-tools.sh` script downloads, compiles, and
+installs a known good version to a directory within the CIRCT source code,
+where it is then picked up automatically by the build.
 
 ## Windows: notes on setting up with Ninja
 

docs/RationaleComb.md

@@ -30,7 +30,7 @@ substrate that may be extended with higher level dialects mixed into it.
 
 ## Type System for `comb` Dialect
 
-TODO: Simple integer types, eventually parametricly wide integer type
+TODO: Simple integer types, eventually parametrically wide integer type
 `hw.int<width>`.  Supports type aliases.  See HW rationale for more info.
 
 ### Zero-bit integer width is not supported
@@ -156,13 +156,13 @@ discussed the tradeoffs of adding support for a single-operation mux.  Such a
 move has some advantages and disadvantages:
 
 1) It is another operation that many transformations would need to be aware of,
-   e.g. verilog emission would have to handle it, and peephole optimizations
-   would have to be aware of array_get and comb.mux.
+   e.g. Verilog emission would have to handle it, and peephole optimizations
+   would have to be aware of `array_get` and `comb.mux`.
 2) We don't have any known analyses or optimizations that are difficult to
    implement with the current representation.
 
 We agreed that we'd revisit in the future if there were a specific reason to
-add it.  Until then we represent the array_create/array_get pattern for
+add it.  Until then we represent the `array_create`/`array_get` pattern for
 frontends that want to generate this.
 
 ## Endianness: operand ordering and internal representation
@@ -197,12 +197,14 @@ them in lexical order.
 %arr456 = ... // {0x4, 0x5, 0x6}
 %arr78  = ... // {0x7, 0x8}
 %arr = comb.array_concat %arr123, %arr456, %arr78 : !hw.array<3 x i4>, !hw.array<3 x i4>, !hw.array<2 x i4>
-// %arr[0] = 0x6
-// %arr[1] = 0x5
-// %arr[2] = 0x4
-// %arr[3] = 0x3
-// %arr[4] = 0x2
-// %arr[5] = 0x1
+// %arr[0] = 0x8
+// %arr[1] = 0x7
+// %arr[2] = 0x6
+// %arr[3] = 0x5
+// %arr[4] = 0x4
+// %arr[5] = 0x3
+// %arr[6] = 0x2
+// %arr[7] = 0x1
 ```
 
 **Note**: This ordering scheme is unintuitive for anyone expecting C
@@ -231,7 +233,7 @@ operand list which created the array upon which the op is running.
 
 ## Bitcasts
 
-The bitcast operation represents a bitwise reinerpretation (cast) of a value.
+The bitcast operation represents a bitwise reinterpretation (cast) of a value.
 This always synthesizes away in hardware, though it may or may not be
 syntactically represented in lowering or export language. Since bitcasting
 requires information on the bitwise layout of the types on which it operates,
@@ -244,7 +246,7 @@ used to represent bit vectors. They are never padded or aligned.
 layout matches C -- the high index of array starts at the MSB. Array's 0th
 element's LSB located at array LSB.
 - **Structs**: The HW dialect defines a custom `StructType`. The in-hardware
-layout matchss C -- the first listed member's MSB corresponds to the struct's
+layout matches C -- the first listed member's MSB corresponds to the struct's
 MSB. The last member in the list shares its LSB with the struct.
 - **Unions**: The HW dialect's `UnionType` could contain the data of any of the
 member types so its layout is defined to be equivalent to the union of members
@@ -347,7 +349,8 @@ because
 - `extract` gets "closer" to underlying `add/sub/xor/op` operations, giving way
   optimizations like narrowing.
 - the form gives a more accurate view of the values that are being depended on.
-- redundant extract operations can be removed from the concat args lists, eg:
+- redundant extract operations can be removed from the concat argument lists,
+  e.g.:
   `cat(extract(a), b, c, extract(d))`
 
 Both forms perform similarly on hardware, since they are simply bit-copies.

docs/RationaleESI.md

@@ -8,7 +8,7 @@ to standardize the signaling protocols there are many minor and major
 variants, both of which lead to confusion which can cause real problems when
 one is listening to and twiddling the wires manually. ESI solves this by
 providing a simple, intuitive, common, and standardized interface to developers
-then figures out the signaling details and conversions between then.
+and then figures out the signaling details and conversions between them.
 
 While the ABI/signaling problem is slowly being partially solved, it does not
 speak to the types of data on the wires – the software analogy being memory

docs/RationaleFIRRTL.md

@@ -44,8 +44,8 @@ FIRRTL specification and is actively maintained, tracking new enhancements. The
 FIRRTL dialect supports some undocumented features and the "CHIRRTL" flavor of
 FIRRTL IR that is produced from Chisel.  The FIRRTL dialect has support for
 parsing an SFC Annotation file consisting of only local annotations and
-converting this to operation or argument attributes.  Non-local annotation
-support is planned, but not implemented.
+converting this to operation or argument attributes.  Non-local annotations
+are also supported.
 
 There are some exceptions to the above:
 
@@ -379,7 +379,7 @@ result value of the `firrtl.mem` operation.  Also, the `firrtl.mem` node does
 not allow zero port memories for simplicity.  Zero port memories are dropped by
 the .fir file parser.
 
-In the FIRRTL pipeline, the firrtl.mem op can be lowered into either a external
+In the FIRRTL pipeline, the `firrtl.mem` op can be lowered into either a external
 module for macro replacement or a register of vector type. The conditions for
 macro replacement are as follows:
 
@@ -570,7 +570,7 @@ firrtl.connect %out, %myport_data : !firrtl.uint<1>, !firrtl.uint<1
 
 The CHIRRTL operations and types are contained in the CHIRRTL dialect.  The is
 primary reason to move them into their own dialect was to keep the CHIRRTL
-types out of the FIRRTL dialect type hiearchy. We tried to have the CHIRRTL
+types out of the FIRRTL dialect type hierarchy. We tried to have the CHIRRTL
 dialect depend on the FIRRTL dialect, but the flow checking in FIRRTL had to
 know about CHIRRTL operations, which created a circular dependency.  To
 simplify how this is handled, both dialects are contained in the same library.

docs/RationaleFSM.md

@@ -54,7 +54,7 @@ don't have such a semantics -- SW IRs “run” sequentially.
 Here we define that each *trigger* causes the possibility of a transition from
 one state to another state through exactly one transition.  In a SW context,
 `fsm.instance` generates an `InstanceType` value to represent a state machine
-instance.  Each `fsm.trigger` targets a machine instance and explicilty causes a
+instance.  Each `fsm.trigger` targets a machine instance and explicitly causes a
 *trigger*.  Therefore, `fsm.trigger` may change the state of the machine
 instance thus is a side-effecting operation.  The following MLIR code shows an
 example of instantiating and triggering the state machine defined above:
@@ -74,7 +74,7 @@ func @bar() {
 In the contrast, to comply with the HW semantics, `fsm.hw_instance` directly
 consumes inputs and generates results.  The operand and result types must align
 with the type of the referenced `fsm.machine`.  In a HW context, *trigger*s are
-implicilty initiated by the processors of `fsm.hw_instance`.  The following
+implicitly initiated by the processors of `fsm.hw_instance`.  The following
 MLIR code shows an example of instantiating the same state machine in HW IRs:
 
 ```mlir

docs/RationaleHW.md

@@ -35,7 +35,7 @@ standard language for hardware design and verification, is known by a large
 number of engineers who write it manually, and is
 an important interchange format between EDA tools.  However, while it is
 ubiquitous, SystemVerilog is not easy to generate or transform.  Furthermore, it
-is non-trivial for compiler tools to generate high quality human readable
+is non-trivial for compiler tools to generate high-quality human-readable
 SystemVerilog.
 
 The `hw`, `comb` and `sv` dialects attempt to address these problems with
@@ -144,7 +144,7 @@ notable differences: for example:
  - The `comb` dialect in particular does not use signed integer types, its
    operators do not support zero-width integer types.  Modules in the `hw` dialect,
    on the other hand, do support both of these.  Zero width ports are omitted (printed as
-   comments) when generating verilog.
+   comments) when generating Verilog.
 
 ### GlobalRefOp
 The GlobalRefOp operation (`hw.globalRef`) can be used to identify the unique
@@ -213,7 +213,7 @@ This allows for metaprogramming along the instance tree, guaranteed
 "instantiation time" optimizations and code generation, further enables
 the "IR compression" benefits of using instances in the first place, and enables
 the generation of parameters in generated Verilog (which can increase the
-percieved readability of the generated code).
+perceived readability of the generated code).
 
 Parameters are declared on modules (including generated and external ones)
 with angle brackets: each parameter has a name and type, and can optionally
@@ -272,7 +272,7 @@ module:
   rules to ensure important cases are canonicalized to uniquable
   representations.
 - `#hw.param.verbatim<"some string">` may be used to provide an opaque blob of
-  textual verilog that is uniqued by its string contents.  This is intended
+  textual Verilog that is uniqued by its string contents.  This is intended
   as a general "escape hatch" that allows frontend authors to express anything
   Verilog cannot, even if first-class IR support doesn't exist yet.  CIRCT does not
   provide any checking to ensure that this is correct or safe, and assumes it
@@ -318,8 +318,8 @@ well.
 
 On the other hand, we expect to support a lot of weird expressions over time (at
 least the full complement that Verilog supports) and canonicalize arbitrary
-expressions in a predictable way is untennable.  As such, we support
-canonicalizating a fixed set of expressions predictably: more may be added in
+expressions in a predictable way is untenable.  As such, we support
+canonicalizing a fixed set of expressions predictably: more may be added in
 the future.
 
 This set includes:
@@ -446,7 +446,7 @@ All that said, using attributes is the right thing for a number of reasons:
 3) We need to support parameterized types like `!hw.int<n>`: because MLIR types
    are immortal and uniqued, they can refer to attributes but cannot refer to
    [SSA values](https://en.wikipedia.org/wiki/Static_single_assignment_form)
-   (which may be destoyed).
+   (which may be destroyed).
 4) Operations need to be able to compute their own type without creating other
    operations.  For example, we need to compute that the result type of
    `comb.concat %a, %b : (i1, !hw.int<n>)` is `!hw.int<n+1>` without introducing
@@ -545,7 +545,7 @@ Until then, we must duplicate the type in the IR.
 
 Verilog has a broad notion of what can be named outside the context of its
 declaration.  This is compounded by the many tools which have additional source
-files which refer to verilog names (e.g. tcl files).  However, we do not want to
+files which refer to Verilog names (e.g. tcl files).  However, we do not want to
 require that every wire, register, instance, localparam, port, etc which can be
 named not be touched by passes.  We want only entities marked as public facing
 to impede transformation.
@@ -564,15 +564,15 @@ references are more general, SV and HW dialects do not define symbol tables for
 modules.  Therefore, wires, registers, and interfaces exist in the same
 namespace as modules.  It is encouraged that one prefaces the names to avoid
 conflict with modules.  The symbol names on these entities has no bearing on the
-output verilog, each of these entities has a defined way to assign its name (SSA
+output Verilog, each of these entities has a defined way to assign its name (SSA
 value name for wires and regs, a non-optional string for instances).
 
 As MLIR symbol support improves, it is desired to move to per-module symbol
 tables and to unify names with symbol names.
 
 **Ports**
 
-Module ports are remotely namable entities in Verilog, but are not easily named
+Module ports are remotely nameable entities in Verilog, but are not easily named
 with symbols.  A suggested workaround is to attach a wire to a port and use its
 symbol for remote references.  Instance ports have a similar problem.
 

docs/RationaleHandshake.md

@@ -6,11 +6,11 @@ This document also explains in a high-level manner how different components are
 organized, the principles behind them and the conventions we followed.
 The document assume that you have basic understanding of 
 [asynchronous digital circuits](https://en.wikipedia.org/wiki/Asynchronous_circuit) 
-at the behavioral level abstraction.
+at the behavioral level of abstraction.
 
 ## Principle
 
-Handshake/dataflow IR is describes independent, unsynchronized processes 
+Handshake/dataflow IR describes independent, unsynchronized processes
 communicating data through First-in First-out (FIFO) communication channels. 
 This can be implemented in many ways, such as using synchronous logic, or with 
 processors. 
@@ -40,7 +40,7 @@ can also lower the std MLIR produced by different frontends to Handshake IR.
 
 ## IR Representation
 
-Simple Handshake IR snippet for add function look like this -
+Simple Handshake IR snippet for an add function looks like this -
 ```
 handshake.func @simple_addi(%arg0: index, %arg1: index, %arg2: none, ...) -> (index, none) {
         %0 = addi %arg0, %arg1 : index

docs/RationaleSV.md

@@ -84,7 +84,7 @@ that is lowered to the `indexed part-select` operation.
  The `sv.part_select` is defined on `Integer` type input and 
  `sv.part_select_inout` is defined on `inout` type.
 
- Part select consits of 3 arguments, the input value,
+ Part select consists of 3 arguments, the input value,
  a `width` and a `base` and an optional boolean attribute `decrement`.
  The `width` shall be a compile-time constant expression. 
  The `base` can be a runtime integer expression. 

docs/RationaleSeq.md

@@ -105,7 +105,7 @@ optimization) another op could be added.
 do not detect and generate the SystemVerilog correctly), we can build it into
 the compreg op.
 - Reset style and clock style: how should we model posedge vs negedge clocks?
-Async vs sync resets? There are some reasonble options here: attributes on
+Async vs sync resets? There are some reasonable options here: attributes on
 this op or `clock` and `reset` types which are parameterized with that
 information.
 - Initial value: this register is uninitialized. Using an uninitialized value