back.pysim: redesign the simulator.

The redesign introduces no fundamental incompatibilities, but it does
involve minor breaking changes:
  * The simulator commands were moved from hdl.ast to back.pysim
    (instead of only being reexported from back.pysim).
  * back.pysim.DeadlineError was removed.

Summary of changes:
  * The new simulator compiles HDL to Python code and is >6x faster.
    (The old one compiled HDL to lots of Python lambdas.)
  * The new simulator is a straightforward, rigorous implementation
    of the Synchronous Reactive Programming paradigm, instead of
    a pile of ad-hoc code with no particular design driving it.
  * The new simulator never raises DeadlineError, and there is no
    limit on the amount of delta cycles.
  * The new simulator robustly handles multiclock designs.
  * The new simulator can be reset, such that the compiled design
    can be reused, which can save significant runtime with large
    designs.
  * Generators can no longer be added as processes, since that would
    break reset(); only generator functions may be. If necessary,
    they may be added by wrapping them into a generator function;
    a deprecated fallback does just that. This workaround will raise
    an exception if the simulator is reset and restarted.
  * The new simulator does not depend on Python extensions.
    (The old one required bitarray, which did not provide wheels.)

Fixes #28.
Fixes #34.
Fixes #160.
Fixes #161.
Fixes #215.
Fixes #242.
Fixes #262.

back.rtlil: infer bit width for instance parameters.

Otherwise, Yosys assumes it is always 32, which is often
inappropriate.

hdl.ir: for instance ports, prioritize defs over uses.

Fixes #274.

vendor.xilinx_*: Set IOB attribute on cels instead of nets.

back.rtlil: extend shorter operand of a binop when matching sign.

This is necessary because converting a large unsigned value to
a signed value of the same width may change its sign.

Fixes #271.

build.plat: in Platform.add_file(), allow adding exact duplicates.

test: add tests for build.plat.Platform.add_file.

hdl.rec: fix Record.like() being called through a subclass.

The subclass does not necessarily take layout as the first argument.

hdl.rec: make Record(name=) keyword-only.

Everywhere else, the name argument is already keyword-only, so
change it here too for consistency.

hdl.ir: lower domains before resolving hierarchy conflicts.

Otherwise, two subfragments with the same local clock domain would
not be able to drive its clock or reset signals. This can be easily
hit if using two ResetSynchronizers in one module.

Fixes #265.

Improve .gitignore.

Fixes #264.

back.verilog: remove $verilog_initial_trigger after proc_prune.

$verilog_initial_trigger was introduced to work around Verilog
simulation semantics issues with `always @*` statements that only
have constants on RHS and in conditions. Unfortunately, it breaks
Verilator. Since the combination of proc_prune and proc_clean passes
eliminates all such statements, it can be simply removed when both
of these passes are available, currently on Yosys master. After
Yosys 0.10 is released, we can get rid of $verilog_initial_trigger
entirely.

test: use `#nmigen:` magic comment instead of monkey patch.

Also, fix missing and incorrect src_loc_at arguments where
appropriate so the testsuite passes without warnings.

hdl.ir: allow disabling UnusedElaboratable warning in file scope.

This warning is usually quite handy, but is problematic in tests:
although it can be suppressed by using Fragment.get on elaboratable,
that is not always possible, in particular when writing tests for
exceptions raised by __init__, e.g.:

    def test_wrong_csr_bus(self):
        with self.assertRaisesRegex(ValueError, r"blah blah"):
            WishboneCSRBridge(csr_bus=object())

In theory, it should be possible to suppress warnings per-module
and even per-line using code such as:

    import re, warnings
    from nmigen.hdl.ir import UnusedElaboratable
    warnings.filterwarnings("ignore", category=UnusedElaboratable,
                            module=re.escape(__name__))

