This page describes the grammar and usage of a sparta parameter file.

Configuration files are a subset of YAML (spec v1.2) used to assign values to parameters in a Sparta TreeNode hierarchy (sparta::TreeNode). The format is simple: a typical YAML file consists of nested YAML maps which describe how the device tree is traversed to assign parameters. Each key within these maps represents a relative path in the device tree. Each value can be another map (implying descent deeper into the tree) or a value to assign to the location indicated by the key. These leaf values are either a scalar (e.g. string, integer) or a sequence (of strings, integers, other vectors, etc.)

Configuration files are typically applied at the global namespace in the device tree (above the "top" object).

This example shows a very simple usage of parameter files. Note that block-style maps in YAML are indicated by "key: value" syntax and that the value can be an additional, nested map.

# YAML comment. Lost during interpretation
top:
   a:
     params:
        param1: 1
        param2: foo

This tree assigns values 1 and foo to the sparta::Parameter nodes located at top.a.params.param1 and top.a.params.param2 respectively. It is up to the sparta::Parameter objets to interpret the value as a native type instead of a string (if necessary).

Note that multiple levels in the tree can be specified in one mapping key. The previous configuration file can be rewritten as:

top.a.params:
   param1: 1
   param2: foo

For sparta::Parameter's which are vectors (or nested vectors), YAML in-line sequence syntax can be used to represent the value.

top.a.params:
   one_dimension_vec_param: [1,2,3,4,5]  # This can be read by a 1-dimensional vector parameter
   two_dimension_vec_param: [[1],[2,3,4]]  # This can be read by a 2-dimensional vector parameter

It is also important that YAML keys and values cannot begin with '*' or '?' and must not contain '#', ':', '{', or '}' characters without putting the entire string in quotes.

Nesting

It is often useful to nest configuration files. For example if a simualtor contains repeating hierarchies, one configuration file can be used for each level. Using the reserved include key allows a configuration file to specify that another configuration file should be applied at that context. At this time, the second configuration file is expected to be a relative path to the currently-parsed config file.

Consider

# top_a.yaml
top:
   a.params:
      a_param_1: 1
      a_param_2: 2
   b:
      include: b.yaml # Applies b.yaml configuration in this context (top.b)

# b.yaml
# To be applied at top.b
params:
   b_param_1: 1 # Assigns "1" to top.b.params.b_param_1
   b_param_2: 2

Note that "#include" or "include" can be used as the key. If the former is used, double-quotes are required to prevent it from being interpreted as YAML comment.

Parameter Assignment Attributes and Optional Parameters

Attributes can be assigned to parameters specified in configuration files that dictate how those parameters values are applied.

Following normal configuration file syntax, parameter-assignment attributes can be attached to a parameter using a value "<ATTRIBUTE>" (where ATTRIBUTE is some meaningful attribute name) as if it were a typical value being assigned to a parameter. These attribute names are case-sensitive.

top.foo.params:

myparam: <ATTRIBUTE>

Parameter paths which include wildcards are welcome. Additional value-assignments of parameters following the attribute assignment may modify or remove the attribute depending on the specific attribute.

Optional Parameters
A parameter specified in a configuration file can be modified so that the simulator suppresses the error that would otherwise occur if the node referred to did not actually exist in the simulated device tree.

By assigning "<OPTIONAL>" as a value for the chosen parameter(s), the user prevent errors if that/those parameters are missing from the simulation tree.

top.foo.params:
   param_that_does_not_exist: 12345
   param_that_does_not_exist: <OPTIONAL>

With this, a user can inherit from other configuration files even if those files contain parameters which do not always exist or do not ever exist in the simulated tree for which the inheriting configuration file is intended. For example, if a configuration file for version 1 of some system included a subcomponent that version 2 did not have, version 2 could still inherit from configuration files for version 1 by marking certain inapplicable parameters from the version 1 file as optional.

top:
   core*:
      version_1_component:
         params:
            "*": <OPTIONAL>

This can also be used to generalize parameter files by assigning values using overly-broad paths using wildcards and and then mark a few exceptions to the the pattern as optional.

Examples

This example shows a variety of ways parameters can be set in a configuration file:

"// Sparta cfg file comment": "value of comment“ # Eventually, comments like these may be reprocuded in config file output a Sparta simulator
"//a.params.param1": 1 # Interpreted as commented line
"//": "this is a test device tree configuration file"
top:
   a:
     params:
     param1: 12
 
top.a:
  "b":
   {
      "params.param1": 56,
      "params": {
           "#include" : "test_other.yaml"
      }
   }
   params:
     "param5":   [1.0, 1.1, 2, 3, 5.5]
     "param6": "0xdeadbeef"
     param7: "070"
     param8: [0xa1, 0xb2, 0xc3]
 
     # This is a comment that will be lost
"top.a.params.param2": 34
"top.a.params.param3": |
    [5,6,7,8]
top.a.params.param9 : string with spaces
"// block comment":
{
    # This is all ignored because the key associated with this mapping begins with "//"
     "a.paramsnonexistant_param": false,
     "b": {
        params.nonexistant_param": false
     }
 }

It is up to the user to identify the types of each parameter. This can most easily done by automatically generating a configuration file containing the simulator's default configuration and then modifying this file. See 2.1 Parameters