Flow-Spec Reference

This section provides detailed reference documentation for the DV Flow specification format (flow.yaml YAML files).

File Root Elements

Each flow.yaml file either defines a package or a package fragment. Each package is defined by the content in its root flow.yaml file and that in any fragment files that are specified in the root package file or its fragments.

package:
    name: proj1

    # ...

    fragments:
    - src/rtl/flow.yaml
    - src/verif

Each package fragment element specifies either a directory or a file. If a file is specified, then that file is loaded. It is expected that the content will be a DV-Flow package fragment. If a directory is specified, then a top-down search is performed for flow.yaml files in the subdirectory tree.

The structure of a package fragment file is nearly identical to a package definition. For example:

fragment:
    tasks:
    - name: rtl
      type: std.FileSet
      params:
        include: "*.sv"

Remember that all fragments referenced by a given package contribute to the same package namespace. It would be illegal for another flow file to also define a task named rtl.

The schema definitions below are generated from dv.flow.schema.json. They are grouped by role: package structure, tasks, parameters and types, and enumerations.

Package Structure

Package Definition

PackageDef

type	object
properties
name	Name
	Name of the package
	type	string
desc	Desc
	Short description of the package
	type	string
	default	null
type	Type
	List of data types defined by this package
	type	array
	items	#/defs/PackageSpec
tasks	Tasks
	List of tasks defined in the package
	type	array
	items	TaskDef
imports	Imports
	List of packages to import. Can be package names (strings) or import specifications with configuration
	type	array
	items	anyOf	type	string
			PackageImportSpec
overrides	Overrides
	Parameter and package overrides. Maps override targets to replacement values
	type	object
	additionalProperties	type	string
fragments	Fragments
	List of fragment file paths to include in this package
	type	array
	items	type	string
types	Types
	List of data type definitions for this package
	type	array
	items	TypeDef
uses	Uses
	Name of a base package to inherit from. This package extends the base package’s tasks and types
	type	string
	default	null
with	With
	Package parameters
	type	object
	additionalProperties	anyOf	type	string
			type	array
			items
			ParamDef
configs	Configs
	List of package configurations
	type	array
	items	ConfigDef
tags	Tags
	Tags as type references with optional parameter overrides
	type	array
	items	anyOf	type	string
			type	object
			additionalProperties	True
package-map	Package Map
	One or more package-map files (name -> flow file) consulted when resolving imports by name
	default	null
	anyOf	type	string
		type	array
		items	type	string
		type	null

Fragment Definition

FragmentDef

type	object
properties
tasks	Tasks
	List of tasks defined in this fragment
	type	array
	items	TaskDef
imports	Imports
	List of packages to import. Can be package names (strings) or import specifications
	type	array
	items	anyOf	type	string
			PackageImportSpec
fragments	Fragments
	List of nested fragment file paths to include
	type	array
	items	type	string
types	Types
	List of data type definitions for this fragment
	type	array
	items	TypeDef

Configuration Definition

ConfigDef

type	object
properties
name	Name
	Name of the configuration
	type	string
with	With
	Configuration parameters map
	type	array
	items	ParamDef
uses	Uses
	Name of the configuration to use as a base
	type	string
	default	null
overrides	Overrides
	List of package overrides
	type	array
	items	OverrideDef
extensions	Extensions
	List of extensions to apply
	type	array
	items	ExtendDef
imports	Imports
	List of packages to import for this config
	type	array
	items	anyOf	type	string
			PackageImportSpec
fragments	Fragments
	List of fragments to apply for this config
	type	array
	items	type	string
tasks	Tasks
	List of tasks defined/overridden by this config
	type	array
	items	TaskDef
types	Types
	List of types defined/overridden by this config
	type	array
	items	TypeDef

Import Definition

PackageImportSpec

type	object
properties
from	From
	Package identifier or file path to import
	type	string
	default	null
as	As
	Alias name for the imported package
	type	string
	default	null
config	Config
	Configuration name to apply when importing
	type	string
	default	null
with	With
	Parameter overrides to apply to the imported package
	type	object
	additionalProperties	True

Override Definition

OverrideDef

Override definition
type	object
properties
override	Override
	Task or package to override
	anyOf	type	string
		type	null
with	With
	Override to use
	type	string

Extend Definition

ExtendDef

Extension definition
type	object
properties
task	Task
	Name of the task to extend
	type	string
with	With
	Parameter extensions to apply to the task
	type	array
	items	ParamDef
uses	Uses
	Name of the extension to use as a base
	type	string
	default	null
needs	Needs
	List of tasks to depend on
	type	array
	items	type	string

Tasks

Task Definition

TaskDef

Holds definition information (ie the YAML view) for a task
type	object
properties
name	Task Name
	The name of the task
	default	null
	anyOf	type	string
		type	null
root	Root Task Name
	The name of the task (marked as root scope)
	default	null
	anyOf	type	string
		type	null
export	Export Task Name
	The name of the task (marked as export scope)
	default	null
	anyOf	type	string
		type	null
local	Local Task Name
	The name of the task (marked as local scope)
	default	null
	anyOf	type	string
		type	null
override	Overide Name
	The name of the task to override
	default	null
	anyOf	type	string
		type	null
uses	Base type
	Task from which this task is derived
	type	string
	default	null
