From e52c93598b1bbbf48fd1740b0980c276de04c43c Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Mon, 28 Apr 2025 11:46:44 +1200 Subject: [PATCH] bugpoint.rst: Minimizing scripts part 2: electric boogaloo --- docs/source/using_yosys/bugpoint.rst | 66 ++++++++++++++++++---------- 1 file changed, 44 insertions(+), 22 deletions(-) diff --git a/docs/source/using_yosys/bugpoint.rst b/docs/source/using_yosys/bugpoint.rst index e7bbfa665..ca54bc8f0 100644 --- a/docs/source/using_yosys/bugpoint.rst +++ b/docs/source/using_yosys/bugpoint.rst @@ -308,38 +308,60 @@ being needed for the specific problem to be preserved until it causes a crash. So to find the smallest possible reproducer it can sometimes be helpful to remove commands prior to the failure point. +The simplest way to do this is by writing out the design, resetting the current +state, and reading back the design: +.. code-block:: yoscrypt -- try ``write_rtlil ; design -reset; read_rtlil ;`` before - the failure point + write_rtlil ; design -reset; read_rtlil ; - + 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 +In most cases, this can be inserted immediately before the failing command while +still producing the error, allowing you to `minimize your RTLIL`_ with the +```` output. For our previous example with `memory_map`, if +:ref:`map_reset` still gives the same error, then we should now be able to call +``yosys design.il -p 'memory_map'`` to reproduce it. - * 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 +.. code-block:: yoscrypt + :caption: resetting the design immediately before failure + :name: map_reset + + synth -top -run :fine + opt -fast -full + write_rtlil design.il; design -reset; read_rtlil design.il; + memory_map + +If that doesn't give the error (or doesn't give the same error), then you should +try to move the write/reset/read earlier in the script until it does. 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. + + As an 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 +A more conservative, but more involved, method is to remove or comment out +commands prior to the failing command. Each command, or group of commands, can +be disabled one at a time while checking if the error still occurs, eventually +giving the smallest subset of commands needed to take the original input through +to the error. The difficulty with this method is that depending on your design, +some commands may be necessary even if they aren't needed to reproduce the +error. For example, if your design includes ``process`` blocks, many commands +will fail unless you run the `proc` command. While this approach can do a +better job of maintaining context, it is often easier to *recover* the context +after the design has been minimized for producing the error. For more on +recovering context, checkout :ref:`using_yosys/bugpoint:Why context matters`. Minimizing Verilog designs