Type System API¶
DV Flow Manager provides a type system for defining structured data that flows between tasks. Types can be defined in packages, inherit from other types, and be used as the basis for tasks and parameters.
Overview¶
The type system enables:
Structured Data: Define complex data structures with typed fields
Inheritance: Build on existing types to create specialized variants
Type Safety: Ensure data consistency across task boundaries
Documentation: Self-documenting data contracts between tasks
Type Definition¶
Types are defined in packages using the types section:
package:
name: my_types
types:
- name: BaseOptions
doc: Common compiler options
with:
optimization:
type: str
value: "-O2"
doc: Optimization level
warnings:
type: list
value: []
doc: Warning flags to enable
Type Inheritance¶
Types can inherit from other types using the uses field:
types:
- name: BaseOptions
with:
optimization:
type: str
value: "-O2"
- name: DebugOptions
uses: BaseOptions
with:
debug_symbols:
type: bool
value: true
optimization:
value: "-O0" # Override parent value
The DebugOptions type inherits all parameters from BaseOptions and:
Adds a new
debug_symbolsparameterOverrides the
optimizationparameter’s default value
Using Types as Task Bases¶
Types can be used as the base for tasks, creating “DataItem” tasks that produce data without executing code:
package:
name: my_pkg
types:
- name: SimOptions
with:
trace:
type: bool
value: false
seed:
type: int
value: 0
tasks:
- name: default_sim_opts
uses: SimOptions
with:
trace: true
seed: 42
This task produces a SimOptions data item with the specified values.
Tasks depending on default_sim_opts receive this structured data.
Type Schema¶
TypeDef Structure¶
The TypeDef class defines the YAML schema for types:
class TypeDef(BaseModel):
name: str # Type name
uses: str = None # Base type to inherit from
doc: str = None # Documentation
params: Dict # Field definitions (alias: "with")
srcinfo: SrcInfo # Source location
Field Definition¶
Each field in a type’s with section can be:
Simple value:
types:
- name: Simple
with:
field1: "value"
field2: 42
ParamDef with metadata:
types:
- name: Documented
with:
field1:
type: str
value: "default"
doc: "Field documentation"
Field Types¶
Supported field types:
str: String values
int: Integer values
bool: Boolean values (true/false)
list: List of values
map: Dictionary of key-value pairs
Complex types can nest:
types:
- name: Complex
with:
settings:
type: map
value:
key1: "value1"
key2: "value2"
files:
type:
list:
item: str
Runtime Type System¶
Type Class¶
At runtime, types are represented by the Type class:
@dataclass
class Type:
name: str # Qualified type name
doc: str # Documentation
params: Dict[str, TypeField] # Field definitions
paramT: Any # Parameter class
uses: Type # Base type
srcinfo: SrcInfo # Source location
typedef: TypeDef # Original definition
TypeField Class¶
Individual fields are represented by TypeField:
@dataclass
class TypeField:
name: str # Field name
type: Any # Field type
doc: str # Documentation
value: str # Default value
append: List[Any] # Values to append (for list types)
srcinfo: SrcInfo # Source location
Creating Type Instances¶
Types are instantiated when creating data items:
# In a task implementation
async def MyTask(ctxt, input):
# Create a data item of a custom type
item = ctxt.mkDataItem("my_pkg.SimOptions")
item.trace = True
item.seed = 42
return TaskDataResult(
output=[item]
)
The runtime ensures that the data item conforms to the type definition.
Standard Library Types¶
std.DataItem¶
The base type for all data items:
types:
- name: DataItem
with:
type:
type: str
All custom types should ultimately derive from std.DataItem (directly
or indirectly).
std.FileSet¶
Structured file collection with metadata:
types:
- name: FileSet
uses: std.DataItem
with:
filetype: str # File type (e.g., "verilogSource")
basedir: str # Base directory
files: list # List of file paths
incdirs: list # Include directories
defines: list # Preprocessor defines
attributes: list # Tags/attributes
std.Env¶
Environment variable mappings:
types:
- name: Env
with:
vals: map # Environment variable values
append_path: map # Paths to append
prepend_path: map # Paths to prepend
Best Practices¶
Type Naming¶
Use PascalCase for type names (
SimOptions,CompilerFlags)Choose descriptive names that indicate the data’s purpose
Prefix with package name for clarity in large projects
Type Organization¶
Define common types in a dedicated types package
Import type packages where needed
Use inheritance to avoid duplication
Type Documentation¶
Document each type’s purpose in the
docfieldDocument each field’s meaning and valid values
Include examples in the documentation
Example: Complete Type Definition¶
package:
name: hdl_types
types:
- name: CompilerOptions
doc: |
Common options for HDL compilation tools.
Used to configure simulators, synthesizers, and linters.
with:
optimization:
type: str
value: "-O2"
doc: Optimization level (-O0, -O1, -O2, -O3)
warnings:
type: list
value: []
doc: List of warning flags to enable
defines:
type: map
value: {}
doc: Preprocessor defines as key-value pairs
- name: SimulatorOptions
uses: CompilerOptions
doc: Simulator-specific options extending compiler options
with:
trace:
type: bool
value: false
doc: Enable waveform tracing
coverage:
type: bool
value: false
doc: Enable coverage collection
seed:
type: int
value: 0
doc: Random seed (0 = random)
This defines a type hierarchy for tool configuration that can be extended and customized throughout a project.