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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Such wires are likely to trigger pathological behavior in Yosys and,
if applicable, other toolchains that consume Verilog converted from
RTLIL.
Fixes#341.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
`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.
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.
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.
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.
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.
$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.
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.
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.
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.
Now environment variable overrides no longer infect the build scripts.
_toolchain.overrides is dropped as probably misguided in the first place.
Fixes#251.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Before this commit, it was possible to set and get clock constraints
placed on Pin objects. This was not a very good implementation, since
it relied on matching the identity of the provided Pin object to
a previously requested one. The only reason it worked like that is
deficiencies in nextpnr.
Since then, nextpnr has been fixed to allow setting constraints on
arbitrary nets. Correspondingly, backends that are using Synplify
were changed to use [get_nets] instead of [get_ports] in SDC files.
However, in some situations, Synplify does not allow specifying
ports in [get_nets]. (In fact, nextpnr had a similar problem, but
it has also been fixed.)
The simplest way to address this is to refer to the interior net
(after the input buffer), which always works. The only downside
of this is that requesting a clock as a raw pin using
platform.request("clk", dir="-")
and directly applying a constraint to it could fail in some cases.
This is not a significant issue.