scope	Task visibility scope
	Visibility scope: ‘root’ (executable), ‘export’ (visible outside package), ‘local’ (fragment-only)
	default	null
	anyOf	type	string
		type	array
		items	type	string
		type	null
body	Body
	Sub-tasks
	type	array
	items	TaskDef
iff	Task enable condition
	Condition that must be true for this task to run
	default	null
	anyOf	type	string
		type	boolean
pytask	Pytask
	Python-based implementation (deprecated)
	type	string
	default	null
run	Run
	Shell-based implementation
	type	string
	default	null
shell	Shell
	Shell to use for shell-based implementation
	type	string
	default	bash
strategy	default	null
	StrategyDef
desc	Task description
	Short description of the task’s purpose
	type	string
	default
doc	Task documentation
	Full documentation of the task
	type	string
	default
needs	Needs
	List of tasks that this task depends on
	type	array
	items	type	string
feeds	Feeds
	List of tasks that depend on this task (inverse of needs)
	type	array
	items	type	string
with	With
	Parameters for the task
	type	object
	additionalProperties	anyOf	type	string
			type	array
			items
			type	integer
			type	boolean
			type	object
			additionalProperties	True
rundir	Specifies handling of this tasks’s run directory
	default	unique
	RundirE
passthrough	Passthrough
	Specifies whether this task should pass its inputs to its output
	default	null
	anyOf	PassthroughE
		type	array
		items
		type	null
consumes	Consumes
	Specifies matching patterns for parameter sets that this task consumes
	default	null
	anyOf	ConsumesE
		type	array
		items
		type	null
uptodate	Uptodate
	Up-to-date check: false=always run, string=Python method, None=use default check
	default	null
	anyOf	type	boolean
		type	string
		type	null
cache	Cache
	Cache configuration. True=enabled with defaults, False=disabled, CacheDef=custom config
	default	null
	anyOf	CacheDef
		type	boolean
		type	null
tags	Tags
	Tags as type references with optional parameter overrides
	type	array
	items	anyOf	type	string
			type	object
			additionalProperties	True
additionalProperties	False

Strategy Definition

StrategyDef

type	object
properties
chain	Chain
	Enable chain strategy: run body tasks sequentially with each consuming output of previous task
	default	null
	anyOf	type	boolean
		type	null
generate	Enable generate strategy: dynamically create tasks by running a shell command that outputs task definitions
	default	null
	anyOf	GenerateSpec
		type	null
matrix	Matrix
	Matrix of parameter values to explore. Creates one task instance per combination of values
	default	null
	anyOf	type	object
		additionalProperties	type	array
			items
		type	null
body	Body
	Body tasks for strategy execution. Used with chain and matrix strategies
	type	array
	items	TaskDef

Generate Specification

GenerateSpec

type	object
properties
shell	Shell
	Shell to use for running the generate command. Defaults to ‘bash’
	default	null
	anyOf	type	string
		type	null
run	Run
	Shell command to execute. Must output valid YAML task definitions to stdout
	type	string

Cache Definition

CacheDef

Cache configuration for a task
type	object
properties
enabled	Enabled
	Whether caching is enabled for this task
	type	boolean
	default	True
hash	Hash
	Extra hash expressions to include in cache key
	type	array
	items	type	string
compression	Compression type for cached artifacts
	default	no
	CompressionType
additionalProperties	False

Parameters and Types

Parameter Definition

ParamDef

type	object
properties
doc	Doc
	Full documentation for this parameter
	type	string
	default	null
desc	Desc
	Short description of this parameter
	type	string
	default	null
type	Type
	Parameter type (e.g., ‘str’, ‘int’, ‘bool’, ‘list’, ‘map’, or a complex type definition)
	default	null
	anyOf	type	string
		ComplexType
value	Value
	Default value for this parameter
	default	null
	anyOf	type	null
append	Append
	Value to append to list-type parameters
	default	null
	anyOf	type	null
prepend	Prepend
	Value to prepend to list-type parameters
	default	null
	anyOf	type	null
path-append	Path-Append
	Path to append to path-type parameters (OS-specific separator)
	default	null
	anyOf	type	null
path-prepend	Path-Prepend
	Path to prepend to path-type parameters (OS-specific separator)
	default	null
	anyOf	type	null

Type Definition

TypeDef

type	object
properties
name	Name
	Name of the data type
	type	string
uses	Uses
	Base type to inherit from. Supports type extension/specialization
	type	string
	default	null
doc	Doc
	Documentation for this type definition
	type	string
	default	null
with	With
	Parameters for this type. Can be simple values or full parameter definitions
	type	object
	additionalProperties	anyOf	type	string
			ParamDef
tags	Tags
	Tags as type references with optional parameter overrides
	type	array
	items	anyOf	type	string
			type	object
			additionalProperties	True

Complex Type

ComplexType

type	object
properties
list	default	null
	anyOf	ListType
		type	null
map	default	null
	anyOf	MapType
		type	null

List Type

ListType

type	object
properties
item	Item
	anyOf	type	string

Map Type

MapType

type	object
properties
key	Key
	anyOf	type	string
val	Val
	anyOf	type	string

Enumerations

Consumes Mode

ConsumesE

type	string
enum	none, all

Passthrough Mode

PassthroughE

type	string
enum	none, all, unused

Run-Directory Mode

RundirE

type	string
enum	unique, inherit

Compression Type

CompressionType

Compression types for cache artifacts
type	string
enum	no, yes, gzip, bzip2