Unfortunately, not only is this code quite convoluted, but it also
does not actually work; we are using warnings.warn_explicit() because
we collect source locations on our own, but it requires the caller
to extract the __warningregistry__ dictionary from module globals,
or warning suppression would not work. Not only is this not feasible
in most diagnostic sites in nMigen, but also I never got it to work
anyway, even when passing all of module, registry, and module_globals
to warn_explicit().

Instead, use a magic comment at the start of a file to do this job,
which might not be elegant but is simple and practical. For now,
only UnusedElaboratable can be suppressed with it, but in future,
other linter parameters may become tweakable this way.

back.rtlil: avoid exponential behavior when legalizing Part().

Fixes #259.

back.rtlil: fix lowering of Part() on LHS to account for stride.

hdl.ast: simplify {bit,word}_select with constant offset.

We don't have any other convenient shortcut for x[off*w:(off+1)*w],
but using word_select to extract a single static range would result
in severe bloat of emitted code through expansion to dead branches.
Recognize and simplify this pattern.

Explicitly restrict prelude imports.

It turns out that while Python does not import _private identifiers
when using * imports, it does nevertheless import all submodules.

Avoid polluting the namespace in the prelude by explicitly listing
all exported identifiers.

compat.fhdl.specials: fix argument parsing compatibility.

lib.io: use keyword-only arguments in Pin().

setup: fix commit 5198d99b.

verilog: fix yosys version error message

back.verilog: fix Yosys version check.

setup: don't append local version for tags.

PyPI rejects any archives with local version.

vendor.lattice_ice40: fix commit 88649def.

vendor.lattice_{ice40,ecp5}: fix typo.

vendor.lattice_ice40: use pcf files instead of pre-pack Python scripts.

This allows to use nextpnr-ice40 built without Python with nMigen.
Requires nextpnr revision
YosysHQ/nextpnr@8c0610e84fa6a38d3f351774bd81a32c96a91242 or newer.

build.plat: batch files use EQU, not EQ.

{,_}tools→{,_}utils

In context of nMigen, "tools" means "parts of toolchain", so it is
confusing to have a completely unrelated module also called "tools".

vendor.lattice_{ice40,ecp5}: emit Verilog as well, for debugging.

build.plat: fold emit_prelude() into emit_commands().

Commit a783e464 broke all toolchains using bash.

Refactor build script toolchain lookups.

Now environment variable overrides no longer infect the build scripts.

_toolchain.overrides is dropped as probably misguided in the first place.

Fixes #251.

hdl.ir: allow ClockSignal and ResetSignal in ports.

Fixes #248.

hdl.ir: cast instance port connections to Values.

Fixes #249.

compat.fhdl.decorators: improve backwards compatibility.

compat.fhdl.bitcontainer: update Value.wrap call.

doc: bring COMPAT_SUMMARY up to date.

Fixes #112.

compat.genlib.fsm: add migration warning.

compat.fhdl.decorators: add migration warnings.

hdl.ast: rename Slice.end back to Slice.stop.

It used to be called .stop in oMigen, and it's also called .stop in
Python range and slice objects, so keep that.

compat.fhdl.structure: remove SPECIAL_* constants.

They cannot be used with nMigen designs since nMigen does not have
specials.

_tools: extract most utility methods to a private package.

We don't want to guarantee backwards compatibility for most of them.

back.rtlil: fix DeprecationWarning. NFC.

Rename remaining `wrap` methods to `cast`.

Following commit d72d4a55.

hdl.ast: deprecate shapes like `(1, True)` in favor of `signed(1)`.

This is a great improvement in clarity.

hdl.ast: deprecate Signal.{range,enum}.

Although constructor methods can improve clarity, there are many
contexts in which it is useful to use range() as a shape: notably
Layout, but also Const and AnyConst/AnyValue. Instead of duplicating
these constructor methods everywhere (which is not even easily
possible for Layout), use casting to Shape, introduced in 6aabdc0a.

Fixes #225.

hdl.ast: add an explicit Shape class, included in prelude.

Shapes have long been a part of nMigen, but represented using tuples.
This commit adds a Shape class (using namedtuple for backwards
compatibility), and accepts anything castable to Shape (including
enums, ranges, etc) anywhere a tuple was accepted previously.

