At the top level, the parameter section must be a YAML mapping. The script parameter framework define the following keys at the top level:
params - whose value must be a mapping.
This defines the tree of parameter definitions available in the script.
The keys in the mapping are the parameter names and the values are parameter definitions.
See Section 3.1 for the format of each parameter definition.args - whose value must be a mapping.
This defines the tree of arguments (parameter default values) used when the script is run.
A script that only has an args, no params section (either directly or via imports from other scripts) and no code, is known as a preset.
See Section 3.2 for the format arguments.description - the description of the script, shown by help, when listing parameters, GUI views, and other user interfaces.target - the file name of the script where parameter definitions and script code are taken from when the current script is run.
This is typically used in presets.
If this key is provided, then it is illegal to also have associated code for the current script.
Note that the referred script can also be a preset.script - the file name of the associated code for the current script, that is run after any mentioned blueprints are instantiated.
If this key is provided, it is illegal to also have code inlined in the same file or as a YAML string.cmd - code given as a YAML string.
If this key is provided, it is illegal to also have code inlined in the same file or to also specify the script key.pre-init - the file name of associated pre-instantiation code for the current script, that is run before any mentioned blueprints are expanded.code-type - the type of the associated code.
The allowed values are simics for Simics CLI scripts, or py for Python code.
This key defaults to simics if the file has extension .simics or .include and it defaults to py if the file has extension .py or .yml.
Otherwise this key is mandatory if the script has associated code.Typically one either has a params section and associated code, either inlined or in a separate file referenced by the script key, or one has an args section and reference another script via the target key.
Note that one can have a params section when the target key is specified, but those parameters cannot be used by the script since it has no code.
However they can be used by scripts that include the current script.
It is illegal to have a parameter in params that is also present in the script specified by target.
Each parameter definition must be a YAML mapping. It either defines an inner node (a namespace) in the parameter tree, or an actual parameter.
Parameters are defined by including the type key.
In that case the following keys are defined:
type - the type of values this parameter accepts.
The allowed types are:
str - for string values.int - for unbounded integer values.float - for floating point values.bool - for boolean values.i8, u8 up to i256, u256 - for integers values with specified bit size.list or list[<type>] - for list values, optionally specifying the element type (which can itself be a list type).file - for file names.
These are string values where %simics% and %script% are evaluated in the usual manner.
The files must exist when the target is run.required - specifies if the parameter must have an assigned value when the script is run.
The default is true.default - the parameter default value.
See Section 4 for how arguments are set.
The default is to have no default value, resulting in an unassigned parameter.description - a description of the parameter.values - a list of allowed parameter values.
If this key is included, it is illegal to set the parameter to a value not in this list.output - specifies if the parameter is an output parameter, default is false.
Output parameters are meant to denote computed values that are defined as parameters for convenience.
They are not included in the output of params.save.advanced - specifies the advanced level of the parameter.
The default is 1.
Specifying a higher level results in the parameter being hidden by default when using params.help and similar places.allow_empty - specifies that NIL is a valid value of the parameter, default is false.An inner node may be an import node, defined by having the import key, or a blueprint import node, defined by having the blueprint key.
In the import case the following keys are defined:
import - the file name where parameters should be imported from.provides - whose value must be a list.
The list must contain names of imported parameters, and it specifies that these parameters are not required when running the current script, whether or not they were required in the imported script.
This is typically used when the current script sets default values of the parameters before running the imported script.defaults - whose value must be a mapping.
The format of the mapping is the same as the args mapping: the keys must be names of imported parameters and the values are the new default values, overriding the defaults specified in the imported scripts.In the blueprint import case, the following keys are defined:
blueprint - the name of the blueprint whose parameters should be imported.
This must be the name specified in the blueprint Python decorator.module - the Python module where the blueprint is defined.
It must be possible to import this module.namespace - the top level namespace name that should be used when expanding the blueprint.
This can reference the value of a sibling parameter to the blueprint import node, by having the prefix ^.defaults - whose value must be a mapping.
The format of the mapping is the same as the args mapping: the keys must be names of imported parameters and the values are the new default values, overriding the defaults specified in the blueprint.Every blueprint that is imported is put on the list of blueprints that is expanded between the pre-instantiation code and regular script code is run.
If neither the import, blueprint nor the type key are specified, then the parameter definition is a regular inner node in the parameter tree, and its keys are parameter names whose values must be parameter definitions, as defined above.
Import nodes in the parameter tree may be of array type, whose size depends on another parameter, which must be a required parameter of integer type.
An array node is specified by having a node name of the form <name>[<size>].
At run-time, assuming the <size> parameter is assigned <value>, the argument tree will contain nodes <name>[0], <name>[1], …, <name>[<value>-1].
The argument tree specified by args must match the tree of parameters: the keys are parameter names or names of inner nodes, and the values are the (default) values, or a mapping in the case of inner nodes.
At any node in the argument tree, one can import an argument tree from another script.
This is specified by having the import, whose value must be the file name where arguments should be imported from.
Additional arguments can be specified in the same mapping as the import.
Any parameter can be turned into a reference to another parameter, by specifying a parameter name prefixed with ^ as the parameter value.
This is primarily useful when parameters in different sub-scripts should have the same value, and copying the values using params.setdefault is impractical.
Only parameters in the same script can be referenced, specified from the root of the script, using : as separator when referring to nested parameters.
Reading from a reference has the same effect as reading from the referred parameter.
It is illegal to set a parameter default to be a reference to an unassigned parameter, unless this is done using params.setdefault, in which case it is illegal to read from the reference until the referred parameter is assigned.