Using session options
Session options are used to configure pyOCD. The configuration documentation has user level documentation of how to set session options. For a full list of built-in options see the session options reference.
Options are quite easy to use from within Python code. The
Session object has an
options property which returns a dict-like
OptionsManager object that is used to access options for that session. The
OptionsManager object supports either slicing or
.set() methods for reading and writing options.
# Reading an option from the session using two techniques. value = session.options['reset_type'] value = session.options.get('reset_type') # Changing the value of an option session.options['reset_type'] = 'system' session.options.set('reset_type') = 'system'
Session options have a priority based on their source. The
OptionsManager class implements these priorities as an ordered sequence of layers from front (high priority) to back (low priority). Each layer is a dict of option name to value. There is also an implicit lowest-priority layer from which default values specified in the option definition are derived.
The priorities of the different sources, from front to back:
- Keyword arguments to the
Sessionconstructor. Applies to most command-line arguments.
- options parameter to
Sessionconstructor. Applies to
- Probe-specific options from a config file.
- Global options from a config file.
- option_defaults parameter to
Sessionconstructor. Used only in rare cases by subcommands to change the default value of options.
- Default values from option definitions.
.set() method simply modifies the value of the highest priority (aka front) copy of the option. Additional layers can be added to the front or back using the
.add_back() methods. These methods take a dict of new option values.
How options are configured
Loading of options from YAML files is handled automatically when the
Session object is created. Probe-specific options are automatically set, too.
Options set through command line arguments, both dedicated arguments and
-O, are passed into the
Session constructor and added as their own layer. The
ConnectHelper methods that are most often used to create sessions will pass through options related arguments to
Name and value modifications
Several changes are applied to option names and values when they are set. First, the names are normalised.
- Convert all occurrences of double-underscores to a dot, e.g.,
__changes to a
.character. Doing this makes it possible to set options with dots in the name using keyword arguments.
- Change to lower case.
Then, any option set with a value of
None is ignored. In that case, the option’s value from a lower priority layer will take precedence.
Adding new options
Session options are defined by an instance of
pyocd.core.options) that specifies the name, type(s), default value, and a help string. At runtime, the complete set of options is in the
pyocd.core.options.OPTIONS_INFO dict. Be sure to define any new options so they’re documented and get a default and help text.
For example, this is the definition of the
OptionInfo('frequency', int, 1000000, "SWD/JTAG frequency in Hertz.")
There are several places to define a new option.
- Global and gdb server options should be added to the
- Plugins can return a list of
OptionInfoobjects from the
.optionsproperty of the
- Python scripts, including user scripts, can add new option definitions by calling
pyocd.core.options) and passing a list of
Supported types for options are bool, int, float, and str. An option that allows multiple types is specified with a tuple of those types. The
convert_session_options() function from
pyocd.utility.cmdline will convert the bool, int, and float options from a string value. However, there is not automatic type conversion when setting options directly on the