In addition, `signed(n)` and `unsigned(n)` are added as aliases for
`Shape(n, signed=True)` and `Shape(n, signed=False)`, transforming
code such as `Signal((8, True))` to `Signal(signed(8))`.
These aliases are also included in prelude.

Preparation for #225.

Consistently use {!r}, not '{!r}' in diagnostics.

This can cause confusion:
  * If the erroneous object is None, it is printed as 'None', which
    appears as a string (and could be the result of converting None
    to a string.)
  * If the erroneous object is a string, it is printed as ''<val>'',
    which is a rather strange combination of quotes.

hdl.ast: Operator.{op→operator}

Both "operator" and "operand" were shortened to "op" in different
places in code, which caused confusion.

hdl.ast: simplify enum handling.

hdl.ast: Value.{wrap→cast}

Preparation for #225.

vendor.xilinx_ultrascale: new supported family.

xilinx_7series: add grade platform property.

For some devices grade has to be omitted, so it is optional.

vendor.lattice_machxo2: new supported family.

vendor: yosys is a required tool for all Verilog-based flows.

README: add device support matrix.

vendor.intel: add Quartus support.

Co-authored-by: Dan Ravensloft <dan.ravensloft@gmail.com>

examples: update blinky, add some explanatory text about domains.

build.plat: elaborate result of create_missing_domain() against platform.

Before this commit, the result was elaborated without platform, which
caused generic implementation of e.g. ResetSynchronizer to be used.

build.plat: don't create default sync domain as reset-less.

build.plat,vendor: always synchronize reset in default sync domain.

This change achieves two related goals.

First, default_rst is no longer assumed to be synchronous to
default_clk, which is  the safer option, since it can be connected to
e.g. buttons on some evaluation boards.

Second, since the power-on / configuration reset is inherently
asynchronous to any user clock, the default create_missing_domain()
behavior is to use a reset synchronizer with `0` as input. Since,
like all reset synchronizers, it uses Signal(reset=1) for its
synchronization stages, after power-on reset it keeps its subordinate
clock domain in reset, and releases it after fabric flops start
toggling.

The latter change is helpful to architectures that lack an end-of-
configuration signal, i.e. most of them. ECP5 was already using
a similar scheme (and is not changed here). Xilinx devices with EOS
use EOS to drive a BUFGMUX, which is more efficient than using
a global reset when the design does not need one; Xilinx devices
without EOS use the new scheme. iCE40 requires a post-configuration
timer because of BRAM silicon bug, and was changed to add a reset
synchronizer if user clock is provided.

back.rtlil: don't crash legalizing values with no branches.

Fixes #239.

back.rtlil: avoid unsoundness for division by zero.

Fixes #238.

hdl.ast: prohibit signed divisors.

See #238.

build.dsl: accept Pins(invert=True).

The PinsN() form is still preferred, but Pins(invert=) form is useful
for code generic over pin polarity.

hdl.ast: don't crash on Mux(<bool>, ...).

Fixes #240.

back.rtlil: don't cache wires for legalized switch tests.

This causes miscompilation of code such as:

  r = Array([self.a, self.b])
  m = Module()
  with m.If(r[self.s]):
      m.d.comb += self.o.eq(1)
  return m

back.rtlil: sign of rhs and lhs of ${sshr,sshl,pow} don't need to match.

back.rtlil: it is not necessary to match binop operand width.

rpc: add public Records as module ports.

rpc: add support for Yosys RPC protocol.

hdl.ast: actually implement the // operator.

hdl.dsl: add a diagnostic for `m.d.submodules += ...`.

hdl.mem: remove WritePort(priority=) argument.

