Session options list

Note: The names of these options are expected to change before the 1.0 release of pyOCD, so they will be better normalized and grouped.

General options

Note that the project_dir, no_config, and config options must come from either a keyword argument or the options parameter passed to the Session constructor due to how early they are processed. The consequence of this is that these options cannot be set in a YAML config file.

Option NameTypeDefaultDescription
adi.v5.max_invalid_ap_count int 3 If this number of invalid APs is found in a row, then AP scanning will stop. The 'scan_all_aps' option takes precedence over this option if set.
allow_no_cores bool False Prevents raising an error if no core were found after CoreSight discovery.
auto_unlock bool True If the target is locked, it will by default be automatically mass erased in order to gain debug access. Set this option to False to disable auto unlock.
cache.read_code_from_elf bool True Controls whether reads of code sections will be taken from an attached ELF file instead of the target memory. This can improve performance, especially over slow target connections. Requires an ELF file to be set.
chip_erase str 'sector' Whether to perform a chip erase or sector erases when programming flash. The value must be one of 'auto', 'sector', or 'chip'.
cmsis_dap.prefer_v1 bool False If a device provides both CMSIS-DAP v1 and v2 interfaces, use the v1 interface in preference of v2. Normal behaviour is to prefer the v2 interface. This option is primarily intended for testing.
commander.history_length int 1000 Number of entries in the pyOCD Commander command history. Set to -1 for unlimited.
config_file str See description Relative path to a YAML config file that lets you specify session options either globally or per probe. The format of the file is documented above. The default is a pyocd.yaml or pyocd.yml file in the working directory.
connect_mode str 'halt' Controls how pyOCD connects to the target. One of 'halt', 'pre-reset', 'under-reset', 'attach'.
  • 'halt': immediately halt all accessible cores upon connect.
  • 'pre-reset': perform a hardware reset prior to connect and halt.
  • 'under-reset': assert hardware reset during the connect sequence, then deassert after the cores are halted. This connect mode is often necessary to gain control of a target that is in a deep low power mode.
  • 'attach': connect to a running target without halting cores.
cpu.step.instruction.timeout float 0.0

Timeout in seconds for instruction step operations. The default of 0 means no timeout.

Note that stepping may take a very long time for to return in cases such as stepping over a branch into the Secure world where the debugger doesn't have secure debug access, or similar for Privileged code in the case of UDE.

dap_protocol str 'default' Wire protocol, either 'swd', 'jtag', or 'default'.
dap_swj_enable bool True Send SWJ transition sequence to switch between SWD and JTAG.
dap_swj_use_dormant bool False When switching between SWD and JTAG, use the SWJ sequence added in ADIv5.2 that transitions through a new dormant state. Requires a SWJ-DPv2. Note that if the connection attempt fails using the deprecated sequence (when this option is disabled), then pyOCD will automatically attempt to use the new sequence. This option simply skips the deprecated sequence in case it causes problems or it is known that dormant state is required for the target.
debug.log_flm_info bool False Log details of loaded .FLM flash algos.
debug.traceback bool True Print tracebacks for exceptions.
enable_multicore_debug bool False Whether to put pyOCD into multicore debug mode. The primary effect is to modify the default software reset type for secondary cores to use VECTRESET, which will fall back to emulated reset if the secondary core is not v7-M.
fast_program bool False Setting this option to True will use CRC checks of existing flash sector contents to determine whether pages need to be programmed.
flash.timeout.init float 5.0 Flash algorithm init and uninit timeout in seconds.
flash.timeout.analyzer float 30.0 Flash CRC analyzer timeout in seconds.
flash.timeout.erase_all float 240.0 Flash algorithm erase all timeout in seconds.
flash.timeout.erase_sector float 10.0 Flash algorithm sector erase timeout in seconds.
flash.timeout.program float 10.0 Flash algorithm programming timeout in seconds.
frequency int 1000000 (1 MHz) SWD/JTAG frequency in Hertz.
hide_programming_progress bool False Disables flash programming progress bar when True.
keep_unwritten bool False Whether to preserve existing flash content for ranges of sectors that will be erased but not written with new data.
logging str, dict No default Either a dictionary with logging configuration, or a path to a separate yaml logging configuration file. See the logging configuration documentation for details of how to use this option.
no_config bool False Do not use default config file.
pack str, list of str No default Path or list of paths to CMSIS Device Family Packs. Devices defined in the pack(s) are added to the list of available targets.
probeserver.port int 5555 TCP port for the debug probe server.
project_dir str See description Path to the session's project directory. Defaults to the working directory when the pyocd tool was executed.
reset_type str 'sw' Which type of reset to use by default (one of 'default', 'hw', 'sw', 'sw_sysresetreq', 'sw_vectreset', 'sw_emulated').
reset.hold_time float 0.1 Number of seconds to hold hardware reset asserted.
reset.post_delay float 0.1 Number of seconds to delay after a reset is issued.
reset.dap_recover.timeout float 5.0 Timeout for waiting for the DAP to be accessible after reset, in seconds. If the timeout lapses, an attempt will be made to reconnect the DP and retry.
reset.core_recover.timeout float 2.0 Timeout in seconds for waiting for a core to be accessible after reset. A warning is printed if the timeout lapses. Set to 0 to disable the core accessibility test. For halting reset, this is also the timeout for waiting for the core to halt.
reset.halt_timeout float 2.0 Timeout in seconds for waiting for the core to halt after a reset and halt.
resume_on_disconnect bool True Whether to resume a halted target when disconnecting.
scan_all_aps bool False Controls whether all 256 ADIv5 AP addresses will be probed.
serve_local_only bool True When this option is True, the GDB server, probe server, semihosting telnet, and raw SWV server are only served on localhost, making them inaccessible across the network. Set to False to enable connecting to these ports from any machine on the network.
smart_flash bool True If set to True, the flash loader will attempt to not program pages whose contents are not going to change by scanning target flash memory. A value of False will force all pages to be erased and programmed.
target_override str No default Target type name to use instead of default board target or default cortex_m.
test_binary str No default Specify the test binary file name used by the functional test suite (in the test/ directory). The binary must be in the binaries/ directory. This option is most useful when set in a board config file for running the functional tests on boards that cannot be automatically detected.
user_script str No default Path of the user script file.
warning.cortex_m_default bool True Whether to show the warning when no target type is selected and the default cortex_m target type is used. The warning is never shown if the cortex_m target type is explicitly specified.

