setup: bump pyvcd to ~=0.2.

We don't use any of the deprecated functionality, and the added
requirement of Python 3.6+ matches ours.

Having a requirement for pyvcd ~=0.1.4 was actually the cause of
the error I tried to fix in commit 6e1145e2. It had nothing to do
with Jinja2 (though it is definitely still good to have the tighter
requirement on Jinja2); the cause of the error was that pip would
install Jinja2, schedule installing markupsafe, install pyvcd 0.2.0
and then choke on the pyvcd 0.1.4 requirement, which would prevent
it from installing markupsafe &c. Why it does that is beyond me.

Add support for using non-compat Elaboratable instances with compat.fhdl.verilog.convert and compat.run_simulation

Fixes #344

setup: tighten version constraint on Jinja2.

I remember thinking that not constraining it properly might bite us
someday, but assumed that Jinja2 will always stay version 2. Now it
looks like Jinja2 3.0.0a1 got released, pip picks it by default, and
it's currently broken (something about markupsafe missing).

Do what needed to be done in the first place.

hdl.ast: implement abs() on values.

vendor.lattice_ice40: add support for SB_[LH]FOSC as default_clk.

These oscillators are only available on iCE40 UltraPlus devices.

vendor: fix typo `async_ff_sync`

back.pysim: implement modulus operator.

Correctly handle resets in AsyncFIFO.

This commit improves handling of resets in AsyncFIFO in two ways:
  * First, resets no longer violate Gray counter CDC invariants.
  * Second, write domain reset now empties the entire FIFO.

vendor: fix a few issues in commit 2f8669ca.

lib.cdc: extract AsyncFFSynchronizer.

In some cases, it is necessary to synchronize a reset-like signal but
a new clock domain is not desirable. To address these cases, extract
the implementation of ResetSynchronizer into AsyncFFSynchronizer,
and replace ResetSynchronizer with a thin wrapper around it.

hdl.ast: fix off-by-1 in Initial.__init__().

back.pysim: fix RHS codegen for Cat() and Repl(..., 0).

Fixes #325.

back.pysim: optionally allow introspecting generated code.

nmigen.compat.genlib.cdc: add PulseSynchronizer.

nmigen.lib.cdc: port PulseSynchronizer.

Co-authored-by: Luke Wren <wren6991@gmail.com>

Travis: prune dependencies.

bitarray is not required since commit 7df70059.

Travis: test on Python 3.8.

cli: update use of deprecated code.

back.pysim: accept write_vcd(vcd_file=None).

Because write_vcd() is a context manager, this is useful if the VCD
file should be sometimes not written, since it avoids awkward
conditionals with duplicated code. It's not very elegant though.

Fixes #319.

setup: update project URLs.

doc: remove outdated files and references to them.

README: link to IRC channel.

README: consolidate requirements in the Installation section.

test_build_res: fix after commit 3e2ecdf2.

build.res,vendor: place clock constraint on port, not net, if possible.

For most toolchains, these are functionally identical, although ports
tend to work a bit better, being the common case. For Vivado, though,
it is necessary to place them on the port because its timing analyzer
considers input buffer delay.

Fixes #301.

xilinx_{7series,ultrascale}: run `report_methodology`.

This can expose important timing issues, such as #301.

hdl.ast: add Value.{as_signed,as_unsigned}.

Before this commit, there was no way to do so besides creating and
assigning an intermediate signal, which could not be extracted into
a helper function due to Module statefulness.

Fixes #292.

test_lib_fifo: define all referenced FSM states.

Broken in commit a1c58633.

hdl.dsl: make referencing undefined FSM states an error.

Before this commit, doing something like:

    with m.FSM():
        with m.State("FOO"):
            m.next = "bAR"
        with m.State("BAR"):
            m.next = "FOO"

would silently create an empty state `bAR` and get stuck in it until
the module is reset. This was done intentionally (in Migen, this code
would in fact miscompile), but in retrospect was clearly a bad idea;
it turns typos into bugs, while in the rare case that branching to
a completely empty state is desired, it is trivial to define one.

Fixes #315.

hdl.ir: type check ports.

Fixes #290.

back.pysim: emit toplevel inputs in VCD files as well.

Before this commit, only signals driven from fragments (in practice,
everything except toplevel inputs) would get written to a VCD file.
Not having toplevel inputs in the dump made debugging ~impossible.

After this commit, all signals the fragment refers to get written to
a VCD file. (More specifically, all signals the compiler assigns
an index to, i.e. signals the generated code reads or writes.)

