1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
|
---
title: Using session options
---
Session options are used to configure pyOCD. The [configuration]({% link _docs/configuration.md %}) documentation has user level documentation of how to set session options. For a full list of built-in options see the [session options reference]({% link _docs/options.md %}).
## Accessing options
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 `.get()`/`.set()` methods for reading and writing options.
```py
# 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'
```
Note that `.get()` does not take an optional second parameter for a default value if the session option is unset. Instead, this default value is determined from the session option's definition.
## Priority layers
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 derived from default values specified in the option definitions.
The priorities of the different sources, from front to back:
1. Keyword arguments to the `Session` constructor. Applies to most dedicated command-line arguments.
2. _options_ parameter to `Session` constructor. Applies to `-O` command-line arguments.
3. Options set by CMSIS-Toolbox Run and Debug Management (`cbuild-run`)
4. Probe-specific options from a config file.
5. Global options from a config file.
6. _option_defaults_ parameter to `Session` constructor. Used only in rare cases by subcommands to change the default value of options.
7. Default values from option definitions.
The `.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_front()` and `.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 `Session`.
## Name and value modifications
Several changes are applied to option names and values when they are set. First, the names are normalised.
1. 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.
2. 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 `OptionInfo` (from `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 `frequency` option:
```py
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 `BUILTIN_OPTIONS` list in `pyocd/core/options.py`
- Plugins can return a list of `OptionInfo` objects from the `.options` property of the `Plugin` subclass.
- Python scripts, including [user scripts]({% link _docs/user_scripts.md %}), can add new option definitions by calling `add_option_set()` (from `pyocd.core.options`) and passing a list of `OptionInfo` objects.
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 `OptionsManager`.
|
