##########
User Guide
##########

.. toctree::
   :maxdepth: 1

   fundamentals
   packages
   tasks_using
   tasks_developing
   configuration
   stdlib

DV Flow input specification builds on three key concepts:

* **Package** - A packages is a parameterized namespace that defines tasks and types.
* **Task** - A task is a processing step in a flow. Tasks represent a data-processing step, which
  might be as simple as building a list of files, or might be a complex as creating a hardened macro
  from multiple source collections. 
* **Dataflow Dependencies** - Tasks are related by dataflow dependencies. In order for a task to 
  execute, the data from all of its dependencies must be available. Each task also produces 
  dataflow items that can be consumed by other tasks. 

The execution graph of a root task (or tasks) and its dependencies is statically known.
The precise data conveyed between tasks via dataflow is only known at runtime.

Let's look at an example to better-understand these concepts.

.. code-block:: YAML

    package:
      name: my_ip
      tasks:
        - name: rtl
          uses: std.Fileset
          with:
            base: "rtl"
            include: "*.sv"

        - name: tb
          uses: std.Fileset
          needs: [rtl]
          with:
            base: "tb"
            include: "*.sv"

        - name: sim
          uses: hdlsim.vlt.SimImage
          needs: [rtl, tb]

        -name: test1
          uses: hdlsim.vlt.RunSim
          needs: [sim]

The code above specifies two collections of source code --
one for the design and one for the testbench. This source
code is compiled into as simulation image using the 
pre-defined task named `hdlsim.vlt.SimImage`. After,
we execute the simulation image.


.. mermaid::

    flowchart TD
      A[rtl] --> B[tb]
      B[tb] --> E[sim]
      E --> F[test1]

The task graph for this flow is shown above. Each step depends on the
prior step, so there is no opportunity for concurrent execution.

Now, let's say that we want to run a series of tests. We can add 
a new task per tests, where we customize the activity that is run
by passing arguments to the simulation.

.. code-block:: YAML

    # ...
        -name: test1
          uses: hdlsim.vlt.RunSim
          needs: [sim]
        -name: test2
          uses: hdlsim.vlt.RunSim
          needs: [sim]
        -name: test3
          uses: hdlsim.vlt.RunSim
          needs: [sim]

.. mermaid::

    flowchart TD
      A[rtl] --> B[tb]
      B[tb] --> E[sim]
      E --> F[test1]
      E --> G[test2]
      E --> H[test3]

Our task graph now looks like the above. Our build tasks are sequential,
while our test tasks only depend on the simulation image being
up-to-date, and and can execute concurrently.

Dataflow
--------

What ties all the tasks above together is dependency-based dataflow.

.. code-block:: YAML

        - name: tb
          uses: std.Fileset
          needs: [rtl]
          with:
            base: "tb"
            include: "*.sv"

        - name: sim
          uses: hdlsim.vlt.SimImage
          needs: [rtl, tb]

When the `sim` task places dependencies on the `rtl` and `tb`
tasks, it receives the output from those tasks as input. In 
this case, that means that the simulation-image compilation
task has a list of all of the source files that it needs to
compile. The `sim` task also produces an output, which contains 
a reference to the directory where the simulation image resides.
The `test` tasks use this input to locate the simulation image.