GDB server options

These session options are currently only applied when running the GDB server.

Option NameTypeDefaultDescription
enable_semihosting bool False Set to True to handle semihosting requests. Also see the semihost_console_type option.
enable_swv bool False Whether to enable SWV printf output over the semihosting console. Requires the swv_system_clock option to be set. The SWO baud rate can be controlled with the swv_clock option.
debug.status_fault_retry_timeout float 1 Duration in seconds that a failed target status check will be retried before an error is raised. Only applies while the target is running after a resume operation in the debugger and pyOCD is waiting for it to halt again.
gdbserver_port int 3333 Base TCP port for the gdbserver. The core number, which is 0 for the primary core, will be added to this value.
persist bool False If True, the GDB server will not exit after GDB disconnects.
report_core_number bool False Whether gdb server should report core number as part of the per-thread information.
rtos.enable bool True Overall enable flag for RTOS aware debugging. By default it's enabled but can be switched off if necessary. str No default Name of the RTOS plugin to use. If not set, all RTOS plugins are given a chance to load.
semihost_console_type str 'telnet' If set to 'telnet' then the semihosting telnet server will be started. If set to 'console' then semihosting will print to the console.
semihost_use_syscalls bool False Whether to use GDB syscalls for semihosting file access operations, or to have pyOCD perform the operations. This is most useful if GDB is running on a remote system.
step_into_interrupt bool False Set this option to True to enable interrupts when performing step operations. Otherwise interrupts will be disabled and step operations cannot be interrupted.
swv_clock int 1000000 (1 MHz) Frequency in Hertz of the SWO baud rate.
swv_system_clock int No default Frequency in Hertz of the target's system clock. Used to compute the SWO baud rate divider.
swv_raw_enable bool True Enable flag for the raw SWV stream server.
swv_raw_port int 3443 TCP port number for the raw SWV stream server.
telnet_port int 4444 Base TCP port number for the semihosting telnet server. The core number, which will be 0 for the primary core, is added to this value.
vector_catch str 'h' Enable vector catch sources, one letter per enabled source in any order, or all or none. The source letters are: - h=hard fault - b=bus fault - m=mem fault - e=secure fault - i=irq err - s=state err - c=check err - p=nocp - r=reset - a=all - n=none
xpsr_control_fields bool False When set to True, XPSR and CONTROL registers will have their respective bitfields defined for presentation in gdb.

CMSIS-DAP probe options

These session options are available when the CMSIS-DAP debug probe plugin is active.

Option NameTypeDefaultDescription
cmsis_dap.deferred_transfers bool True Whether to use deferred transfers in the CMSIS-DAP probe backend. By disabling deferred transfers, all writes take effect immediately. However, performance is negatively affected.
cmsis_dap.limit_packets bool False Restrict CMSIS-DAP backend to using a single in-flight command at a time. This is useful on some systems where USB is problematic, in particular virtual machines.

These session options are available when the SEGGER J-Link debug probe plugin is active.

Option NameTypeDefaultDescription
jlink.device str No default If this option is set to a supported J-Link device name, then the J-Link will be asked connect using this name. Otherwise, when unset, the J-Link is configured for only the low-level CoreSight operations required by pyOCD. Ordinarily, it does not need to be set.
jlink.non_interactive bool True Controls whether the J-Link DLL is allowed to present UI dialog boxes and its control panel. Note that dialog boxes will actually still be visible, but the default option will be chosen automatically after 5 seconds. Note: This has the effect of also silencing dialog boxes that appear when updating firmware / to confirm updating firmware.
jlink.power bool True Enable target power when connecting via a JLink probe, and disable power when disconnecting. Default is True.

Picoprobe options

These session options are available when the Picoprobe debug probe plugin is active.

Option NameTypeDefaultDescription
picoprobe.safeswd bool False Use safer but slower SWD transfer function with Picoprobe. Default is False, so possible WAIT or FAULT SWD acknowldeges and protocol errors will not be caught immediately.

These session options are available when the STLink debug probe plugin is active.

Option NameTypeDefaultDescription
stlink.v3_prescaler int 1 Sets the HCLK prescaler of an STLinkV3, changing performance versus power tradeoff. The value must be one of 1=high performance (default), 2=normal, or 4=low power.