Give formal index a proper title.
Use `Pass::formatted_help()` to assign the group, but still return `false` because the help text still comes from `Pass::help()`.
Tidy up some of the affected files' includes to make use of the shared `yosys.h` includes.
Keep techlibs folder hierarchy.
techlibs/* and passes/* groups are now nested under index_techlibs and index_passes respectively, with most (all?) of the passes/* pages getting proper headings, as well as backends/frontends/kernel. `index_passes_techmap` also references `index_techlibs`.
Split command reference toc in twain, one with maxdepth=2 and one with maxdepth=3, since passes and techlibs now have an extra level of nesting.
Move the `cmd_ref` link to the command reference, instead of top of the page.
Remove `index_internal` and `index_other` from the toc, and mark the pages as orphan. Internal commands get a note callout after the command reference toc (although this doesn't work for the pdf build), while other commands are linked in the warning for missing `source_location` (since that *should* be the only time when there are any commands in the "unknown" group).
Update autodoc extension versions, and mark the directives extension as not `parallel_read_safe` (it might be, but I'm not sure about how the xref lookups work if it is parallel so better to be safe).
Calling :cmd:title:`<cmd>` will generate a cross reference to `<cmd>`, but unlike :cmd:ref: which displays a literal block and puts the title (short_help) in the hovertext (the title field of an a-ref), :cmd:title: will display "<cmd> - <short_help>" as plain text.
Thus replacing the previous use case of referring to :doc:`cmd/<cmd>`.
Also refactor util py scripts to have more descriptive names.
Commands flagged as internal will display a warning, just like experimental commands.
Drop `passes/tests` group in favour of `internal` group, which is automatically assigned for any command without an assigned group which is flagged as internal.
Changes a bunch of :doc:`/cmd/*` to :cmd:ref:`*` with the intention of changing it later to something that replicates the previous effect of displaying the commands `short_help`.
Removes group parsing from command ref domain, instead relying on a 'groups' object in the cmds.json file.
`docs/source/cmd` is no longer ignored or cleaned.
Add `doc_string` field to `Pass` constructor
Add `docs/util/newcmdref.py` to contain command domain
Update `docs/util/cmdref.py` with `cmd:usage` and `cmd:optiongroup` for describing commands.
Functional, but WIP.
There are two elements involved:
1) Apply the relevant full_case and/or parallel_case attribute(s) to
the generated AST_CASE node(s), so that the existing AST frontend and
subsequent passes will generate RTLIL with appropriate behaviour.
(This is handled in the parser "if_attr" non-terminal.)
2) Rearrange the AST_CASE structure when necessary. For "priority if"
(i.e., full_case), this requires only ensuring that directly nested
"else if" branches also inherit the full_case attribute. For
"unique if" and "unique0 if" (i.e., parallel_case+full_case and
parallel_case alone), there are two steps:
a) Flatten the AST_CASE structure such that any direct "else if"
branches are mapped to additional AST_CONDs in the parent;
b) Reverse the "direction" of the test: the constant 1 (true)
is provided in the AST_CASE node, and the expression(s) in the
if statement(s) are given in each AST_COND. This is necessary
because the constant 1, being the common factor, must occupy the
shared AST_CASE position.
(This is handled in the parser "TOK_IF" expansion of behavioral_stmt.)
Observe that:
* The generated AST has not been changed for bare "if"s (those
without unique/priority). This should minimise the risk of
unexpected regressions.
* It is possible that the flattening described in 2) a) above might
affect the behaviour of expressions with side effects in "unique if"
statements (consider "unique if( a ) ...; else if( b++ ) ...": if
a is true, is b incremented?). While it might be possible to provide
precise semantics here, IEEE 1800-2012 12.4.2 seems to be deliberately
vague ("In unique-if and unique0-if, the conditions may be evaluated
and compared in any order[...] The presence of side effects in
conditions may cause nondeterministic results.") and so it seems
doubtful that there is benefit in Yosys providing stronger promises
on the interpretation of questionable code.
Add support to the "read_verilog -sv" parser to validate the
"unique", "unique0", and "priority" keywords in contexts where
they're legal according to 1800-2012 12.4.2.
This affects only the grammar accepted; the behaviour of conditionals
is not changed. (But accepting this syntax will provide scope for
possible optimisations as future work.)
Three test cases ("unique_if", "unique_if_else", and
"unique_if_else_begin") verify that the keywords are accepted where
legal and rejected where illegal, as described in the final paragraph
of 12.4.2.
Drop svg badges. Even though they were only appearing in the html version, the latexpdf target was still trying to download them, leading to warnings-as-errors in offline builds.
I was thinking about compiling the dummy example and including a simple example usage, but it turns out functional.h isn't (currently) available for extensions.
Acknowledge the minimal functional backend, highlighting what's new/different for our SExpr targets.
Add and use the reference `minimal backend`.
Use `note` directives to point out missing code sections (highlighting that the included diffs are not complete).
Racket *is* still strongly-typed, it's just dynamic instead of static. Adjust phrasing to reflect that.
Adjust some of the literal includes, adding a new section from the `Functional::AbstractVisitor`, splitting the `Module::write_eval()` in twain and adding a `smtlib.cc` literal include for the node iteration, as well as for the `FunctionalSmtBackend` to compare against the minimal backend.
Move `Backend` description up to minimal functional backend section.
Add `dummy.cc`, loosely based on `backends/functional/test_generic.cc` but as an actualy backend and without the memory testing.
Skeleton section for minimal functional backend, describing the aforementioned `dummy.cc`.
As the intro paragraph (now) says:
> This section will introduce the SMT-LIB functional backend and what changes are needed...
The example is intended to be read without prior knowledge of the SMT-LIB backend, but the previous version glossed over a lot and instead focused on *just* what was changed.
This version should now be easier to follow without prior knowledge, while still being able to learn enough about the `Smt` version to adapt it to a different s-expression target that isn't Rosette.
Also adds a few `literalinclude`s of smtlib.cc, which is now copied to `docs/source/generated` along with producing the rosette diff on the fly (which now also has up to 20 lines of context, enabling the full `Module::write()` diff to be literal included).
Drop the parts that are being dropped.
Move the things that are being moved.
Also move the verilog stuff out of README and into the docs.
GettingStarted is less cut and dry, so hold off on that one.
This is mainly intended for (latex)pdf builds which do not use the furo-ys html theme, where the yosys script syntax highlighting can safely fallback to plaintext. This effectively makes `furo-ys` an optional dependency to simplify distro-package maintainability.
See also #4725.
Krystine Sherwin
Martin Povišer
Miodrag Milanovic
Gary Wong
Emily Schmidt
N. Engelhardt
Daniel Gröber
Scott Ashcroft
Emil J
George Rennie