Docs: Running tasks in parallel

Also using make for dependency management/ordering.
Includes `tests/stage_sim_and_verif/dependencies.mk` file because I was using that to check my make logic (and the docs example is once again incomplete sby).

docs/examples/tags/.skip

@@ -3,3 +3,4 @@ bad
 complex
 default
 example
+dependencies

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

docs/examples/tags/dependencies.sby

@@ -0,0 +1,4 @@
+[tasks]
+stage_1
+stage_2a
+stage_2b

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 <jobname>.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
+``<jobname>_<taskname>``, we are able to provide a single pattern rule that
+will call ``sby`` for any given ``<taskname>``.
+
+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
+
+

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
-<https://yosyshq.readthedocs.io/projects/ap130>`_.
+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 <https://yosyshq.readthedocs.io/projects/ap130>`_.
 
 Options section
 ---------------

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_*