Configuration

The config.toml file stores settings and extends Orbit's functionality. It is written in the TOML format. It is maintained by the developer and can be shared across teams for consistent development environments.

Note: The configuration's file name is "config.toml", with respect to case-sensitivity.

Paths

When a field is expected to be a file system path, Orbit has the ability to resolve relative paths. The path is determined in relation to the currently processed config.toml's parent directory. This design choice was implemented in order to allow for path definitions to be valid across developer machines when sharing configurations. It is recommended to use relative paths when setting a path to a field in a config.toml.

Precedence

Orbit supports multiple levels of configuration. Each level has its own order of precedence. The order of precedence is the following:

1. Local configuration file (current ip's .orbit/conifg.toml)

2. Regional configuration files (parent directories of the current working directory)

3. Global configuration file (Orbit's $ORBIT_HOME/config.toml)

4. Included configuration files (order-preserving list found for the global configuration's include field)

The configuration files are processed in the order defined above. When a configuration file defines a field, no other configuration files later in the process will be able to override its value. If a field is never provided an explicit value, the Orbit's default will be used.

Tip: You can modify some values in the configuration file through the command-line by using the orbit config command.

Every configuration file consists of the following sections:

• include - Lists other config.toml files to process. This field is only allowed for the global configuration file.
• [general] - The general settings.
  • target-dir - Default target directory.
• [test] - The test settings.
  • default-target - Set the default target for tests.
• [build] - The build settings.
  • default-target - Set the default target for builds.
• [vhdl-format] - VHDL code formatting.
• [verilog-format] - SystemVerilog/Verilog code formatting.
• [env] - The runtime environment variables.
• [[target]] - Define a target.
  • name - The name of the target.
  • description - A short description of the target.
  • command - The command to execute the target.
  • args - Arguments to pass to the command.
  • plans - The list of supported blueprint file formats.
  • [fileset] - Filesets to collect for the target.
• [[protocol]] - Define a protocol.
  • name - The name of the protocol.
  • description - A short description of the protocol.
  • command - The command to execute the protocol.
  • args - Arguments to pass to the command.
• [[channel]] - Define a channel.
  • name - The name of the channel.
  • description - A short description of the channel.
  • root - The directory where the channel exists.
  • sync.command - The command to execute when synchronizing the channel.
  • sync.args - Arguments to pass to the command during synchronization.
  • pre.command - The command to execute immediately before launch.
  • pre.args - Arguments to pass to the command immediately before launch.
  • post.command - The command to execute immediately after launch.
  • post.args - Arguments to pass to the command immediately after launch.

The include field

include = [
    "profiles/p1/config.toml",
    "profiles/p2/config.toml",
    "channels/c1/config.toml"
]

The [general] section

The target-dir field

Define the default output directory to create for the planning and building phases. This value can be overridden on the command-line when the --target-dir option is available. When this field is not defined, the default value for the build directory is "target".

[general]
target-dir = "target"
# ...

The [test] section

The default-target field

Sets the default target when calling orbit test. If the default target is set to be used and it cannot be found among the known targets, it will error.

[test]
default-target = "foo"

The [build] section

The default-target field

Sets the default target when calling orbit build. If the default target is set to be used and it cannot be found among the known targets, it will error.

[build]
default-target = "bar"

The [vhdl-format] section

The currently supported entries are demonstrated in the following code snippet. Entries not present will be set to their default values.

[vhdl-format]
# enable colored output for VHDL code snippets
highlight-syntax = true
# number of whitespace characters per tab/indentation
tab-size = 2
# insert a tab before 'generic' and 'port' interface declarations
indent-interface = true
# automatically align a signal or constant's subtype with its other identifiers
type-auto-alignment = false
# number of whitespace characters after alignment (before the `:` character)
type-offset = 0
# automatically align an instantiation's mapping along its port connections
mapping-auto-alignment = false
# number of whitespace characters before port connection (before the `=>` character)
mapping-offset = 1
# the default instance name
instance-name = "uX"

The [verilog-format] section

The currently supported entries are demonstrated in the following code snippet. Entries not present will be set to their default values. This section currently applies its settings to SystemVerilog and Verilog source code.

[verilog-format]
# enable colored output for code snippets (TODO)
highlight-syntax = false
# number of whitespace characters per tab/indentation
tab-size = 2
# automatically align a port or parameter's name with the module's other names
name-auto-alignment = false
# number of additional whitespace characters after alignment
name-alignmnet = 0
# number of whitespaces before a range specifier
range-offset = 0
# automatically align an instantiation's mapping along its port connections
mapping-auto-alignment = false
# number of whitespace characters before port connection (before the `(` character)
mapping-offset = 0
# the default instance name
instance-name = "uX"

The [env] section

The user can define an arbitrary number of their own entries with their determined value represented in string format.

[env]
foo = "0" # Accessible as ORBIT_ENV_FOO
super-bar = "1" # Accessible as ORBIT_ENV_SUPER_BAR

The [[target]] array

The name field

[[target]]
name = "dump-blueprint"

The description field

[[target]]
# ...
description = "Print the blueprint contents to the screen"

The command field

[[target]]
# ...
command = "cat"

The args field

[[target]]
# ...
args = ["blueprint.tsv"]

The plans field

[[target]]
# ...
plans = ["tsv"]

The type of blueprint files supported by the particular target. If a list is provided, the default plan used is the first item in the list. If a plan is provided on the command-line, then it must be a valid plan and found within the target's defined list.

If this field is left blank or not defined, then the default plan is "tsv".

The [fileset] section

[[target]]
# ...
fileset.pymdl = "{{ orbit.bench }}.py"

The [[protocol]] array

The name field

See [target]'s definition.

The description field

See [target]'s definition.

The command field

See [target]'s definition.

The args field

See [target]'s definition.

The [[channel]] array

The name field

See [target]'s definition.

The description field

See [target]'s definition.

The root field

The file system path where the channel exists, relative to the configuration file where it is defined.

[[channel]]
# ...
root = "./index"

The sync.command field

See [target]'s definition.

The sync.args field

See [target]'s definition.

The pre.command field

See [target]'s definition.

The pre.args field

See [target]'s definition.

The post.command field

See [target]'s definition.

The post.args field

See [target]'s definition.