Update README.

docs/install: use pip/pip3 more consistently.

docs: clarify naming.

Revert "Add PEP 518 `pyproject.toml`."

This reverts commit 7fca037f9c14974f499195171bb84c38ebddc1e1.

This broke editable installs and has to be reverted due to a number
of pip issues:
  * pypa/pip#6375
  * pypa/pip#6434
  * pypa/pip#6438

We can put this back once PEP 517/518 support editable installs.
Until then the legacy behavior will suffice, and we should just teach
people to install the dependencies in virtualenvs or something...

docs: add a crude approximation of intersphinx toctrees.

This is a pretty awful hack. We could do this properly after one of
the following issues is fixed:
  * sphinx-doc/sphinx#701
  * sphinx-doc/sphinx#1836

Gracefully handle missing dependencies.

Some people's workflows involve not using `pip`. This is not
a recommended way to use nMigen, but is prevalent enough for good
enough reason that we try to keep them working anyway.

docs/install: fix dead link.

docs/install: quote special chars to avoid issues with extended glob.

docs/install: explain how to install non-editable snapshot from git.

Add PEP 518 `pyproject.toml`.

This is necessary to be able to install nMigen into a virtualenv that
does not have `wheel` installed in certain cases.

See #349.

docs/install: use `pip install --user` on *nix.

docs/install: reduce repetition.

README: update to refer to documentation where applicable.

docs: reword slightly.

docs: explain how to install GTKWave on Windows.

CI: build docs on all pushes, update only on 

docs: rewrite install instructions to be easier to understand.

setup: link to proper location for docs.

docs: fix syntax.

docs: fix CI workflow.

docs: explain that `pip3 install -e` should be run after pulling.

Add (heavily work in progress) documentation.

To render correctly, the docs require:
 * pygments/pygments#1441

Don't use pkg_resources.

This package is deprecated and introduces a massive amount of startup
latency. On my machine with 264 installed Python packages, it reduces
the time required to `import nmigen` from ~100ms to ~200ms.

lib.cdc: update PulseSynchronizer to follow conventions.

Fixes #370.

back.pysim: simplify.

Remove _EvalContext, which was a level of indirection serving almost
no purpose. (The only case where it would be useful is repeatedly
resetting a simulation that, each time it is reset, would create new
signals to communicate with between coroutine processes. In that case
the signal states would not be persisted in _SimulatorState, but
would be removed with the _EvalContext that is recreated each time
the simulation is reset. But this could be solved with a weak map
instead.)

This regresses simulator startup time by 10-15% for unknown reasons
but is necessary to align pysim and future cxxsim.

_yosys: handle unparseable versions

Do not use yosys binaries with unparseable version numbers. This ensures
that nmigen always knows what version of yosys it is generating RTLIL
for.

The effect of this change is that if the version number of the system
yosys is unparsable, nmigen will attempt to fallback to the builtin
Yosys.

Fixes #409.

vendor.lattice_machxo2: add back as a compatibility shim.

vendor.lattice_machxo*: add MachXO3L support.

back.verilog: refactor Yosys script generation. NFCI.

In commit 5f30bcbb, back.cxxsim gained a nicer way to generate
a script; this commit brings it to back.verilog too.

back.cxxrtl: allow injecting black boxes.

_yosys: add a way to retrieve Yosys data directory.

This is important for CXXRTL, since that's where its include files
are located.

_yosys: fix typo in error message.

test: fix example test after commit a7b8ced9.

back.cxxrtl: new backend.

_yosys: translate Yosys warnings to Python warnings.

This isn't used yet (the only Yosys warning we can get is useless),
but will be handy for CXXRTL.

nmigen.cli: fix file type autodetection code.

back.verilog: remove unused imports. NFC.

hdl.xfrm: preserve allow_reset_less when transforming ResetSignal.

Fixes #400.

hdl.rec: preserve shapes when constructing a layout.

