diff --git a/docs/source/code_examples/selections/memdemo.ys b/docs/source/code_examples/selections/memdemo.ys index e240f162127..cb7700a7e04 100644 --- a/docs/source/code_examples/selections/memdemo.ys +++ b/docs/source/code_examples/selections/memdemo.ys @@ -4,6 +4,7 @@ prep -top memdemo; memory; opt cd memdemo show -format dot -prefix memdemo_00 show -format dot -prefix memdemo_01 y %ci2 -show -format dot -prefix memdemo_02 y %ci2:+$dff[Q,D] -show -format dot -prefix memdemo_03 y %ci2:-[CLK] %ci2 -show -format dot -prefix memdemo_04 y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff +show -format dot -prefix memdemo_02 y %ci5 +show -format dot -prefix memdemo_03 y %ci5:-$mux[S] +show -format dot -prefix memdemo_04 y %ci*:-[CLK,S]:+$dff,$mux +show -format dot -prefix memdemo_05 y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff diff --git a/docs/source/code_examples/selections/sumprod.out b/docs/source/code_examples/selections/sumprod.out new file mode 100644 index 00000000000..f7c2594994f --- /dev/null +++ b/docs/source/code_examples/selections/sumprod.out @@ -0,0 +1,38 @@ + + + attribute \src "sumprod.v:4.21-4.25" + wire width 8 output 5 \prod + + attribute \src "sumprod.v:10.17-10.26" + cell $mul $mul$sumprod.v:10$4 + parameter \A_SIGNED 0 + parameter \A_WIDTH 8 + parameter \B_SIGNED 0 + parameter \B_WIDTH 8 + parameter \Y_WIDTH 8 + connect \A $mul$sumprod.v:10$3_Y + connect \B \c + connect \Y \prod + end + + + attribute \src "sumprod.v:10.17-10.22" + wire width 8 $mul$sumprod.v:10$3_Y + + attribute \src "sumprod.v:3.21-3.22" + wire width 8 input 3 \c + + attribute \src "sumprod.v:4.21-4.25" + wire width 8 output 5 \prod + + attribute \src "sumprod.v:10.17-10.26" + cell $mul $mul$sumprod.v:10$4 + parameter \A_SIGNED 0 + parameter \A_WIDTH 8 + parameter \B_SIGNED 0 + parameter \B_WIDTH 8 + parameter \Y_WIDTH 8 + connect \A $mul$sumprod.v:10$3_Y + connect \B \c + connect \Y \prod + end diff --git a/docs/source/code_examples/selections/sumprod.ys b/docs/source/code_examples/selections/sumprod.ys index 1e687fa4e66..67e2a28d5c9 100644 --- a/docs/source/code_examples/selections/sumprod.ys +++ b/docs/source/code_examples/selections/sumprod.ys @@ -8,3 +8,6 @@ show -format dot -prefix sumprod_02 prod show -format dot -prefix sumprod_03 prod %ci show -format dot -prefix sumprod_04 prod %ci2 show -format dot -prefix sumprod_05 prod %ci3 + +dump -o sumprod.out prod %ci +dump -a sumprod.out prod %ci2 diff --git a/docs/source/using_yosys/more_scripting/selections.rst b/docs/source/using_yosys/more_scripting/selections.rst index 2bc6540b83c..517304fad81 100644 --- a/docs/source/using_yosys/more_scripting/selections.rst +++ b/docs/source/using_yosys/more_scripting/selections.rst @@ -197,22 +197,39 @@ The following sequence of diagrams demonstrates this step-wise expansion: .. figure:: /_images/code_examples/selections/sumprod_02.* :class: width-helper - Output of ``show prod`` on :numref:`sumprod` + Output of :yoscrypt:`show prod` on :numref:`sumprod` .. figure:: /_images/code_examples/selections/sumprod_03.* :class: width-helper - Output of ``show prod %ci`` on :numref:`sumprod` + Output of :yoscrypt:`show prod %ci` on :numref:`sumprod` .. figure:: /_images/code_examples/selections/sumprod_04.* :class: width-helper - Output of ``show prod %ci %ci`` on :numref:`sumprod` + Output of :yoscrypt:`show prod %ci %ci` on :numref:`sumprod` .. figure:: /_images/code_examples/selections/sumprod_05.* :class: width-helper - Output of ``show prod %ci %ci %ci`` on :numref:`sumprod` + Output of :yoscrypt:`show prod %ci %ci %ci` on :numref:`sumprod` + +Notice the subtle difference between :yoscrypt:`show prod %ci` and +:yoscrypt:`show prod %ci %ci`. Both images show the ``$mul`` cell driven by +some inputs ``$3_Y`` and ``c``. However it is not until the second image, +having called ``%ci`` the second time, that :cmd:ref:`show` is able to +distinguish between ``$3_Y`` being a wire and ``c`` being an input. We can see +this better with the :cmd:ref:`dump` command instead: + +.. literalinclude:: /code_examples/selections/sumprod.out + :language: RTLIL + :end-at: end + :caption: Output of :yoscrypt:`dump prod %ci` + +.. literalinclude:: /code_examples/selections/sumprod.out + :language: RTLIL + :start-after: end + :caption: Output of :yoscrypt:`dump prod %ci %ci` When selecting many levels of logic, repeating ``%ci`` over and over again can be a bit dull. So there is a shortcut for that: the number of iterations can be @@ -263,9 +280,6 @@ diagram in :numref:`memdemo_00`. Complete circuit diagram for the design shown in :numref:`memdemo_src` -.. TODO:: :ref:`memdemo_01` and :ref:`memdemo_02` are the same, probably change - the example so they aren't. - There's a lot going on there, but maybe we are only interested in the tree of multiplexers that select the output value. Let's start by just showing the output signal, ``y``, and its immediate predecessors. Remember `Selecting logic @@ -279,51 +293,52 @@ cones`_ from above, we can use :yoscrypt:`show y %ci2`: From this we would learn that ``y`` is driven by a ``$dff cell``, that ``y`` is connected to the output port ``Q``, that the ``clk`` signal goes into the -``CLK`` input port of the cell, and that the data comes from a auto-generated -wire into the input ``D`` of the flip-flop cell. - -As we are not interested in the clock signal we add an additional pattern to the -``%ci`` action :yoscrypt:`show y %ci2:+$dff[Q,D]`, that tells it to only follow -ports ``Q`` and ``D`` of ``$dff`` cells: +``CLK`` input port of the cell, and that the data comes from an auto-generated +wire into the input ``D`` of the flip-flop cell (indicated by the ``$`` at the +start of the name). Let's go a bit further now and try :yoscrypt:`show y %ci5`: .. figure:: /_images/code_examples/selections/memdemo_02.* :class: width-helper :name: memdemo_02 - Output of :yoscrypt:`show y %ci2:+$dff[Q,D]` - -To add a pattern we add a colon followed by the pattern to the ``%ci`` action. -The pattern itself starts with ``-`` or ``+``, indicating if it is an include or -exclude pattern, followed by an optional comma separated list of cell types, -followed by an optional comma separated list of port names in square brackets. - -Since we know that the only cell considered in this case is a ``$dff`` cell, we -could as well only specify the port names, :yoscrypt:`show y %ci2:+[Q,D]`. Or we -could decide to tell the ``%ci`` action to not follow the ``CLK`` input, -:yoscrypt:`show y %ci2:-[CLK]`. + Output of :yoscrypt:`show y %ci5` -Next we would investigate the next logic level by adding another ``%ci2`` to the -command, :yoscrypt:`show y %ci2:-[CLK] %ci2`: +That's starting to get a bit messy, so maybe we want to ignore the mux select +inputs. To add a pattern we add a colon followed by the pattern to the ``%ci`` +action. The pattern itself starts with ``-`` or ``+``, indicating if it is an +include or exclude pattern, followed by an optional comma separated list of cell +types, followed by an optional comma separated list of port names in square +brackets. In this case, we want to exclude the ``S`` port of the ``$mux`` cell +type with :yoscrypt:`show y %ci5:-$mux[S]`: .. figure:: /_images/code_examples/selections/memdemo_03.* :class: width-helper :name: memdemo_03 - Output of :yoscrypt:`show y %ci2:-[CLK] %ci2` + Output of :yoscrypt:`show y %ci5:-$mux[S]` -From this we would learn that the next cell is a ``$mux`` cell and we would add -an additional pattern to narrow the selection on the path we are interested. In -the end we would end up with a command such as :yoscrypt:`show y %ci2:+$dff[Q,D] +We could use a command such as :yoscrypt:`show y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff` in which the first ``%ci`` jumps over the initial d-type flip-flop and the 2nd action selects the entire input cone without going over -multiplexer select inputs and flip-flop cells. The diagram produced by this -command is shown in :numref:`memdemo_04`. +multiplexer select inputs and flip-flop cells: + +.. figure:: /_images/code_examples/selections/memdemo_05.* + :class: width-helper + :name: memdemo_05 + + Output of ``show y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff`` + +Or we could use :yoscrypt:`show y %ci*:-[CLK,S]:+$dff:+$mux` instead, following +the input cone all the way but only following ``$dff`` and ``$mux`` cells, and +ignoring any ports named ``CLK`` or ``S``: + +.. TODO:: pending discussion on whether rule ordering is a bug or a feature .. figure:: /_images/code_examples/selections/memdemo_04.* :class: width-helper :name: memdemo_04 - Output of ``show y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff`` + Output of :yoscrypt:`show y %ci*:-[CLK,S]:+$dff,$mux` Similar to ``%ci`` exists an action ``%co`` to select output cones that accepts the same syntax for pattern and repetition. The ``%x`` action mentioned