diff --git a/docs/examples/tags/.skip b/docs/examples/tags/.skip index 5057937..8bc8ee6 100644 --- a/docs/examples/tags/.skip +++ b/docs/examples/tags/.skip @@ -3,3 +3,4 @@ bad complex default example +dependencies diff --git a/docs/examples/tags/dependencies.mk b/docs/examples/tags/dependencies.mk new file mode 100644 index 0000000..b117799 --- /dev/null +++ b/docs/examples/tags/dependencies.mk @@ -0,0 +1,14 @@ +.PHONY: stage_1 stage_2 stage_2_alt +dependencies_%: dependencies.sby + sby -f dependencies.sby $* + +STAGE_1_TARGS = dependencies_stage_1 +stage_1: $(STAGE_1_TARGS) + +STAGE_2_TARGS = dependencies_stage_2a dependencies_stage_2b +$(STAGE_2_TARGS): stage_1 +stage_2: $(STAGE_2_TARGS) + +# both tasks together +stage_2_alt: stage_1 + sby -f dependencies.sby stage_2a stage_2b diff --git a/docs/examples/tags/dependencies.sby b/docs/examples/tags/dependencies.sby new file mode 100644 index 0000000..1eb500a --- /dev/null +++ b/docs/examples/tags/dependencies.sby @@ -0,0 +1,4 @@ +[tasks] +stage_1 +stage_2a +stage_2b diff --git a/docs/source/advanced/tags.rst b/docs/source/advanced/tags.rst index c133ebc..4c458e1 100644 --- a/docs/source/advanced/tags.rst +++ b/docs/source/advanced/tags.rst @@ -57,9 +57,10 @@ Default tasks A special tag, ``default``, is provided for controlling which tasks should be run when no specific tasks are provided. The ``--dumpdefaults`` option is -provided for getting the list of default tasks for a given ``.sby`` file. Note -that ``default`` does *not* get added to the list of tags, and should not be -used for controlling conditional lines. +provided for getting the list of default tasks for a given ``.sby`` file. If no +``default`` tag is provided, all tasks listed in the ``[tasks]`` section will be +used as the default. Note that ``default`` does *not* get added to the list of +tags, and should not be used for controlling conditional lines. .. literalinclude:: /../examples/tags/default.sby :language: sby @@ -134,3 +135,53 @@ an error message if an unknown host/device is used, and demonstrates that care must be taken when using regex matching. e.g. without the ``assert task is None`` line, a task of ``witness_hAdX`` would provide an error message about ``mode`` being unset, which may not be immediately obvious as to why that is. + + +Running tasks in parallel +------------------------- + +By default, if there are multiple tasks available then SBY will attempt to run +them in parallel. If SBY is called by a modern version of ``make``, it will +attempt to connect to the Make jobserver for controlling parallelism. If no +jobserver is available, such as when calling ``sby`` directly, the maximum +number of parallel jobs can be set by the ``-j`` command line option: + +.. code-block:: shell + + # Calling SBY with up to 4 parallel tasks + sby -j4 .sby + +Task dependencies with Make +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Say we have some set of tasks which can be broken into two stages, and the +second stage shouldn't run until the first stage has completed. In SBY we have +no way to describe such a dependency. Instead, we can use a Makefile for flow +control: + +.. literalinclude:: /../examples/tags/dependencies.sby + :language: sby + :caption: ``docs/examples/tags/dependencies.sby`` + +.. literalinclude:: /../examples/tags/dependencies.mk + :language: make + :caption: ``docs/examples/tags/dependencies.mk`` + :start-after: PHONY + :end-before: both tasks + +Since each task will (by default) output to a directory called +``_``, we are able to provide a single pattern rule that +will call ``sby`` for any given ````. + +An alternative approach is to define a single rule for each stage, allowing a +single invocation of SBY to run multiple tasks. Remember that SBY can connect +to the Make jobserver, so no parallelism is lost here. This may even reduce the +overhead of launching multiple ``sby`` processes, particularly if there are many +tasks. + +.. literalinclude:: /../examples/tags/dependencies.mk + :language: make + :caption: Make rule for running both stage 2 tasks together + :start-after: both tasks + + diff --git a/docs/source/reference.rst b/docs/source/reference.rst index e66ba87..91767f6 100644 --- a/docs/source/reference.rst +++ b/docs/source/reference.rst @@ -74,9 +74,11 @@ It is possible to check the pre-processed config file for a given task with the first. -Note that there is currently no way to specify dependencies on other tasks. For complex flows where such dependencies are needed, consider using separate ``.sby`` files, or a single file with external scripting. For an advanced example which uses tasks and external scripting to implement a multi-stage verification -flow, see `AppNote 130: Multi-Stage Verification -`_. +Note that there is currently no way to specify dependencies on other tasks. For +complex flows where such dependencies are needed, refer to :ref:`Task +dependencies with Make`. For an advanced example which uses tasks and external +scripting to implement a multi-stage verification flow, see `AppNote 130: +Multi-Stage Verification `_. Options section --------------- diff --git a/tests/staged_sim_and_verif/dependencies.mk b/tests/staged_sim_and_verif/dependencies.mk new file mode 100644 index 0000000..8633fa8 --- /dev/null +++ b/tests/staged_sim_and_verif/dependencies.mk @@ -0,0 +1,15 @@ +skip_staged_flow_%: skip_staged_flow.sby + sby -f skip_staged_flow.sby $* + +skip_staged_flow_stage_1: skip_staged_flow_prep +skip_staged_flow_stage_2: skip_staged_flow_stage_1 +skip_staged_flow_stage_3_init: skip_staged_flow_stage_2 +skip_staged_flow_stage_3a_cover skip_staged_flow_stage_3b_assert: skip_staged_flow_stage_3_init + +.PHONY: stage_3 +stage_3: skip_staged_flow_stage_3a_cover skip_staged_flow_stage_3b_assert + +.PHONY: clean +clean: + @rm -rf skip_staged_flow + @rm -rf skip_staged_flow_*