diff --git a/docs/source/using_yosys/bugpoint.rst b/docs/source/using_yosys/bugpoint.rst index a81c36b27..d3d418ea5 100644 --- a/docs/source/using_yosys/bugpoint.rst +++ b/docs/source/using_yosys/bugpoint.rst @@ -45,43 +45,64 @@ Yosys script. Can I use bugpoint? ~~~~~~~~~~~~~~~~~~~ -- only usable on platforms where Yosys can spawn executables +The first thing to be aware of is that `bugpoint` is not available in every +build of Yosys. Because the command works by invoking external processes, it +requires that Yosys can spawn executables. Notably this means `bugpoint` is not +able to be used in WebAssembly builds such as that available via YoWASP. The +easiest way to check your build of Yosys is by running ``yosys -qq -p '!echo +test'``. If this echoes ``test`` in the console, then `bugpoint` will work as +expected. If instead if it displays the text ``ERROR: Shell is not available.`` +then `bugpoint` will not work either. - + unavailable on emscripten and wasm - + can test by running e.g. ``yosys -qqp '!echo test'`` +.. note:: - * 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 - * check :ref:`getting_started/scripting_intro:script parsing` for more about - the ``-p`` option and common pitfalls + The console command ``yosys -qq -p '!echo test'`` uses the ``-qq`` flag to + prevent Yosys from outputting non-error messages to the console. The ``-p`` + option executes ``!echo test`` as a Yosys command, attempting to pass ``echo + test`` to the shell for execution. For more about the ``-p`` option and + common pitfalls, check out :ref:`getting_started/scripting_intro:script + parsing` in the :doc:`/getting_started/index` section. -- single command (``yosys -p '' design.il``) -- *or* multiple commands in a separate script file +.. TODO:: Add ``YOSYS_DISABLE_SPAWN`` check in ``bugpoint.cc``. - + script shouldn't load the design - + ``yosys -s design.il`` - + `minimize your script`_ to reduce the time needed by `bugpoint` + At least in the help text, so that ``yosys -h bugpoint`` will correctly + indicate if the command will work instead of this roundabout method. -- doesn't require design to be in RTLIL format +Next you need to separate loading the design from the failure point; you should +be aiming to reproduce the failure by running ``yosys -s -s +``. If the failure occurs while loading the design, such as during +`read_verilog` you will instead have to minimize the input design yourself. +Check out the instructions for :ref:`using_yosys/bugpoint:minimizing verilog +designs` below. - + 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 +The commands in ```` only need to be run once, while those in +```` will be run on each iteration of `bugpoint`. If you haven't +already, following the instructions for :ref:`using_yosys/bugpoint:minimizing +scripts` will also help with identifying exactly which commands are needed to +produce the failure and which can be safely moved to the loading script. -- works with user-defined failures in scripts +.. note:: - + e.g. `select` command with ``-assert-*`` option - + or `equiv_opt` - + can even call another tool with `exec` - - * useful for when Yosys is outputting an invalid design - * use the ``-expect-*`` options to ensure the script correctly returns the - failure state to `bugpoint` - * can call shell scripts with e.g. ``exec -expect-return 1 -- bash - `` + You should also be able to run the two scripts separately, calling first + ``yosys -s -p 'write_rtlil design.il'`` and then ``yosys -s + design.il``. If this doesn't work then it may mean that the + failure isn't reproducible from RTLIL and `bugpoint` won't work either. + +When we talk about failure points here, it doesn't just mean crashes or errors +in Yosys. The ```` script can also be a user-defined failure such +as the `select` command with one of the ``-assert-*`` options; an example where +this might be useful is when a pass is supposed to remove a certain kind of +cell, but there is some edge case where the cell is not removed. Another +use-case would be minimizing a design which fails with the `equiv_opt` command, +suggesting that the optimization in question alters the circuit in some way. + +It is even possible to use `bugpoint` with failures *external* to Yosys, by +making use of the `exec` command in ````. This is especially useful +when Yosys is outputting an invalid design, or when some other tool is +incompatible with the design. Be sure to use the ``exec -expect-*`` options so +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 +``). How do I use bugpoint? @@ -143,6 +164,7 @@ What do I do with the minimized design? - check out :ref:`using_yosys/bugpoint:identifying issues` for more on what to do next + .. _minimize your script: Minimizing scripts @@ -189,7 +211,6 @@ Minimizing scripts opt -fast -full memory_map - - try ``write_rtlil ; design -reset; read_rtlil ;`` before the failure point @@ -349,7 +370,6 @@ Creating an issue on GitHub `yosys -p ': minimum sequence of commands;' min.v` - - alternatively can provide a single code-block which includes the minimized design as a "here document" followed by the sequence of commands which reproduce the error