Preserve the original user-provided shape, while still checking
its validity. This allows Enum decoders to work when specifying
record fields with Enums.

Fixes #393.

setup: exclude tests.

The inclusion of tests in the package was completely unintentional
and a result of my lack of knowledge of setuptools. If you are using
nmigen.test.utils, please copy the parts you need to your own code
because the nmigen.test code can and will change without notice.

vendor.lattice_ice40: reword confusing comment. NFC.

hdl.ast: fix typo

back.verilog: fall back to nmigen_yosys package.

The nmigen-yosys PyPI package provides a custom, minimal build of
Yosys that uses (at the moment) wasmtime-py to deliver a single
WASM binary that can run on many platforms, and eliminates the need
to build Yosys from source.

Not only does this lower barrier to entry for new nMigen developers,
but also decouples nMigen from Yosys' yearly release cycle, which
lets us use new features and drop workarounds for Yosys bugs earlier.

The source for the nmigen-yosys package is provided at:
  https://github.com/nmigen/nmigen-yosys
The package is built from upstream source and released automatically
with no manual steps.

Fixes #371.

Update .gitignore.

vendor.intel: don't use `write_verilog -decimal`.

See commit 702e41ba for details.

vendor.intel: double-quote Tcl values rather than brace-quoting.

For unknown reasons, Quartus treats {foo} and "foo" in completely
different ways, which is not true for normal Tcl code; specifically,
it preserves the braces if they are used. Because of this, since
commit 6cee2804, the vendor.intel package was completely broken.

vendor.xilinx_{7series,ultrascale}: don't use `write_verilog -decimal`.

