Command reference
PyOCD has a simple command processor that is accessible from the console via the commander subcommand, or from gdb as remote monitor commands.
The syntax for the commands is straightforward. The command line is first split into individual
commands separated by ; (semicolon). Each command is then split into words separated by
whitespace. The whitespace characters are space, tab, CR, and LF. Words can be quoted with either a
single or double quote to include whitespace (or quotes) in the word.
Any prefix of a command name is accepted as long as it is unique. If a command prefix is entered that ambiguous because it matches multiple commands, an error will be reported showing the matched command names. In addition, commonly used commands often have a short alias. The alias takes precedence even when it is a prefix of multiple other commands.
All commands
| Command | Arguments | Description |
|---|---|---|
| Breakpoints | ||
| break | ADDR | Set a breakpoint address. |
| lsbreak | List breakpoints. | |
| lswatch | List watchpoints. | |
| rmbreak | ADDR | Remove a breakpoint. |
| rmwatch | ADDR [r|w|rw] [1|2|4] | Remove watchpoint(s). |
| watch | ADDR [r|w|rw] [1|2|4] | Set a watchpoint address, and optional access type (default rw) and size (4). |
| Bringup | ||
| initdp | Init DP and power up debug. | |
| makeap | APSEL | Creates a new AP object for the given APSEL. |
| reinit | Reinitialize the target object. | |
| Commander | ||
| exit, quit | Quit pyocd commander. | |
| list | Show available targets. | |
| Core | ||
| continue, c, go, g | Resume execution of the target. | |
| core | [NUMBER | NAME] | Select CPU core by number or name, or print selected core. |
| halt, h | Halt the target. | |
| step, s | [COUNT] | Step one or more instructions. |
| Dap | ||
| readap, rap | [APSEL] ADDR | Read AP register. |
| readdp, rdp | ADDR | Read DP register. |
| writeap, wap | [APSEL] ADDR DATA | Write AP register. |
| writedp, wdp | ADDR DATA | Write DP register. |
| Device | ||
| reset | [halt|-halt|-h] [TYPE] | Reset the target, optionally with halt and/or specifying the reset type. |
| unlock | Unlock security on the target. | |
| Gdbserver | ||
| exit | Terminate running gdbservers in this session. | |
| General | ||
| help, ? | [CMD] | Show help for commands. |
| Memory | ||
| compare, cmp | ADDR [LEN] FILENAME | Compare a memory range against a binary file. |
| disasm, d | [-c/--center] ADDR [LEN] | Disassemble instructions at an address. |
| erase | [ADDR] [COUNT] | Erase all internal flash or a range of sectors. |
| fill | [SIZE] ADDR LEN PATTERN | Fill a range of memory with a pattern. |
| find | [-n] ADDR LEN BYTE+ | Search for a value in memory within the given address range. |
| load | FILENAME [ADDR] | Load a binary, hex, or elf file with optional base address. |
| loadmem | ADDR FILENAME | Load a binary file to an address in memory (RAM or flash). |
| read16, rh | ADDR [LEN] | Read 16-bit halfwords. |
| read32, rw | ADDR [LEN] | Read 32-bit words. |
| read64, rd | ADDR [LEN] | Read 64-bit words. |
| read8, rb | ADDR [LEN] | Read 8-bit bytes. |
| savemem | ADDR LEN FILENAME | Save a range of memory to a binary file. |
| write16, wh | ADDR DATA+ | Write 16-bit halfwords to memory. |
| write32, ww | ADDR DATA+ | Write 32-bit words to memory. |
| write64, wd | ADDR DATA... | Write 64-bit double-words to memory. |
| write8, wb | ADDR DATA+ | Write 8-bit bytes to memory. |
| Nrf91 | ||
| nrf91-update-modem-fw | [-f] mfw_nrf91xx_x.x.x.zip | Update modem firmware for an nRF91 target. |
| Openocd_compatibility | ||
| init | Ignored; for OpenOCD compatibility. | |
| Probe | ||
| flushprobe | Ensure all debug probe requests have been completed. | |
| Registers | ||
| reg, rr | [-p] [-f] [REG...] | Print core or peripheral register(s). |
| wreg, wr | [-r] [-p] [-f] REG VALUE | Set the value of a core or peripheral register. |
| Rtt | ||
| rtt | rtt {setup,start,stop,channels,server} | Control SEGGER RTT compatible interface. |
| Semihosting | ||
| arm | semihosting {enable,disable} | Enable or disable semihosting. |
| Servers | ||
| gdbserver | {start,stop,status} | Control the gdbserver for the selected core. |
| probeserver | {start,stop,status} | Control the debug probe server. |
| Symbols | ||
| symbol | NAME | Show a symbol's value. |
| where | [ADDR] | Show symbol, file, and line for address. |
| Target | ||
| status, st | Show the target's current state. | |
| Threads | ||
| threads | {flush,enable,disable,status} | Control thread awareness. |
| Utility | ||
| sleep | MILLISECONDS | Sleep for a number of milliseconds before continuing. |
| Values | ||
| set | NAME VALUE | Set a value. |
| show | NAME | Display a value. |
All values
Values represent a setting or piece of information that can be read and/or changed. They are accessed with
the show and set commands. The “Access” column of the table below shows whether the
command can be read, written, or both.
| Value | Access | Description |
|---|---|---|
| accessible-pins | read-write | Display which debug probe pins can be read and written with the 'pins' value. |
| aps | read-only | List discovered Access Ports. |
| cores | read-only | Information about CPU cores in the target. |
| debug-sequences | read-only | Show the available debug sequences from the target's DFP. |
| fault | read-only | Fault status information. |
| frequency | write-only | Set SWD or JTAG clock frequency in Hertz. |
| graph | read-only | Print the target object graph. |
| hnonsec | read-write | The current HNONSEC attribute value used by the selected MEM-AP. |
| hprot, memap_attr | read-write | The current memory transfer attributes value used by the selected MEM-AP. |
| locked | read-only | Report whether the target is locked. |
| log | write-only | Set log level to one of 'debug', 'info', 'warning', 'error', 'critical'. |
| map | read-only | Target memory map. |
| mem-ap | read-write | The currently selected MEM-AP used for memory read/write commands. |
| nreset | read-write | Current nRESET signal state. |
| option | read-write | The current value of one or more session options. |
| peripherals | read-only | List of target peripheral instances. |
| pins | read-write | Current debug probe protocol I/O pin states. |
| probe-uid, uid | read-only | Target's unique ID. |
| register-groups | read-only | Display available register groups for the selected core. |
| reset-type | read-write | Show reset configuration and all available reset types for each core. Set current reset type. |
| step-into-interrupts, si | read-write | Display whether interrupts are enabled when single stepping. |
| target | read-only | General target information. |
| vector-catch, vc | read-write | Show current vector catch settings. |
Command details
Breakpoints
break
Usage: break ADDR
Set a breakpoint address.
lsbreak
Usage: lsbreak
List breakpoints.
lswatch
Usage: lswatch
List watchpoints.
rmbreak
Usage: rmbreak ADDR
Remove a breakpoint.
rmwatch
Usage: rmwatch ADDR [r|w|rw] [1|2|4]
Remove watchpoint(s). Access type and size are optional. All watchpoints matching the specified parameters will be removed.
watch
Usage: watch ADDR [r|w|rw] [1|2|4]
Set a watchpoint address, and optional access type (default rw) and size (4).
Bringup
These commands are meant to be used when starting up Commander in no-init mode. They are primarily useful for low-level debugging of debug infrastructure on a new chip.
initdp
Usage: initdp
Init DP and power up debug.
makeap
Usage: makeap APSEL
Creates a new AP object for the given APSEL. The type of AP, MEM-AP or generic, is autodetected.
reinit
Usage: reinit
Reinitialize the target object.
Commander
exit
Aliases: quit
Usage: exit
Quit pyocd commander.
list
Usage: list
Show available targets.
Core
continue
Aliases: c, go, g
Usage: continue
Resume execution of the target. The target’s state is read back after resuming. If the target is not running, then it’s state is reported. For instance, if the target is halted immediately after resuming, a debug event such as a breakpoint most likely occurred.
core
Usage: core [NUMBER | NAME]
Select CPU core by number or name, or print selected core.
halt
Aliases: h
Usage: halt
Halt the target.
step
Aliases: s
Usage: step [COUNT]
Step one or more instructions.
Dap
readap
Aliases: rap
Usage: readap [APSEL] ADDR
Read AP register.
readdp
Aliases: rdp
Usage: readdp ADDR
Read DP register.
writeap
Aliases: wap
Usage: writeap [APSEL] ADDR DATA
Write AP register.
writedp
Aliases: wdp
Usage: writedp ADDR DATA
Write DP register.
Device
reset
Usage: reset [halt|-halt|-h] [TYPE]
Reset the target, optionally with halt and/or specifying the reset type. The reset type must be one of ‘default’, ‘hw’, ‘sw’, ‘hardware’, ‘software’, ‘system’, ‘core’, ‘emulated’, ‘sw_system’, ‘sw_core’, ‘sw_sysresetreq’, ‘sw_vectreset’, ‘sw_emulated’, ‘sysresetreq’, or ‘vectreset’.
unlock
Usage: unlock
Unlock security on the target.
Gdbserver
exit
Usage: exit
Terminate running gdbservers in this session. For the pyocd gdbserver subcommand, terminating gdbservers will cause the process to exit. The effect when the gdbserver(s) are running in a different environment depends on that program. Note that gdb will still believe the connection to be valid after this command completes, so executing the ‘disconnect’ command is a necessity.
General
help
Aliases: ?
Usage: help [CMD]
Show help for commands.
Memory
compare
Aliases: cmp
Usage: compare ADDR [LEN] FILENAME
Compare a memory range against a binary file. If the length is not provided, then the length of the file is used.
disasm
Aliases: d
Usage: disasm [-c/–center] ADDR [LEN]
Disassemble instructions at an address. The length argument is in bytes and is optional, with a default of 6. If the -c option is used, the disassembly is centered on the given address. Otherwise the disassembly begins at the given address.
erase
Usage: erase [ADDR] [COUNT]
Erase all internal flash or a range of sectors.
fill
Usage: fill [SIZE] ADDR LEN PATTERN
Fill a range of memory with a pattern. The optional SIZE parameter must be one of 8, 16, or 32. If not provided, the size is determined by the pattern value’s most significant set bit. Only RAM regions may be filled.
find
Usage: find [-n] ADDR LEN BYTE+
Search for a value in memory within the given address range. A pattern of any number of bytes can be searched for. Each BYTE parameter must be an 8-bit value. If the -n argument is passed, the search is negated and looks for the first set of bytes that does not match the provided values.
load
Usage: load FILENAME [ADDR]
Load a binary, hex, or elf file with optional base address.
loadmem
Usage: loadmem ADDR FILENAME
Load a binary file to an address in memory (RAM or flash). This command is deprecated in favour of the more flexible ‘load’.
read16
Aliases: rh
Usage: read16 ADDR [LEN]
Read 16-bit halfwords. Optional length parameter is the number of bytes (not half-words) to read. It must be divisible by 2. If the length is not provided, one halfword is read. The address may be unaligned.
read32
Aliases: rw
Usage: read32 ADDR [LEN]
Read 32-bit words. Optional length parameter is the number of bytes (not words) to read. It must be divisible by 4. If the length is not provided, one word is read. The address may be unaligned.
read64
Aliases: rd
Usage: read64 ADDR [LEN]
Read 64-bit words. Optional length parameter is the number of bytes (not double-words!) to read. It must be divisible by 8. If the length is not provided, one word is read. The address may be unaligned.
read8
Aliases: rb
Usage: read8 ADDR [LEN]
Read 8-bit bytes. Optional length parameter is the number of bytes to read. If the length is not provided, one byte is read.
savemem
Usage: savemem ADDR LEN FILENAME
Save a range of memory to a binary file.
write16
Aliases: wh
Usage: write16 ADDR DATA+
Write 16-bit halfwords to memory. The data arguments are 16-bit halfwords in big-endian format and are written as little-endian. The address may be unaligned. Can write to both RAM and flash. Flash writes are subject to minimum write size and alignment, and the flash page must have been previously erased.
write32
Aliases: ww
Usage: write32 ADDR DATA+
Write 32-bit words to memory. The data arguments are 32-bit words in big-endian format and are written as little-endian. The address may be unaligned. Can write to both RAM and flash. Flash writes are subject to minimum write size and alignment, and the flash page must have been previously erased.
write64
Aliases: wd
Usage: write64 ADDR DATA…
Write 64-bit double-words to memory. The data arguments are 64-bit words in big-endian format and are written as little-endian. The address may be unaligned. Can write to both RAM and flash. Flash writes are subject to minimum write size and alignment, and the flash page must have been previously erased.
write8
Aliases: wb
Usage: write8 ADDR DATA+
Write 8-bit bytes to memory. The data arguments are 8-bit bytes. Can write to both RAM and flash. Flash writes are subject to minimum write size and alignment, and the flash page must have been previously erased.
Nrf91
nrf91-update-modem-fw
Usage: nrf91-update-modem-fw [-f] mfw_nrf91xx_x.x.x.zip
Update modem firmware for an nRF91 target. If -f is specified, modem firmware is written to the device, even if the correct version is already present.
Openocd compatibility
init
Usage: init
Ignored; for OpenOCD compatibility.
Probe
flushprobe
Usage: flushprobe
Ensure all debug probe requests have been completed.
Registers
reg
Aliases: rr
Usage: reg [-p] [-f] [REG…]
Print core or peripheral register(s). If no arguments are provided, the ‘general’ core register group will be printed. Either a core register name, the name of a peripheral, or a peripheral.register can be provided. When a peripheral name is provided without a register, all registers in the peripheral will be printed. The -p option forces evaluating the register name as a peripheral register name. If the -f option is passed, then individual fields of peripheral registers will be printed in addition to the full value.
wreg
Aliases: wr
Usage: wreg [-r] [-p] [-f] REG VALUE
Set the value of a core or peripheral register. The REG parameter must be a core register name or a peripheral.register. When a peripheral register is written, if the -r option is passed then it is read back and the updated value printed. The -p option forces evaluating the register name as a peripheral register name. If the -f option is passed, then individual fields of peripheral registers will be printed in addition to the full value.
Rtt
rtt
Usage: rtt rtt {setup,start,stop,channels,server}
Control SEGGER RTT compatible interface.
Semihosting
arm
Usage: arm semihosting {enable,disable}
Enable or disable semihosting. Provided for compatibility with OpenOCD. The same functionality can be achieved by setting the ‘enable_semihosting’ session option.
Servers
gdbserver
Usage: gdbserver {start,stop,status}
Control the gdbserver for the selected core. The action argument should be either ‘start’, ‘stop’, or ‘status’. Use the ‘gdbserver_port’ and ‘telnet_port’ session options to control the ports the gdbserver uses.
probeserver
Usage: probeserver {start,stop,status}
Control the debug probe server. The action argument should be either ‘start’, ‘stop’, or ‘status. Use the ‘probeserver.port’ option to control the TCP port the server uses.
Symbols
These commands require an ELF to be set.
symbol
Usage: symbol NAME
Show a symbol’s value. An ELF file must have been specified with the –elf option.
where
Usage: where [ADDR]
Show symbol, file, and line for address. The symbol name, source file path, and line number are displayed for the specified address. If no address is given then current PC is used. An ELF file must have been specified with the –elf option.
Target
status
Aliases: st
Usage: status
Show the target’s current state.
Threads
threads
Usage: threads {flush,enable,disable,status}
Control thread awareness.
Utility
sleep
Usage: sleep MILLISECONDS
Sleep for a number of milliseconds before continuing.
Values
set
Usage: set NAME VALUE
Set a value.
show
Usage: show NAME
Display a value.
Value details
accessible-pins
Access: read-write
Usage: show accessible-pins, set accessible-pins VALUE
Display which debug probe pins can be read and written with the ‘pins’ value.
aps
Access: read-only
Usage: show aps
List discovered Access Ports.
cores
Access: read-only
Usage: show cores
Information about CPU cores in the target.
debug-sequences
Access: read-only
Usage: show debug-sequences
Show the available debug sequences from the target’s DFP. Only available for CMSIS-Pack based targets.
fault
Access: read-only
Usage: show fault
Fault status information. By default, only asserted fields are shown. Add -a to command to show all fields.
frequency
Access: write-only
Usage: set frequency VALUE
Set SWD or JTAG clock frequency in Hertz. A case-insensitive metric scale suffix of either ‘k’ or ‘m’ is allowed, as well as a trailing “Hz”. There must be no space between the frequency and the suffix. For example, “2.5MHz” sets the clock to 2.5 MHz.
graph
Access: read-only
Usage: show graph
Print the target object graph.
hnonsec
Access: read-write
Usage: show hnonsec, set hnonsec VALUE
The current HNONSEC attribute value used by the selected MEM-AP. This value controls whether memory transactions are secure or nonsecure. The value is an integer, either 0 or secure or 1 for nonsecure.
hprot
Aliases: memap_attr
Access: read-write
Usage: show hprot, set hprot VALUE
The current memory transfer attributes value used by the selected MEM-AP. This integer value controls attributes of memory transfers. It is a direct mapping of the AHB
or AXI attribute settings, depending on the type of MEM-AP. For AHB-APs, the value is HPROT[4:0].
For AXI-APs, the value is {AxPROT[2:0}, AxCACHE[3:0]}, e.g. AxPROT in bits 6-4 and AxCACHE in
its 3-0. Not all MEM-AP implementations support all attributes. See the Arm Technical Reference
Manual for your device’s MEM-AP for details.
locked
Access: read-only
Usage: show locked
Report whether the target is locked.
log
Access: write-only
Usage: set log VALUE
Set log level to one of ‘debug’, ‘info’, ‘warning’, ‘error’, ‘critical’. If pyocd module names are provided as arguments after the log level then only those modules will have their log level changed.
map
Access: read-only
Usage: show map
Target memory map.
mem-ap
Access: read-write
Usage: show mem-ap, set mem-ap VALUE
The currently selected MEM-AP used for memory read/write commands. When the selected core is changed by the ‘core’ command, the selected MEM-AP is changed to match. This overrides a user-selected MEM-AP if different from the AP for the newly selected core.
nreset
Access: read-write
Usage: show nreset, set nreset VALUE
Current nRESET signal state. Accepts a value of 0 or 1.
option
Access: read-write
Usage: show option, set option VALUE
The current value of one or more session options. When setting, each argument should follow the form “NAME[=VALUE]”.
peripherals
Access: read-only
Usage: show peripherals
List of target peripheral instances.
pins
Access: read-write
Usage: show pins, set pins VALUE
Current debug probe protocol I/O pin states. The pins value is a mask containing the state of all accessible protocol pins. See the accessible-pins value for protocol pins that can be read and written by the connected debug probe.
probe-uid
Aliases: uid
Access: read-only
Usage: show probe-uid
Target’s unique ID.
register-groups
Access: read-only
Usage: show register-groups
Display available register groups for the selected core.
reset-type
Access: read-write
Usage: show reset-type, set reset-type VALUE
Show reset configuration and all available reset types for each core. Set current reset type.
step-into-interrupts
Aliases: si
Access: read-write
Usage: show step-into-interrupts, set step-into-interrupts VALUE
Display whether interrupts are enabled when single stepping. Set to 1 to enable.
target
Access: read-only
Usage: show target
General target information.
vector-catch
Aliases: vc
Access: read-write
Usage: show vector-catch, set vector-catch VALUE
Show current vector catch settings. When setting, the alue is a concatenation of one letter per enabled source in any order, or ‘all’ or ‘none’. (h=hard fault, b=bus fault, m=mem fault, i=irq err, s=state err, c=check err, p=nocp, r=reset, a=all, n=none).