From cf6e96ba5993d3137bf4e1520d677061187b2428 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 11 Mar 2025 17:11:26 +1300 Subject: [PATCH] Docs: Initial outline of minimizing designs How to guide for using bugpoint, minimizing yosys scripts, and minimizing verilog code. AKA how to MVCE. --- docs/source/using_yosys/bugpoint.rst | 210 +++++++++++++++++++++++++++ docs/source/using_yosys/index.rst | 1 + 2 files changed, 211 insertions(+) create mode 100644 docs/source/using_yosys/bugpoint.rst diff --git a/docs/source/using_yosys/bugpoint.rst b/docs/source/using_yosys/bugpoint.rst new file mode 100644 index 000000000..8c685c35c --- /dev/null +++ b/docs/source/using_yosys/bugpoint.rst @@ -0,0 +1,210 @@ +Minimizing failing (or bugged) designs +====================================== + +- how to guide +- assumes knowledge and familiarity with Yosys +- something is wrong with your design OR something is wrong with Yosys + + + how to work out which + +- *read* the error message +- is it a Yosys error? (starts with ERROR:) + + + does it give you a line number from your design + +- is it a runtime error, e.g. SEGFAULT +- are you using the latest release of Yosys + + + has your problem already been fixed + +- is your input design valid? + + + if you're using Verilog, try load it with `iverilog`_ or `verilator`_ + +.. _iverilog: https://steveicarus.github.io/iverilog/ +.. _verilator: https://www.veripool.org/verilator/ + +- make sure to back up your code (design source and yosys script(s)) before + making any modifications + + + even if the code itself isn't important, this can help avoid "losing" the + error while trying to debug it + + +.. _minimize your RTLIL: + +Minimizing RTLIL designs with bugpoint +-------------------------------------- + +- `bugpoint`, only usable on platforms where Yosys can spawn executables + + + unavailable on emscripten and wasm + + can test by running e.g. ``yosys -qqp '!echo test'`` + + * the ``-qq`` prevents Yosys from outputting non-error messages to the + console, so this will either display the text ``test``, or an error + message about ``Shell`` being unavailable + * be careful about using ``!`` in bash as it will perform a history + substitution if not escaped with single quotes (double quotes will not + escape it) + * ``!`` does not need to be escaped in *Yosys* scripts or when called within + the interactive Yosys shell, *only* when called on the command line with + ``-p`` + +- single command (``yosys -p "" design.il``) +- *or* multiple commands in a separate script file + + + script shouldn't load the design + + ``yosys -s design.il`` + + `minimize your script`_ to reduce the time needed by `bugpoint` + +- doesn't require design to be in RTLIL format + + + can e.g. ``read_verilog ; prep -top ;`` before `bugpoint` + + this method may be more useful if you are trying to find a bug in your + design rather than Yosys + + but, `bugpoint` itself calls the command/script with an RTLIL dump, so if it + isn't reproducible from RTLIL then `bugpoint` won't work + +- follow `bugpoint` instructions + + + output design after `bugpoint` with `write_rtlil` + + use ``-grep ""`` to only accept a minimized design that crashes + with the ```` in the log file + + ``-modules``, ``-ports``, ``-cells``, and ``-processes`` will enable those + parts of the design to be removed + + * use the ``bugpoint_keep`` attribute on objects you don't want to be + removed, usually because you already know they are related to the failure + * ``(* bugpoint_keep *)`` in Verilog, ``attribute \bugpoint_keep 1`` in + RTLIL, or ``setattr -set bugpoint_keep 1 [selection]`` from script + + + ``-runner ""`` can allow running ``yosys`` wrapped by another + command + + can also use `setenv` before `bugpoint` to set environment variables for + the spawned processes (e.g. ``setenv UBSAN_OPTIONS halt_on_error=1``) + +.. note:: + + Using `setenv` in this way **does not affect the current process**. Only + child processes will respect the assigned ``halt_on_error``. + + +.. _minimize your script: + +Minimizing scripts +------------------ + +- reminder to back up original code before modifying it +- if you're using command line, convert it to a script +- if you're using one of the :doc:`/using_yosys/synthesis/synth`, replace it + with its contents +- remove everything *after* the error occurs +- can use `log` command to print messages to help locate the failure point +- `echo` can also help (``echo on``) +- try ``write_rtlil ; design -reset; read_rtlil ;`` before + the failure point + + + ideally you now have a single command that is producing an error and can + `minimize your RTLIL`_ with the ```` output + + if not, try to move the write/reset/read earlier in the script until you can + reproduce the error + + if you have no idea where exactly you should put the reset, the best way is + to use a "binary search" type approach, reducing the possible options by + half after each attempt + + * for example, your script has 16 commands in it before failing on the 17th + * if resetting immediately before the 17th doesn't reproduce the error, try + between the 8th and 9th (8 is half of the total 16) + * if that produces the error then you can remove everything before the + `read_rtlil` and try reset again in the middle of what's left, making sure + to use a different name for the output file so that you don't overwrite + what you've already got + * if the error isn't produced then you need to go earlier still, so in this + case you would do between the 4th and 5th (4 is half of the previous 8) + * repeat this until you can't reduce the remaining commands any further + +.. TODO:: is it possible to dump scratchpad? + + is there anything else in the yosys/design state that doesn't get included in + `write_rtlil`? + +- you can also try to remove or comment out commands prior to the failing + command; just because the first and last commands are needed doesn't mean that + every command between them is + + +Minimizing Verilog designs +-------------------------- + +- manual process +- made easier if the error message is able to identify the source line or name + of the object +- reminder to back up original code before modifying it +- if a specific module is causing the problem, try to set that as the top + module, you can then remove + + + if the problem is parameter specific you may be able to change the default + parameters so that they match the problematic configuration + +- as with `minimize your script`_, if you have no idea what is or is not + relevant, try to follow a "binary search" type approach where you remove (or + comment out) roughly half of what's left at a time +- focusing on one type of object at a time simplifies the process, removing as + many as you can until the error disappears if any of the remaining objects are + removed +- periodically check if anything is totally disconnected (ports, wires, etc), if + it is then it can be removed too +- start by removing cells (instances of modules) + + + if a module has no more instances, remove it entirely + +- then processes +- try to remove or reduce assignments and operations + + + are there any wires/registers which get read but never written? + + * try removing the signal declaration and replacing references to it with + ``'0`` or ``'x`` + * try this with constants too + + + can you replace strings with numeric values? + + are you able to simplify any operations? like replacing ``a & '0`` with + ``'0`` + + if you have enable or reset logic, does the error still happen without that? + + can you reduce an ``if .. else`` to a single case? + +- if you're planning to share the minimized code: + + + make sure there is no sensitive or proprietary data in the design + + instead of a long string of numbers and letters that had some meaning (or + were randomly or sequentially generated), can you give it a single character + name like ``a`` or ``x`` + + please try to keep things in English, using the letters a-z and numbers 0-9 + (unless the error is arising because of the names used) + + +Creating an issue on GitHub +--------------------------- + +- "Reproduction Steps" is ideally a single code-block (starting and ending with + triple backquotes), containing the minimized yosys script file, which includes + the minimized design as a "here document" followed by the sequence of commands + which reproduce the error + +.. TODO:: https://tldp.org/LDP/abs/html/here-docs.html + + Actually fill out :doc:`/using_yosys/more_scripting/load_design` with here + docs info and then link to it from here + +.. code-block:: markdown + + ``` + read_rtlil <