The write port priority in Yosys is derived directly from the order
in which the ports are declared in the Verilog frontend. It is being
removed for several reasons:
  1. It is not clear if it works correctly for all cases (FFRAM,
     LUTRAM, BRAM).
  2. Although it is roundtripped via Verilog with correct simulation
     semantics, the resulting code has a high chance of being
     interpreted incorrectly by Xilinx tools.
  3. It cannot be roundtripped via FIRRTL, which is an alternative
     backend that is an interesting future option. (FIRRTL leaves
     write collision completely undefined.)
  3. It is a niche feature that, if it is needed, can be completely
     replaced using an explicit comparator, priority encoder, and
     write enable gating circuit. (This is what Xilinx recommends
     for handling this case.)

In the future we should extend nMigen's formal verification to assert
that a write collision does not happen.

back.rtlil: fix handling of certain nested arrays.

This triggers on code like:

c1 = Signal()
c2 = Signal()
c3 = Signal()
v1 = Array([Const(1, 8), Const(2, 8)])[c1]
v2 = Array([Const(3, 8), Const(4, 8)])[c2]
v3 = Array([v1, v2])[c3]

Fixes #226.

build.plat: strip internal attributes from Verilog output.

Although useful for debugging, most external tools often complain
about such attributes (with notable exception of Vivado). As such,
it is better to emit Verilog with these attributes into a separate
file such as `design.debug.v` and only emit the attributes that were
explicitly placed by the user to `design.v`.

This still leaves the (*init*) attribute. See #220 for details.

build.plat,lib.cdc,vendor: unify platform related diagnostics. NFC.

lib.cdc: specify maximum input delay in seconds.

Since we use hertz elsewhere, this provides for easy conversions.

Also, cast the delay to string before applying it in xilinx_7series,
to avoid stripping the fractional digits.

Closes #234.

vendor.xilinx_spartan_3_6: explain why ASYNC_REG is used. NFC.

vendor.lattice_ecp5: correct a typo in tristate buffer generation

vendor.xilinx_7series: apply false path / max delay constraints.

vendor.xilinx_7series: simplify. NFC.

vendor.xilinx_7series: override reset synchronizer.

lib.cdc: add diagnostic checks for synchronization stage count.

lib.cdc: expand ResetSynchronizer documentation.

Loosely based on work by @Wren6991.

lib.cdc: avoid modifying synchronizers in their elaborate() method.

vendor.xilinx_spartan_3_6: override reset synchronizer.

README: add a section on migrating from Migen.

lib.cdc: MultiReg→FFSynchronizer.

Fixes #229.

hdl.ast: cast Mux() selector to bool if it is not a 1-bit value.

Fixes #232.

back.rtlil: give predictable names to anonymous subfragments.

This is required for applying constraints to clocks in anonymous
subfragments in build.plat.

lib.fifo: handle depth=0, elaborating to a dummy FIFO with no logic.

hdl.mem,lib.fifo: use keyword-only arguments for memory geometry.

Fixes #230.

hdl.mem: simplify. NFC.

hdl.ast: make Signal(name=) a keyword-only argument.

Almost no code would specify Signal(_, name) as a positional argument
on purpose, but forgetting parens and accidentally placing signedness
into the name position is so common that we had a test for it.

lib.fifo: change FIFOInterface() diagnostics to follow Memory().

lib.fifo: round up AsyncFIFO{,Buffered} depth to lowest valid value.

Unless exact_depth=True is specified.

The logic introduced in this commit is idempotent: that is, if one
uses the depth of one AsyncFIFOBuffered in the constructor of another
AsyncFIFOBuffered, they will end up with the same depth. More naive
logic would result in an unbounded, quadratic growth with each such
step.

Fixes #219.

lib.fifo: make simulation read() and write() functions compat-only.

These functions were originally changed in 3ed51938, in an attempt
to make them take one cycle instead of two. However, this does not
actually work because of drawbacks of the simulator interface.

Avoid committing to any specific implementation for now, and instead
make them compat-only extensions.

hdl.rec: fix using Enum subclass as shape if direction is specified.

Also improves error messages.

Fixes #224.

hdl.rec: allow using Enum subclass as shape.

Fixes #223.