minor cleanup of __Cat__ and Cat to more compact code

add redirection of __Cat__ to allow overrides for more advanced behaviour
without changing fundamental language characteristics or semantics in nmigen

https://bugs.libre-soc.org/show_bug.cgi?id=458

this one is slightly more involved than __Repl__, __Mux__, __Switch__ etc.
because Cat() can receive arbitrary objects including generators.
exactly as is done in what is now _InternalCat, the arguments need to
be flattened and individually Value.cast()ed, however *before* doing
so, the first argument needs to be inspected and treated separately,
because the first argument is the one on which __Cat__ shall be called.

    args[0].__Cat__(*args[1:])

therefore it must not be lowered because its type (a derivative of
UserValue) would be entirely lost through the Value.cast().

add redirection of __Repl__ to allow overrides for more advanced behaviour
without changing fundamental language characteristics or semantics in nmigen
https://bugs.libre-soc.org/show_bug.cgi?id=458

remove Mux Value.cast before passing to 1st argument __Mux__
only one case requires Mux to perform Value.cast, which is when the sel
argument is a python bool

add redirection of __Assign__ to allow overrides for advanced behaviour
without changing fundamental language characteristics or semantics of nmigen
https://bugs.libre-soc.org/show_bug.cgi?id=458

add redirection of __Switch__ to allow overrides for advanced behaviour
without changing fundamental language characteristics or semantics in nmigen
https://bugs.libre-soc.org/show_bug.cgi?id=458

add redirection of __Mux__ to allow overrides for more advanced behaviour
without changing fundamental language characteristics or semantics in nmigen
https://bugs.libre-soc.org/show_bug.cgi?id=458

hdl.ast: simplify Mux implementation.

hdl.ast: add tests for casting bare integers in {Cat,Repl}.

hdl.ast: remove quadratic time complexity in Statement.cast().

Using `sum(lst, [])` to flatten a list of lists has quadratic time
complexity. Use `chain.from_iterable()` instead. While not strictly
necessary to improve performance, convert to `map()`.

A test case writing out verilog for a 512k entry FIFO is 120x faster
with this applied.

vendor.xilinx: avoid using `/` for hierarchy in ISE constraint files.

Unify Xilinx platforms into a single class, support more devices

This merges existing code, and also adds support for:

- Virtex, Virtex E (also known as Spartan 2, Spartan 2E)
- Virtex 2, Virtex 2 Pro
- Spartan 3, Spartan 3E (in addition to existing Spartan 3A, Spartan 3A
  DSP support)
- Virtex 4
- Virtex 5
- Virtex 6
- ISE synthesis for Series 7

Fixes #552.

_toolchain: Properly set compiler/linker executables on Gentoo

The `test_toolchain_cxx.py` tests on Gentoo definitely use compiler and
linker set with `_so_cxx`-suffixed executables. Tests use a proper
executable instead of `c++` after this change.

Signed-off-by: Adam Jeliński <ajelinski@antmicro.com>

vendor.xilinx_{7series,ultrascale}: hierachical -> hierarchical

Signed-off-by: Robin Ole Heinemann <robin.ole.heinemann@gmail.com>

_toolchain: substitute '+' with 'X' in tool_env_var().

README: update IRC channel.

rpc: fix parsing of negative signed parameters

test.test_hdl_ast.OperatorTestCase: remove duplicate test_bool

tests: rename tests with duplicate names

tests.test_hdl_cd.ClockDomainTestCase.test_name: actually test domain with cd_ prefix

*: remove unused variables

*: remove unused imports

tests.hdl.dsl: add tests for mis-nested Switch/Case and FSM/State statements

hdl.dsl: raise SyntaxError for mis-nested If/Elif/Else statements

vendor.lattice_{ecp5,machxo_2_3l}: remove -forceAll from Diamond scripts.

Fixes #604.

CI: fix sri-csl/formal-methods PPA series.

GHA's Ubuntu has been upgraded to Focal.

hdl.ast: handle int subclasses as slice start/stop values.

Fixes #601.

compat.genlib.roundrobin: fix missing imports

vendor.xilinx_7series: fix tool names for symbiflow.

Prefix "tools" with symbiflow_ as is done for the QuickLogic Symbiflow
toolchain. Installing symbiflow gives me the tools with the preifx, so I
guess this is the correct way to move forward.

vendor.lattice_ecp5: correctly generate OE signaling when xdr=0

This fixes a logic bug introduced in
6ce2b21e196a0f93b82748ed046098331d20b3bf.

vendor.lattice_ecp5: replicate OE signal for each output bit.

nextpnr can only pack OE FFs into IOLOGIC when there's one OFS1P3DX per
output, rather than one shared instance.

README: add ChipEleven as a sponsor.

docs: Update up_counter to avoid deprecation warning

nmigen/docs/_code/up_counter.py:44: DeprecationWarning: instead of nmigen.back.pysim.*, use nmigen.sim.*
  from nmigen.back.pysim import Simulator

vendor.lattice_ecp5: remove outdated comment in ECP5 platform.

