From b429fba5ac57953079f2f09b7f61467e9893f09e Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 25 Mar 2025 17:06:05 +1300 Subject: [PATCH] Docs: How to use bugpoint paragraphs --- docs/source/using_yosys/bugpoint.rst | 99 ++++++++++++++++++++++------ 1 file changed, 79 insertions(+), 20 deletions(-) diff --git a/docs/source/using_yosys/bugpoint.rst b/docs/source/using_yosys/bugpoint.rst index d3d418ea5..7d38124bf 100644 --- a/docs/source/using_yosys/bugpoint.rst +++ b/docs/source/using_yosys/bugpoint.rst @@ -104,34 +104,75 @@ that the pass/fail can be detected correctly. Multiple calls to `exec` can be made, or even entire shell scripts (e.g. ``exec -expect-return 1 -- bash ``). +Our final failure we can use with `bugpoint` is one returned by a wrapper +process, such as ``valgrind`` or ``timeout``. In this case you will be calling +something like `` yosys -s design.il``. Here, Yosys is +run under a wrapper process which checks for some failure state, like a memory +leak or excessive runtime. Note however that unlike the `exec` command, there +is currently no way to check the return status or messages from the wrapper +process; only a binary pass/fail. + How do I use bugpoint? ~~~~~~~~~~~~~~~~~~~~~~ -- 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 +At this point you should have: - + only checks log file, will not match runtime errors - + can be particularly important for scripts with multiple commands to avoid - unrelated failures - + call e.g. ``yosys -qqp '' design.il`` or ``yosys -qqs - design.il`` to print only the error message(s) and use that (or a portion of - that) as the ```` to search for +1. either an RTLIL file containing the design to minimize (referred to here as + ``design.il``), or a Yosys script, ````, which loads it; and +2. a Yosys script, ````, which produces the failure and returns a + non-zero return status. -- ``-modules``, ``-ports``, ``-cells``, ``-processes``, and ``-wires`` will - enable only those parts of the design to be removed (default is to allow - removing all) +Now call ``yosys -qq -s design.il`` and take note of the error(s) +that get printed. A template script, ````, is provided here which +you can use. Make sure to configure it with the correct filenames and use only +one of the methods to load the design. Fill in the ``-grep`` option with the +error message printed just before. If you are using a wrapper process for your +failure state, add the ``-runner ""`` option to the `bugpoint` call. +For more about the options available, check ``help bugpoint`` or +:doc:`/cmd/bugpoint`. - + 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 +.. code-block:: yoscrypt + :caption: ```` template 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``) + # Load design + read_rtlil design.il + ## OR + script + + # Call bugpoint with failure + bugpoint -script -grep "" + + # Save minimized design + write_rtlil min.il + +.. note:: + + Using ``-grep ""`` with `bugpoint` is optional, but helps to ensure + that the minimized design is reproducing the right error, especially when + ```` contains more than one command. Unfortunately this does not + work with runtime errors such as a ``SEGFAULT`` as it is only able to match + strings from the log file. + +.. TODO:: Consider checking ``run_command`` return value for runtime errors. + + Currently ``BugpointPass::run_yosys`` returns ``run_command(yosys_cmdline) == + 0``, so it shouldn't be too hard to add an option for it. Could also be + used with the ``-runner`` option, which might give it a bit more flexibility. + +By default, `bugpoint` is able to remove any part of the design. In order to +keep certain parts, for instance because you already know they are related to +the failure, you can use the ``bugpoint_keep`` attribute. This can be done with +``(* bugpoint_keep *)`` in Verilog, ``attribute \bugpoint_keep 1`` in RTLIL, or +``setattr -set bugpoint_keep 1 [selection]`` from a Yosys script. It is also +possible to limit `bugpoint` to only removing certain *kinds* of objects, such +as only removing entire modules or cells (instances of modules). For more about +the options available, check ``help bugpoint`` or :doc:`/cmd/bugpoint`. + +In some situations, it may also be helpful to use `setenv` before `bugpoint` to +set environment variables for the spawned processes. An example of this is +``setenv UBSAN_OPTIONS halt_on_error=1`` for where you are trying to raise an +error on undefined behaviour but only want the child process to halt on error. .. note:: @@ -141,6 +182,24 @@ How do I use bugpoint? ``ABC`` because they are only read on start-up. While others, such as ``YOSYS_NOVERIFIC`` and ``HOME``, are evaluated each time they are used. +Once you have finished configuration, you can now run ``yosys ``. +The first thing `bugpoint` will do is test the input design fails. If it +doesn't, make sure you are using the right ``yosys`` executable; unless the +``-yosys`` option is provided, it will use whatever the shell defaults to. If +you are using the ``-runner`` option, try replacing the `bugpoint` command with +``write_rtlil test.il`` and then on a new line, ``! yosys -s + test.il`` to check it works as expected and returns a non-zero +status. + +Depending on the size of your design, and the length of your ````, +`bugpoint` may take some time; remember, it will run ``yosys -s `` +on each iteration of the design. The bigger the design, the more iterations. +The longer the ````, the longer each iteration will take. As the +design shrinks and `bugpoint` converges, each iteration should take less and +less time. Once all simplifications are exhausted and there are no more objects +that can be removed, the script will continue and the minimized design can be +saved. + What do I do with the minimized design? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~