From a461870050a9e651cefb42b22cc5445681dab813 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Thu, 17 Apr 2025 16:23:36 +1200 Subject: [PATCH] Docs: More bugpoint bullets More info for creating GitHub issues and the different sections. Discuss additional details that can be included as comments on the issue. Also mention Gists for large files (preferable to downloading a .txt). Add a warning about external plugins/tools. Also add a note to `load_design.rst` about `Frontend`s and `-f` command line option. --- docs/source/using_yosys/bugpoint.rst | 102 ++++++++++++++++-- .../more_scripting/load_design.rst | 4 + 2 files changed, 100 insertions(+), 6 deletions(-) diff --git a/docs/source/using_yosys/bugpoint.rst b/docs/source/using_yosys/bugpoint.rst index 80694fd2d..2316510cf 100644 --- a/docs/source/using_yosys/bugpoint.rst +++ b/docs/source/using_yosys/bugpoint.rst @@ -498,10 +498,27 @@ Why context matters Creating an issue on GitHub --------------------------- -- "Reproduction Steps" is ideally a code-block (starting and ending with triple - backquotes) containing the minimized design (Verilog or RTLIL), followed by a - code-block containing the minimized yosys script OR a command line call to - yosys with code-formatting (starting and ending with single backquotes) +- use the `bug report template`_ + +.. _bug report template: https://github.com/YosysHQ/yosys/issues/new?template=bug_report.yml + +- short title briefly describing the issue, e.g. + + techmap of wide mux with undefined inputs raises error during synth_xilinx + + + tells us what's happening ("raises error") + + gives the command affected (`techmap`) + + an overview of the input design ("wide mux with undefined inputs") + + and some context where it was found ("during `synth_xilinx`") + + +Reproduction Steps +~~~~~~~~~~~~~~~~~~ + +- ideally a code-block (starting and ending with triple backquotes) containing + the minimized design (Verilog or RTLIL), followed by a code-block containing + the minimized yosys script OR a command line call to yosys with + code-formatting (starting and ending with single backquotes) .. code-block:: markdown @@ -535,5 +552,78 @@ Creating an issue on GitHub # minimum sequence of commands ``` -- any environment variables or command line options should also be mentioned in - the "Reproduction Steps" +- any environment variables or command line options should also be mentioned +- if the problem occurs for a range of values/designs, what is that range +- if you're using an external tool, such as ``valgrind``, to detect the issue, + what version of that tool are you using and what options are you giving it + +.. warning:: + + Please try to avoid the use of any external plugins/tools in the reproduction + steps if they are not directly related to the issue being raised. This + includes frontend plugins such as GHDL or slang; use `write_rtlil` on the + minimized design instead. This also includes tools which provide a wrapper + around Yosys such as OpenLane; you should instead minimize your input and + reproduction steps to just the Yosys part. + +"Expected Behaviour" +~~~~~~~~~~~~~~~~~~~~ + +- if you have a similar design/script that doesn't give the error, include it + here as a reference +- if the bug is that an error *should* be raised but isn't, are there any other + commands with similar error messages + + +"Actual Behaviour" +~~~~~~~~~~~~~~~~~~ + +- any error messages go here +- any details relevant to the crash that were found with ``--trace`` or + ``--debug`` flags +- if you identified the point of failure in the source code, you could mention + it here, or as a comment below + + + if possible, use a permalink to the source on GitHub + + you can browse the source repository for a certain commit with the failure + and open the source file, select the relevant lines (click on the line + number for the first relevant line, then while holding shift click on the + line number for the last relevant line), click on the `...` that appears and + select "Copy permalink" + + should look something like + ``https://github.com/YosysHQ/yosys/blob//path/to/file#L139-L147`` + + clicking on "Preview" should reveal a code block containing the lines of + source specified, with a link to the source file at the given commit + + +Additional details +~~~~~~~~~~~~~~~~~~ + +- once you have created the issue, any additional details can be added as a + comment on that issue +- could include any additional context as to what you were doing when you first + encountered the bug +- was this issue discovered through the use of a fuzzer +- if you've minimized the script, consider including the `bugpoint` script you + used, or the original script, e.g. + +.. code-block:: markdown + + Minimized with + ``` + read_verilog design.v + # original sequence of commands prior to error + bugpoint -script -grep "" + write_rtlil min.il + ``` + + OR + + Minimized from + `yosys -p ': original sequence of commands to produce error;' design.v` + +- if you're able to, it may also help to share the original un-minimized design + + + if the design is too big for a comment, consider turning it into a `Gist`_ + +.. _Gist: https://gist.github.com/ diff --git a/docs/source/using_yosys/more_scripting/load_design.rst b/docs/source/using_yosys/more_scripting/load_design.rst index 1c597bdfc..7e417eff9 100644 --- a/docs/source/using_yosys/more_scripting/load_design.rst +++ b/docs/source/using_yosys/more_scripting/load_design.rst @@ -68,6 +68,10 @@ Yosys frontends + executed as multiple successive calls to the frontend +- compatible with ``-f`` command line option, e.g. ``yosys -f verilog + design.txt`` will use the `read_verilog` frontend with the input file + ``design.txt`` + - `verific` and `read` commands are technically not 'Frontends', but their behaviour is kept in sync