Fixes #280.

back.pysim: make `write_vcd(traces=)` actually use those traces.

Reported in #280.

hdl.dsl: reject name mismatch in `m.domains.<name> +=`.

This would violate invariants later in the elaboration process.

Fixes #282.

hdl.dsl: type check when adding to m.domains.

hdl.mem: add synthesis attribute support.

Fixes #291.

hdl.mem: document Memory.

hdl.{ast,dsl}: allow whitespace in bit patterns.

Fixes #316.

hdl.ast: update documentation for Signal.

Fixes #288.

hdl.ast: prohibit shifts by signed value.

These are not desirable in a HDL, and currently elaborate to broken
RTLIL (after YosysHQ/yosys#1551); prohibit them completely, like
we already do for division and modulo.

Fixes #302.

build.plat: align pipeline with Fragment.prepare().

Since commit 7257c20a, platform code calls create_missing_domains()
before _propagate_domains_up() (as a part of prepare() call). Since
commit a7be3b48, without a platform, create_missing_domains() is
calle after _propagate_domains_up(); because of that, it adds
the missing domain to the fragment. When platform code then calls
prepare() again, this causes an assertion failure.

The true intent behind the platform code being written this way is
that it *overrides* a part of prepare()'s mechanism. Because it was
not changed when prepare() was modified in 7257c20a, the override,
which happened to work by coincidence, stopped working. This is
now fixed by inlining the relevant parts of Fragment.prepare() into
Platform.prepare().

This is not a great solution, but given the amount of breakage this
causes (no platform-using code works), it is acceptable for now.

Fixes #307.

hdl.dsl: don't allow inheriting from Module.

`Module` is an object with a lot of complex and sometimes fragile
behavior that overrides Python attribute accessors and so on.
To prevent user designs from breaking when it is changed, it is not
supposed to be inherited from (unlike in Migen), but rather returned
from the elaborate() method. This commit makes sure it will not be
inherited from by accident (most likely by users familiar with
Migen).

Fixes #286.

hdl.ast: warn on unused property statements (Assert, Assume, etc).

A property statement that is created but not added to a module is
virtually always a serious bug, since it can make formal verification
pass when it should not. Therefore, add a warning to it, similar to
UnusedElaboratable.

Doing this to all statements is possible, but many temporary ones are
created internally by nMigen, and the extensive changes required to
remove false positives are likely not worth the true positives.
We can revisit this in the future.

Fixes #303.

_unused: extract must-use logic from hdl.ir.

hdl.dsl: add missing case width check for Enum values.

Fixes #305.

README: clarify relationship to Migen.

hdl.dsl: make `if m.{If,Elif,Else}(...)` a syntax error.

A common typo, and hard to notice when it's silently ignored.

Fixes #284.

back.rtlil: don't emit wires for empty signals.

Fixes #312.

vendor.lattice_ecp5: support internal oscillator (OSCG).

build.dsl: allow strings to be used as connector numbers.

Fixes #311.

vendor.lattice_{ice40,ecp5}: Support .il (RTLIL) files in extra_files

Update README.

hdl.ir: resolve hierarchy conflicts before creating missing domains.

Otherwise, code such as:

    m.submodules.a = (something with cd_sync)
    m.submodules.b = (something with cd_sync)
    m.d.b_sync += x.eq(y)

causes an assertion failure.

Fixes #304 (again).

hdl.xfrm: transform drivers as well in DomainRenamer.

This is necessary because drivers may be late bound.

Fixes #304.

Remove everything deprecated in nmigen 0.1.

Closes #275.

Signal: allow to use integral Enum for reset value.

vendor.intel: fix output enable width for XDR=0 case.

Fixes #297.

build.run: fix indentation.

back.rtlil: do not consider unreachable array elements when legalizing.

Otherwise we produce invalid RTLIL.

hdl.mem: fix src_loc_at in ReadPort, WritePort.

hdl.ast: Fix width for unary minus operator on signed argument.

To properly represent a negation of a signed X-bit quantity we may, in
general, need a signed (X+1)-bit signal — for example, negation of
3-bit -4 is 4, which is not representable in signed 3 bits.

back.pysim: fix miscompilation of Signal(unsigned) - Signal(signed).

hdl.ast: actually remove simulator commands.

These were supposed to be removed in 7df70059, but I forgot.

vendor.intel: silence meaningless warnings in nMigen files

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.