* [ExportVerilog] Emit extra parentheses around reduction ops (#3357)

This closes #3001. This PR is a follow-up onto
reduction operators appear in the head of subexpression such as `a & b & &a & a`.
This PR fixes the issue by setting precedence of reduction ops to lowest.

Example:
```mlir
hw.module @foo(%a: i4, %b: i1) -> (o1:i1) {
  %one4 = hw.constant -1 : i4

  %and1 = comb.icmp eq %a, %one4 : i4
  %and2 = comb.icmp eq %a, %one4 : i4
  %and3 = comb.icmp eq %a, %one4 : i4
  %and = comb.and %and1, %b, %and2, %and3  : i1
  hw.output %and : i1
}
```

`circt-opt -export-verilog` produces:

```verilog
module Foo(
  input  [3:0] a,
  input        b,
  output       o1);

  assign o1 = (&a) & b & (&a) & (&a);
endmodule
```

* Update CI OS version and docker image

* Use v3

* Update buildAndTest.yml

When instances are grouped after extraction, the group module would
inherit the appropriate prefix from the DUT, but any hierarchical paths
pointing to it would not include the prefix. Fix this by using the same
name for the module and the hierarchical path.

Fixes #5961.

Fix a bug in the composition of the PrefixModules and ExtractInstances
passes.  Because the latter can generate modules with new names when
using the grouping feature, this module needs a prefix and does not
currently get one.  Change the PrefixModules pass to add a wildcat
attribute "prefix" to the DUT annotation.  This prefix is then used by
ExtractInstances to properly generate the module name.

This is a variant of the solution used for the GrandCentral pass where
the companion module annotation is given a wildcat attribute that stores
the prefix which is then used by the pass.

A better solution would be to reorder PrefixModules after
ExtractInstances.  However, this has complications with verbatim
metadata emission and the possibility of PrefixModules manipulating the
hierarchy (duplicating modules to resolve non-local prefixes).  There is
more discussion about this on the #4593.

Fixes #4593.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@sifive.com>
Co-authored-by: Jack Koenig <koenig@sifive.com>

This fixes nondeterminism caused by iteration over DenseMap. Instead use MapVector to guarantee determinism.

This adds extra guards for headers to avoid redefinition of macros. For example,
```
`ifdef PRINTF_COND
  `define PRINTF_COND_ (`PRINTF_COND)
`else  // PRINTF_COND
  `define PRINTF_COND_ 1
