If delta cycles are expanded (i.e. if the `fs_per_delta` argument to
`Simulator.write_vcd` is not zero), then create a string typed variable
for each testbench in the simulation, which reflects the current
command being executed by that testbench. To make all commands visible,
insert a (visual) delta cycle after each executed command, and ensure
that there is a change/crossing point in the waveform display each time
a command is executed, even if several identical ones in a row.
If delta cycles are not expanded, the behavior is unchanged.
This commit adds an option `fs_per_delta=` to `Simulator.write_vcd()`.
Specifying a positive integer value for it causes the simulator to
offset value change times by that many femtoseconds for each delta
cycle after the last timeline advancement.
This option is only suitable for debugging. If the timeline is advanced
by less than the combined duration of expanded delta cycles, an error
similar to the following will be raised:
vcd.writer.VCDPhaseError: Out of order timestamp: 62490
Typically `fs_per_delta=1` is best, since it allows thousands of delta
cycles to be expanded without risking a VCD phase error, but bigger
values can be used for an exaggerated visual effect.
Also, the VCD writer is changed to use 1 fs as the timebase instead of
1 ps. This change is largely invisible to designers, resulting only in
slightly larger VCD files due to longer timestamps.
Since the `fs_per_delta=` option is per VCD writer, it is possible to
simultaneously dump two VCDs, one with and one without delta cycle
expansion:
with sim.write_vcd("sim.vcd"), sim.write_vcd("sim.d.vcd", fs_per_delta=1):
sim.run()
Before this commit, testbenches (generators added with `add_testbench`)
were not only preemptible after any `yield`, but were *guaranteed* to
be preempted by another testbench after *every* yield. This is evil:
if you have any race condition between testbenches, which is common,
this scheduling strategy will maximize the resulting nondeterminism by
interleaving your testbench with every other one as much as possible.
This behavior is an outcome of the way `add_testbench` is implemented,
which is by yielding `Settle()` after every command.
One can observe that:
- `yield value_like` should never preempt;
- `yield assignable.eq()` in `add_process()` should not preempt, since
it only sets a `next` signal state, or appends to `write_queue` of
a memory state, and never wakes up processes;
- `yield assignable.eq()` in `add_testbench()` should only preempt if
changing `assignable` wakes up an RTL process. (It could potentially
also preempt if that wakes up another testbench, but this has no
benefit and requires `sim.set()` from RFC 36 to be awaitable, which
is not desirable.)
After this commit, `PySimEngine._step()` is implemented with two nested
loops instead of one. The outer loop iterates through every testbench
and runs it until an explicit wait point (`Settle()`, `Delay()`, or
`Tick()`), terminating when no testbenches are runnable. The inner loop
is the usual eval/commit loop, running whenever a testbench changes
design state.
`PySimEngine._processes` is a `set`, which doesn't have a deterministic
iteration order. This does not matter for processes, where determinism
is guaranteed by the eval/commit loop, but causes racy testbenches to
pass or fail nondeterministically (in practice depending on the memory
layout of the Python process). While it is best to not have races in
the testbenches, this commit makes `PySimEngine._testbenches` a `list`,
making the outcome of a race deterministic, and enabling a hacky work-
around to make them work: reordering calls to `add_testbench()`.
A potential future improvement is a simulation mode that, instead,
randomizes the scheduling of testbenches, exposing race conditions
early.
The abbreviated form was initially added to match `lib.fifo`, but it
looks very out of place on `lib.memory`, and we may be moving away from
such heavy use of abbreviations anyway.
While technically a breaking change, these attributes have very narrow
usefulness and so this change qualifies as "minor".
Display `shape` and `depth` also. `depth` is redundant although useful
for ease of reading (there are always `depth` elements shown), but
`shape` was just lost.
This attribute is fully redundant with `.__len__()`, and is out of place
on a `list`-like container like `Memory.Init`.
The `.shape` attribute, however, provides a unique function.
The premise of `tcl_escape` is incorrect: it is not possible, by design,
to escape a single backslash inside of a Tcl {}-quoted string:
$ tclsh
% puts {\\}
\\
`tcl_quote` should be used instead since it can escape arbitrary strings
(and uses the right algorithm already).
This isn't expected to result in a significant increase in memory use,
so for now it's enabled by default. Elaboration chains where it is not
desired to preserve origins can delete the `origins` attribute from
the fragment and nothing will be stored.
The interface `Fragment.origins` remains private, as is the rest of
the `Fragment` interface (including itself), but it enables certain
codebases that currently use a much more invasive technique to rely on
reading a single private field.
Use _EnumDict._member_names to determine which members to consider.
This way we don't need to redo sunder/dunder checks, and `nonmember`s
(introduced in py3.11) are correctly excluded.
This is a defacto public API, given it remains usable from py3.8
until py3.12 inclusive. (_member_names changes from a list to a
keys-only dict for performance reasons in py3.11, but they iterate the
same.) In current Python main (i.e. what will most likely be 3.13), a
"member_names" property is added which returns those keys.
I originally picked :pc: as it is short for "python code", but it is
obscure and :py: is not taken, so a much more obvious role can be used
instead. Also, we all typo :pc: as :py: all the time anyway.
In this environment it's not feasible, or at least it's not documented
how, to distribute JavaScript code by packaging it as a wheel; only
Wasm code (as shared objects) can be distributed this way. The current
`amaranth-yosys` strategy would not work even though wheels can be
installed on Pyodide, and Yosys will need to be explicitly provided by
the environment instead.
The implementation is sufficiently generic that non-Pyodide hosts could
potentially make use of it, though it doesn't seem like any exist at
the moment.
In some environments (e.g. Pyodide) it may be advantageous to not load
this library, and with the import at file level, it makes the entire
simulator unusable, not just `PySimEngine.write_vcd`.
This might also help people whose Python environments are unusually
broken, whom we've historically accommodated.
The new intermediate representation will enable global analyses
on Amaranth code without lowering it to another representation
such as RTLIL.
This commit also changes the RTLIL builder to use the new IR.
Co-authored-by: Wanda <wanda@phinode.net>
The source location is set to the place where `In`/`Out` was created.
The source location of the instantiation is tracked but overwritten;
we will need to change the internal structure storing those to be able
to include both.
Fixes#1085.
This closes#721 by implementing get_async_ff_sync() using FDPE
primitives to obtain exactly the netlist that we want. This consits
of a chain of N FPDEs (by default N = 2) with all their PRE pins
connected to the reset for a positive edge reset or to the ~reset
for a negative edge reset. The D pin of the first FDPE in the chain
is connected to GND.
To make timing analysis work correctly, two new attributes are
introduced: amaranth.vivado.false_path_pre and
amaranth.vivado.max_delay_pre. These work similarly to
amaranth.vivado.false_path and amaranth.vivado.max_delay, but affect
only the PRE pin, which is what is needed for this synchronizer.
The TCL has been modified to generate constraints using these
attributes, and there are comments explaining how to use the attributes
directly in an XDC file in case the user wants to manage their XDC
file manually instead of using the TCL.
This subclassing is unnecessary and makes downstream code more complex.
In the new IR, they are unified into cells with the same name anyway.
Even before that, this change simplifies things.
This commit also contains a related semantic change: it adds `Shape`
and `ShapeCastable` to the `__all__` list in `amaranth.hdl`. This is
consistent with the policy that is laid out in the new documentation,
which permits such additions without notice.
Co-authored-by: mcclure <mcclure@users.noreply.github.com>
This change completes commit 9dc0617e and makes all the tests pass.
It corresponds with the ongoing langauge reference documentation effort.
Fixes#781.
Reexports of `amaranth.utils` functions are removed from
`amaranth._utils` to avoid a circular import issue (for `deprecated`).
Since this is a private module, this should not be a problem.
This ensures things like `Const(1.5)` raise an error.
`int(operator.index())` is used since `operator.index(True)` on Python
3.9 and earlier returns `True` instead of `1`.
The build scripts generated by Amaranth are designed to be invoked by
directly running them with any shell (some of them will re-invoke
themselves with `bash` specifically, when it's a toolchain requirement),
and they're not currently marked executable, so there's no shebang.
Add a shebang line to improve compatibility with cases where they are
treated as executables in their own right.
