Target parameters reference

1 Target parameters

The is a reference for the core logic and format of the target parameter framework.

1.1 File format

A Simics script file can either be a YAML file containing parameter and/or argument declarations, with a pointer to a separate file containing code, or have a parameter declaration section in YAML format placed at the top of a file with Simics CLI or Python code.

In the former case, the file format has the following specifications:

• It must start with the YAML 1.2 directive, i.e. %YAML 1.2
• The whole file must be valid YAML.
• It must contain exactly one YAML document.
• The YAML document must have document start marker immediately after the YAML 1.2 directive. The document must contain the parameters, arguments and any other meta-data. This is specified in Section 1.3
• The document must have a document end marker.

In the latter case, the file format has the following specifications:

• The file may start with any number of blank lines or comment lines (starting with #), and must be followed by the parameter start marker, which is a line ''' followed by a line %YAML 1.2 (in Python code) or @''' followed by %YAML 1.2 (in Simics CLI code), followed by a line ---
• Some subsequent line must be ''', which marks the end of the parameter block.
• The text between these lines must be valid YAML and must contain the parameters, arguments and any other meta-data. This is specified in Section 1.3
• Any text on lines following the ''' line must be code.

1.2 Semantics

The parameters definitions form a tree. The leaves in this tree are the individual parameters, which have types and other meta-data. The contents of an inner node can either be defined in the same script, or it can contain a parameter tree imported from another script.

The run-time value for a parameter can be specified in multiple places, either in the script itself or by callers, recursively, since callers have access to parameters of scripts that they call, via imports. The actual value is the one from the first (outermost) specification. In effect, parameters are write-once, or equivalently parameter values are not set, only parameter default values.

When a script runs another script that it has imported parameters from, the corresponding sub-tree with arguments must be provided by the caller, using the namespace parameter to the load-target or run-script commands.

1.3 Parameter section

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 1.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 1.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 targets.

1.3.1 Parameter tree nodes

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:
  1. str - for string values.
  2. int - for unbounded integer values.
  3. float - for floating point values.
  4. bool - for boolean values.
  5. i8, u8 up to i256, u256 - for integers values with specified bit size.
  6. list or list[<type>] - for list values, optionally specifying the element type (which can itself be a list type).
  7. 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 1.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 advance 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 in 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.
• defaults - whose value must be a mapping. The format of the mapping is the same as the args mapping: the keys in 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, ands its keys are parameter names whose values must be parameter definitions, as defined above.

1.3.1.1 Array parameters

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].

1.3.2 Argument specifications

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.

1.3.3 Parameter references

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.

1.4 Runtime evaluation order

Running a script can be done in several ways:

• Using the load-target or run-script commands.
• Specifying the target name or script file name on the Simics command line,
• Using targets key in the script parameter section, since that effectively runs the specified script from the current script.

In the first two cases, one can also provide arguments on the command line. In the last case, the args section in the current script is used as input.

When running a script, the following happens:

1. The script and all its imports are parsed, recursively, to construct its parameter tree and argument (default value) tree.
2. If the script is not the top level script to run, then all arguments have been assigned already. If it is the top level script, then the arguments are assigned as follows:
   1. The argument tree is taken from the args section in the script, then it is overridden using any arguments on the command line, or using the args section in the script containing the targets key.
   2. Assign parameters using the default values specified in the parameter definitions.
   3. Assign parameters from the argument tree, overwriting any assignments from default values.
   4. Check that all required parameters have been assigned.
   5. Check that everything in argument tree has been used to assign parameters.
3. Any associated pre-init code is run. It can use params.setdefault to assign parameters. If the parameter is already assigned this statement has no effect.
4. All mentioned blueprints are expanded, using the same blueprint builder (unless the blueprints are included via a script inside an array namespace, in which case each one has its own builder). All blueprints are then instantiated.
5. The associated code is run. It can use params.setdefault to assign parameters. If the parameter is already assigned this statement has no effect.

Note that a script containing a targets key may itself be called by another script using the targets key. It follows from the above that the arguments from the caller script overrides the callee, and by induction, in a series of caller script the arguments from the outermost script are used.