`endif // PRINTF_COND
```
will be emitted with additional ifndef guard:
```
`ifdef PRINTF_COND_
  `ifdef PRINTF_COND
    `define PRINTF_COND_ (`PRINTF_COND)
  `else  // PRINTF_COND
    `define PRINTF_COND_ 1
  `endif // PRINTF_COND
`endif
```

We need to add a comment `// VCS coverage exclude_file"` to all Grand
Central modules and interfaces.  When we needed something like this
previousl, it was previously handled by adding a `comment` attribute
onto `hw.module` and handled in lower to HW.

To support these new targets, we have to:

1. Add a comment attribute to SV interfaces.  To accomplish this, I used
   an optional string attribute.  I switched the printed format to print
   the attribute dictionary after the symbol name, which I think is more
   common across all our operations.
2. Update ExportVerilog to print this attribute.  The `emitComment`
   function can recognize null attributes and skip a comment.
3. Propagate a "comment" attribute on FIRRTL modules in LowerToHW to HW
   modules.  This was not added to the ODS arguments, similar to the
   `output_file` attribute.
4. Modify GrandCentral to attach these comments to generated modules and
   interfaces.

I tested this on a design and there were no more files in the `scope`
directory missing this attribute.

Co-authored-by: Hideto Ueno <uenoku.tokotoko@gmail.com>

* [FIRRTL] Remove empty modules in IMDCE (#3378)

This commit extends IMDCE to delete empty modules. A module is empty if
it doesn't have any argument, operation and annotation. In the post-processing,
we traverse modules in a post-order of the instance graph, and remove empty
modules and their instances in a bottom-up manner.

* [IMDCE] Forward constant output ports to caller sides (#3688)

This PR makes IMDCE propagate constant output ports to caller sides before
actually performing dataflow analysis so that we can eliminate constant output ports.

Fix a bug in Grand Central (GCT) Data/Mem Taps pass where Data Taps
could be produced with invalid XMRs.  An exhaustive test case is added
that checks all permutations of upwards and downwards XMRs including
corner cases where the tap module is a leaf and the root.

Fixes #3414.

Add a `Clock` input port type. Allow a `with` on that port to enter a
'clocking block', which the `Value.reg` function recognizes and uses as
the `clk` input. Implicitly enter a clocking block when a module has
exactly one `Clock` port.

In a few cases the variables were re-defined instead of checking
that the produced output matches an earlier matched name.

In two cases, drop use of a variable as the symbol name is known
(since it's given in the input IR) and should match.

Overriding __new__, while slick, was too complex. This is the suggested
way to do it, so make things simpler.

Add a helper utility to get the inner_sym attribute from any operation.
This commit removes any direct access to the inner_sym attribute, and instead 
uses a helper utility to get the inner_sym name of an operation.
This utility will be required to get the inner_sym name, when the inner_sym
 attribute is a complex Attribute instead of a StringAttr. This also reduces
 the number of changes required for a followup InnerSymAttr PR.

Tests can now use the `@testmodule` to reduce boilerplate such as system instantiation, generation, and printing.

In case of wrapping a function, `@testmodule` accepts kwargs which are passed to the function as arguments.

StructAttr was finally removed from upstream MLIR in
d883a02a7c2bb89000d0685749f062c9206ac40c. ESI had a peculiar usage of
StructAttr, ChannelBufferOptions, that did not migrate cleanly to the
new way of defining Attrs with multiple parameters. The issue was that
ChannelBufferOptions acted as a dictionary of attributes for
the ChannelBuffer op, but this adds an extra layer of key-value pair
nesting under the new scheme.

Since the two properties of ChannelBufferOptions were orthogonal, it was
cleaner to just define these as regular, scalar attributes directly on
ChannelBuffer.

This commit inlines these two properties of ChannelBufferOptions
directly onto ChannelBuffer and updates all the ESI code to directly
access the attributes on the ChannelBuffer op. It slightly changes the
assembly format in the case where no attributes are specified, where
instead of writing a pair of empty braces (`{ }`), the braces are
omitted altogether.

This ultimately simplified the custom assembly format parser, however,
since we can just directly use the `parseOptionalAttrDict()` method now.

The -gen-struct-attr-decls/defs option to MLIR tablengen, so having
these targets around in CMakeLists.txt was causing the build to fail,
even though they're not even used by these dialects.

Change the Grand Central (GCT) Data/Mem Taps pass to use relative XMRs
for taps that involve non-local annotations (NLAs).  Previously, NLA
paths were used as-is and did not factor into existing XMR minimization
code.  Change this by adding NLA path information to the existing
InstanceOp array used by minimization code.

This is done to fix issues where a user creates a Data/Mem Tap at a
specific point in the hierarchy and they wind up with an XMR that goes
_above_ this point in the design.  This creates problems for designs
that expect the XMR to be compartmentalized, but where the Chisel API
produces NLA paths that are absolute.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@sifive.com>

We modify the instance graph as dedup runs and have some issues with
iterator invalidation. This change copies the module list into a
separate array so we don't have to worry about instance graph updates.

This is not the most efficient solution and in the future we should find
something better.  See https://github.com/llvm/circt/issues/3387 for
more information.

This pass creates temporary NLA operations which are known to be dead
and sometimes are invalid, causing breakage during subsequent circuit
verification. The invalid NLA encountered is when the target is in the
root module, and so we end up making a one-element (InnerRef) NLA.

While we cannot delete incoming HierPath's attached to operations in
input IR without a more careful analysis of all possible users, any NLA
explicitly created in this pass can be reasoned about and removed at the
end for cleaner (and valid) IR.

This change restore behavior for deleting the HierPath's added in this
pass which was accidentally removed.

This fixes assertion failure on a real design.

InnerRef's are expensive to verify presently, as the InnerSymbol
portion requires walking the target operation (FModuleLike).

HierPathOps are chains of these, and so were especially
problematic in this regard.

This is a similar problem to verifying Symbol (SymbolTable) users,
and is solved in a similar way.

The primary components of the new approach:

1. Drive verification from the top of InnerRef resolution scope

Only walk the relevant IR once, parallelizing where makes sense.

2. Introduce an interface for verifying InnerRef's

Operations using InnerRef's can implement the interface
to opt-in to this new verification.

For (1), a new trait "InnerRefNamespace" is added to mark Operations
in which InnerRef's are resolved.  For now this is only added to CircuitOp.

For (2), introduce "InnerRefUserOpInterface" with a "verifyInnerRefs"
method, similar to SymbolOpUserInterface and verifySymbolUses.
Operations using InnerRef's should prefer this interface, at least for
purposes of verification: since `verifyInnerRefs` also provides the operation
with a SymbolTable, all the same verification done in `verifySymbolUses` can be
done together with verification involving resolving the InnerSymbol's.
(There's no need for a SymbolTableCollection within an InnerRefNamespace,
as there's only one SymbolTable, at the top level.)

In addition, InnerSymbolTable is fleshed out a bit so that it can be
used for basic lookups of InnerSymbols, and "InnerSymbolTableCollection"
is added that serves a similar purpose as SymbolTableCollection.
InnerRefNamespace is also a class (as well as the trait) that combines a
SymbolTable and the InnerSymbolTableCollection, for convenient access to both
in "verifyInnerRefs".

Some structural requirements are now explicitly checked.

This is a follow-up to #3344. Interesting names should be only created by parsers.
This commit replaces remaining uses of `InterestingName` with `DroppableName`.

This is required to match systemverilog semantics.

As an example, previously, the following:
```python
    m = NDArray((3, 3), dtype=types.i32)
    for i in range(3):
      for j in range(3):
        m[i][j] = types.i32(i * 3 + j)
```
would emit:
```
assign matrix_wire = {{{{32'h0}, {32'h1}, {32'h2}}}, {{{32'h3}, {32'h4}, {32'h5}}}, {{{32'h6}, {32'h7}, {32'h8}}}};
```

where correct behaviour is instead:
```
assign matrix_wire = {{{{32'h8}, {32'h7}, {32'h6}}}, {{{32'h5}, {32'h4}, {32'h3}}}, {{{32'h2}, {32'h1}, {32'h0}}}};
```

Modify the Grand Central (GCT) Views pass to generate SV
Verbatim-encoded XMRs that are as short as possible.  Do this with a
naive lowest-common ancestor (LCA) computation the prunes the XMR path
to start at the GCT View parent module (the module where the mapping
module containing the XMRs is instantiated).

Previously, the full non-local annotation (NLA) hierarchical path would
be blindly used under the assumption that this path was what the user
wanted.  This was problematic as the Chisel API will always generate an
absolute path starting from the FIRRTL circuit's main module instead of
a path starting from where the GCT API is used.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@sifive.com>

IMCP would preserve wires, but not registers with names.
From @uenoku

This is a step on the way to untangling logic in module.py to be specific to `MSFTModuleOp`.
Classes can now supply callbacks for generation and creation, which allows for creating, generating top-level ops that aren't necessarily  `MSFTModule(Extern)Op`s.

There is currently no rationale for explicitly annotating the type that states (a state register) should be inferred as for a machine op. Annotating it upon constructing the machine op is therefore just an extra burden on the front-end, and may also be a premature constraint.

As i see it, default behaviour should just be to infer a state type via. e.g. ceil_log2(# states) when lowering to hardware. If some other behaviour is needed, then this should be lowering specific.

Add statistic for counting names converted to "droppable".

While visiting, minor fixup to the test now that droppable is the default.

Don't create entries while reading from the map,
as sometimes this requires the map to grow which invalidates pointers to entries.

A PyCDE NDArrayserves as a Numpy view of a multidimensional CIRCT array (ArrayType).
The Matrix ensures that all assignments to itself have been properly converted to conform with insertion into the numpy array (circt_to_arr).
Once filled, a user can treat the NDArray as a numpy array. The underlying CIRCT array is not materialized until `to_circt` is called.

The NDArraycan be used both directly, as well as through PyCDE `ListValue`s. Users who use the `NDArray` directly have access to all numpy functions.
In reality, it will only be a subset of the numpy array functions which are safe to be used in a PyCDE context. Since using the numpy transformations is experimental, curating the set of allowed functions at the level of `ListValue`s seems like a safe starting point.

This commit filters the `HierPathOp`s that participate in an instance based on
 where it is being inlined at.
For example, If an `InstanceOp`  `@InlinedMod::@inst1` is being inlined to
 replace InstanceOp `@ParentMod::@inst2`, then only the `HierPathOps` 
that participate in both `@inst1` and `@inst2` are valid after inlining.
If a `HierPathOp` begins at `@InlinedMod::@inst1`, then it implicitly
 participates at all places, where `@InelinedMod` is instantiated.

This commit fixes a crash with the `ModuleInliner`, whenever an `InnerRef`
 is renamed without checking if it occurs in the current path.
 This triggers an assert when the `InnerRef` is renamed twice.

This pass performs inter-module liveness anaysis and deletes dead code
aggressively. A value is considered as alive if it is connected to a port
of public modules or a value with a symbol. We first populate alive values
into a set, and then propagate the liveness by looking at their dataflow.
The framework is almost same as IMCP except that lattice has two states
(knownAlive, assumedDead) and direction of propagation is opposite.