Starting with nextpnr c6401413a, nextpnr does pack *FS1P3DX
into IOLOGIC cells.

lib.fifo.AsyncFIFOBuffered: fix output register accounting

lib.fifo.AsyncFIFOBuffered: fix FFSynchronizer latency

lib.fifo: use proper clock domains in AsyncFIFO tests

lib.fifo.AsyncFIFOBuffered: use FFSynchronizer instead of AsyncFFsynchronizer

AsyncFFsynchronizer only synchronizes one edge

Revert "vendor.xilinx_7series: byte swap generated bitstream"

This reverts commit 14a5c42a8bd425a4882ba566b26e11bd6d1e1721.

hdl.ast: formatting. NFC.

hdl.ast: normalize case values to two's complement, not signed binary.

This was an especially insidious bug because the minus character is
valid in case values but has a completely different meaning (wildcard
rather than sign).

Fixes #559.

back.rtlil: give private items an appropriate name. NFCI.

build.plat: make `verbose` work like all other overrides.

Fixes #497.

vendor.intel: implement `add_settings` (QSF) and `add_constraints` (SDC) overrides.

vendor.xilinx_spartan_3_6: fix typo.

This was introduced in commit 2f8669ca.

Fixes #549.

hdl.ast: remove dead code. NFC.

See #548.

nmigen.hdl.rec: restore Record.shape().

This method was lost in commit abbebf8e.

sim._pyrtl: mask Mux selection operand.

Otherwise it behaves funny when it's eg. the result of operator ~.

vendor.quicklogic: enable SoC clock configuration

Signed-off-by: Jan Kowalewski <jkowalewski@antmicro.com>

vendor.quicklogic: write OpenOCD scripts as part of build process.

The OpenOCD scripts for EOS-S3 are roughly equivalent to SVF files
for a more traditional FPGA, which we also produce, for some common
"default" configuration, as a part of the build process.

build.plat: TemplatedPlatform.iter_extra_files→Platform.iter_files.

This function was added in commit 20553b14 in the wrong place, with
the wrong name, and without tests. Fix all that.

hdl.rec: proxy operators correctly.

Commit abbebf8e used __getattr__ to proxy Value methods called on
Record. However, that did not proxy operators like __add__ because
Python looks up the special operator methods directly on the class
and does not run __getattr__ if they are missing.

Instead of using __getattr__, explicitly enumerate and wrap every
Value method that should be proxied. This also ensures backwards
compatibility if more methods are added to Value later.

Fixes #533.

vendor.intel: add support for Cyclone V internal oscillator

When using the default clock "cyclonev_oscillator" on Cyclone V devices,
the internal oscillator will be used.

hdl.ast: deprecate UserValue in favor of ValueCastable.

Closes #527.

sim.pysim: avoid redundant VCD updates.

This commit properly addresses a bug introduced in 2efeb05c and then
temporarily fixed in 58f1d4bc.

Fixes #429.

examples: clean up oudated code.

Fix commit 8313d6e7.

cli: update deprecated import.

CI: add CPython 3.9 to test matrix.

CI: run testsuite with -Werror.

vendor.lattice_{ice40,ecp5}: clean up $verilog_initial_trigger wires.

These only matter in simulation and after conversion to Verilog.
During synthesis they cause Yosys to produce warnings:

  Warning: Wire $verilog_initial_trigger has an unprocessed 'init' attribute.

hdl.rec: migrate Record from UserValue to ValueCastable.

Closes #528.

hdl.ast: implement ValueCastable.

Closes RFC issue #355.

vendor.quicklogic: part→package

vendor.xilinx_7series: byte swap generated bitstream

The Zynq driver in the FPGA Manager framework on Linux expects bitstreams that
are byte swapped with respect to what the Vivado command
`write_bitstream -bin_file` produces. Thus, use the `write_cfgmem` command with
appropriate options to generate the bitstream (.bin file).

Fixes #519.

lib.fifo: fix {r,w}_level in AsyncFIFOBuffered

lib.fifo: fix level on fifo full

vendor.lattice_ice40: zero-pad CLKHF_DIV in SB_HFOSC instance.

Fixes #520.

vendor.quicklogic: utilize internal SoC clock in EOS-S3

Signed-off-by: Jan Kowalewski <jkowalewski@antmicro.com>

vendor.quicklogic: fix toolchain nomenclature

Signed-off-by: Jan Kowalewski <jkowalewski@antmicro.com>

lib.fifo.AsyncFFSynchronizer: check input and output signal width

setup: link to latest docs if VCS information is not available.

build.dsl: clean up inversion logic.

  * Add invert= argument to DiffPairs() constructor, like in Pins().
  * Make PinsN() and DiffPairsN() pass invert= to the corresponding
    construtor instead of mutating.

back.{verilog,rtlil}: adjust $verilog_initial_trigger insertion.

To track upstream changes.

CI: disable codecov project status.

Every PR should be covered by tests, and codecov patch statuses are
extremely useful. However, codecov project statuses mostly create
noise because project-wide coverage in nMigen is currently primarily
informational.