In commit 892cff05, `-decimal` was used when writing Verilog for
Vivado targets because it treats (* keep=32'd1 *) and (* keep=1 *)
differently in violation of Verilog LRM. However, it is possible
to avoid that workaround by using (* keep="TRUE" *). Do that,
and remove `-decimal` to avoid special-casing 32-bit constants.

Refs #373.

build.plat: skip clock constraints on unused signals.

It's not very nice to add more internal mutable state to Platform
related classes, but our whole approach for Platform is inherently
stateful, and other solutions (like changing every individual vendor
platform to check for unused signals) are even worse.

Fixes #374.

vendor.xilinx_{7series,ultrascale}: add (*keep*) on constrained clocks.

If the clock signal is not a top-level port and has aliases, it can
be optimized out, and then the constraint will no longer apply.
To prevent this, make sure the constrained signal is preferred over
any aliases by using the `keep` attribute.

Vivado does not parse attributes like (* keep = 32'd1 *) as valid
even though, AFAICT, they are equivalent to (* keep = 1 *) or simply
(* keep *) per IEEE 1364. To work around this, use the solution we
currently use for Quartus, which is `write_verilog -decimal`.

Fixes #373.

hdl.ast: add const-shift operations.

Also, clean up the rotate code a bit.

Fixes #378.

hdl.ast: clarify docs for Value.rotate_{left,right}.

"Rotate modulo 2**len(self)" is redundant because that's just how
rotates work.

hdl.dsl: check for unique domain name.

Fixes #385.

back.rtlil: handle signed and large Instance parameters correctly.

Fixes #388.

tracer: fix get_var_name() to work on toplevel attributes.

E.g. this now works:

    >>> class dummy: pass
    >>> self = dummy()
    >>> self.foo = Signal()
    >>> self.foo.name
    'foo'

vendor.lattice_machxo2: generate binary bitstreams.

plat, vendor: systematically escape net and file names in Tcl.

Before this commit, there was only occasional quoting of some names
used in any Tcl files. (I'm not sure what I was thinking.)

After this commit, any substs that may include Tcl special characters
are escaped. This does not include build names (which are explicitly
restricted to ASCII to avoid this problem), or attribute names (which
are chosen from a predefined set). Ideally we'd use a more principled
approach but Jinja2 does not support custom escaping mechanisms.

Note that Vivado restricts clock names to a more restrictive set that
forbids using Tcl special characters even when escaped.

Fixes #375.

back.rtlil: fix incorrect escaping of signed parameters.

Also, improve escaping code in general.

hdl.ast: use SignalSet, not ValueSet, for _[lr]hs_signals().

The implementation of these functions likely predates support for
{Clock,Reset}Signal() in SignalKey.

lib.cdc: add missing documentation for AsyncFFSynchronizer. NFC.

lib.fifo: add r_rst output for AsyncFIFO{,Buffered}.

Fixes #181.

hdl.ir: typecheck `convert(ports=)` more carefully.

The `ports` argument to the `convert` functions is a frequent hotspot of
beginner issues. Check to make sure it is either a list or a tuple, and
give an appropriately helpful error message if not.

Fixes #362.

README: link directly to Yosys build instructions.

back.verilog: add workaround for evaluation Verific behavior.

The evaluation version of Verific prints its license information to stdout,
and since it is against the EULA to change that in any way, this behavior
is not possible to fix in Yosys. Add a workaround in nMigen instead.

back.verilog: make Yosys version check compatible with Verific.

vendor: use nextpnr -12k for -12F devices; remove theoretical devices

nextpnr now supports -12k; which replaces the use of -25k and --idcode
together to build bitstreams compatible with -12F devices. Use this.

This also removes the LFEUM-12K and its 5G counterpart; as per Dave Shah
they're currently only theoretical FPGAs.

hdl.rec: make Record inherit from UserValue.

Closes #354.

back.rtlil: translate enum decoders to Yosys enum attributes.

Fixes #254.

buil.plat: enable strict undefined behavior in Jinja2.

By default, if an operation produces an undefined value (a Jinja2
concept that corresponds to Python's KeyError, AttributeError, etc)
then this value may be printed in a template, which is a nop. This
behavior can hide bugs.

This commit changes the Jinja2 behavior to raise an error instead of
producing an undefined value in all cases. (We produce undefined
values deliberately in a few places. Those are unaffected; it is OK
to use several kinds of undefined values in one Jinja2 environment.)

Fixes #337.

back.rtlil: don't emit connections to zero width ports.

Fixes #335.

back.rtlil: refuse to create extremely large wires.

Such wires are likely to trigger pathological behavior in Yosys and,
if applicable, other toolchains that consume Verilog converted from
RTLIL.

Fixes #341.

back.rtlil: fix expansion of Part() for partial dummy writes.

Before this commit, selecting a part that was fully out of bounds of
a value was correctly implemented as a write to a dummy wire, but
selecting a part that was only partially out of bounds resulted in
a crash.

Fixes #351.

back.rtlil: fix legalization of Part() with stride.

Also known as word_select().

Clarify a few comments. NFC.

hdl.ast: add Value.{rotate_left,rotate_right}.

Travis: require tests to pass on pypy3.

Fixes #147.

Travis: upgrade to bionic.

build.run: fix BuildProducts.extract to work with subdirectories.

Fixes #353.

hdl.rec: improve repr() for Layout.

Fixes #326.

hdl.ast: improve repr() for Shape.

The default __repr__() from typing.NamedTuple does not include
the module name, so the replacement (which uses the preferred syntax
for specifying these shapes) doesn't either.

build.plat: don't check for toolchain presence if do_build=False.

back.pysim: Clear pending updates after they are effected

back.pysim: Eliminate duplicate dict lookup in VCD update

back.pysim: Reuse clock simulation commands

hdl.mem: fix source location of ReadPort.en.

back.pysim: fix emission of undriven traces to VCD files.

This has been originally implemented in commit d3775eed (which fixed
`write_vcd(traces=)` to do something at all), but had a flaw where
undriven traces would not be correctly placed in hierarchy. This
used to produce incorrect results on pyvcd 0.1, but started causing
assertion failures on pyvcd 0.2.

Fixes #345.

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>