lib.fifo.AsyncFIFO: fix incorrect latency of r_level.

Co-authored-by: Andrew Wygle <awygle@gmail.com>

tests: make spec directory name unique per test method.

sim._pyrtl: sign extend RHS of assignment.

Fixes #502.

hdl.dsl: error on Elif immediately nested in an If.

I.e. on this code, which is currently not only wrongly accepted but
also results in completely unexpected RTL:

    with m.If(...):
        with m.Elif(...):
            ...

Fixes #500.

vendor.quicklogic: fix syntax

Signed-off-by: Jan Kowalewski <jkowalewski@antmicro.com>

setup.py: Exclude "tests" package

67b957d moved the tests from nmigen/test/ to tests/, and removed the
exclude= parameter from find_packages() in setup.py. However, even if
the new location is not inside the module tree, it is still found by
find_packages(), resulting in a stray "tests" module on the system.

hdl.ir: Update error message for Instance arguments

48d4ee4 added the option to specify attributes using Instance arguments,
but the error message wasn't updated accordingly.

README: Quicklogic EOS S3 is now supported.

CI: fix code coverage collection.

This has been broken since commit d71e19e2 (2020-07-22).

vendor.quicklogic: new platform.

Signed-off-by: Kamil Rakoczy <krakoczy@antmicro.com>
Signed-off-by: Jan Kowalewski <jkowalewski@antmicro.com>
Co-authored-by: Kamil Rakoczy <krakoczy@antmicro.com>

tests: keep comments up to date. NFC.

build.plat: avoid type confusion in _check_feature.

Before this commit, `_check_feature(valid_xdrs=0)` would mean that
XDR buffers are not supported. Only `_check_feature(valid_xdrs=())`
was intended to be an indicator of that.

hdl.mem: document ReadPort and WritePort.

Fixes #496.

vendor.lattice_{ecp5,machxo_2_3l}: explain how to set up NMIGEN_ENV_Diamond on Windows.

setup: synchronize builtin-yosys dependency.

back.verilog: use `proc -nomux` if it is available.

Yosys offers no stability guarantees for individual `proc_*` passes,
though so far it worked out fine. This commit changes the Verilog
backend to use `proc -nomux` instead, which is guaranteed to have
backwards-compatible behavior.

Fixes #479.

sim: split into base, core, and engines.

Before this commit, each simulation engine (which is only pysim at
the moment, but also cxxsim soon) was a subclass of SimulatorCore,
and every simulation engine module would essentially duplicate
the complete structure of a simulator, with code partially shared.

This was a really bad idea: it was inconvenient to use, with
downstream code having to branch between e.g. PySettle and CxxSettle;
it had no well-defined external interface; it had multiple virtually
identical entry points; and it had no separation between simulation
algorithms and glue code.

This commit completely rearranges simulation code.
  1. sim._base defines internal simulation interfaces. The clarity of
     these internal interfaces is important because simulation
     engines mix and match components to provide a consistent API
     regardless of the chosen engine.
  2. sim.core defines the external simulation interface: the commands
     and the simulator facade. The facade provides a single entry
     point and, when possible, validates or lowers user input.
     It also imports built-in simulation engines by their symbolic
     name, avoiding eager imports of pyvcd or ctypes.
  3. sim.xxxsim (currently, only sim.pysim) defines the simulator
     implementation: time and state management, process scheduling,
     and waveform dumping.

The new simulator structure has none of the downsides of the old one.

See #324.

sim.pysim: in write_vcd(), close files if an exception is raised.

This also avoids leaving the waveform writer list in an inconsistent
state after an exception.

sim._pyclock: new type of process.

The overhead of coroutine processes is fairly high. A clock driver
implemented through a coroutine process is mostly overhead. This was
partially addressed in commit 2398b792 by microoptimizing yielding.

This commit eliminates the coroutine process overhead completely by
introducing dedicated clock processes. It also simplifies the logic
to a simple toggle.

This change improves runtime by about 12% on Minerva SRAM SoC.

sim._pycoro: make src_loc() more robust.

  * Guard for finished coroutines.
  * Guard for coroutines yielding from iterators and not generators.

_toolchain.cxx: work around PyPy missing LDCXXSHARED sysconfig variable.

_toolchain.cxx: new toolchain.

hdl.ast: clarify exception message for out of bounds indexing.

Fixes #488.

nmigen.test.utils: restore FHDLTestCase to gracefully deprecate it.

Fixes #484.

tests: move out of the main package.

Compared to tests in the repository root, tests in the package have
many downsides:
  * Unless explicitly excluded in find_packages(), tests and their
    support code effectively become a part of public API.
    This, unfortunately, happened with FHDLTestCase, which was never
    intended for downstream use.
  * Even if explicitly excluded from the setuptools package, using
    an editable install, or setting PYTHONPATH still allows accessing
    the tests.
  * Having a sub-package that is present in the source tree but not
    exported (or, worse, exported only sometimes) is confusing.
  * The name `nmigen.test` cannot be used for anything else, such as
    testing utilities that *are* intended for downstream use.