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

CommandArgumentsDescription
Breakpoints
break ADDR Set a breakpoint address.
lsbreak List breakpoints.
lswatch List watchpoints.
rmbreak ADDR Remove a breakpoint.
rmwatch ADDR Remove a watchpoint.
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 [NUM] Select CPU core by number 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 specifying the reset type.
unlock Unlock security on the target.
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 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.
Openocd_compatibility
init 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.
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.
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.

ValueAccessDescription
aps read-only List discovered Access Ports.
cores read-only Information about CPU cores in the target.
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 value used by the selected MEM-AP.
hprot read-write The current HPROT 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.
probe-uid, uid read-only Target's unique ID.
register-groups read-only Display available register groups for the selected core.
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.

Commands

Breakpoints

break

Usage: ADDR
Set a breakpoint address.

lsbreak

Usage:
List breakpoints.

lswatch

Usage:
List watchpoints.

rmbreak

Usage: ADDR
Remove a breakpoint.

rmwatch

Usage: ADDR
Remove a watchpoint.

watch

Usage: 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:
Init DP and power up debug.

makeap

Usage: APSEL
Creates a new AP object for the given APSEL. The type of AP, MEM-AP or generic, is autodetected.

reinit

Usage:
Reinitialize the target object.

Commander

exit

Aliases: quit
Usage:
Quit pyocd commander.

list

Usage:
Show available targets.

Core

continue

Aliases: c, go, g
Usage:
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: [NUM]
Select CPU core by number or print selected core.

halt

Aliases: h
Usage:
Halt the target.

step

Aliases: s
Usage: [COUNT]
Step one or more instructions.

Dap

readap

Aliases: rap
Usage: [APSEL] ADDR
Read AP register.

readdp

Aliases: rdp
Usage: ADDR
Read DP register.

writeap

Aliases: wap
Usage: [APSEL] ADDR DATA
Write AP register.

writedp

Aliases: wdp
Usage: ADDR DATA
Write DP register.

Device

reset

Usage: [halt|-halt|-h] [TYPE]
Reset the target, optionally specifying the reset type. The reset type must be one of ‘default’, ‘hw’, ‘sw’, ‘hardware’, ‘software’, ‘sw_sysresetreq’, ‘sw_vectreset’, ‘sw_emulated’, ‘sysresetreq’, ‘vectreset’, or ‘emulated’.

unlock

Usage:
Unlock security on the target.

General

help

Aliases: ?
Usage: [CMD]
Show help for commands.

Memory

compare

Aliases: cmp
Usage: 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: [-c/–center] ADDR [LEN]
Disassemble instructions at an address. Only available if the capstone library is installed. To install capstone, run ‘pip install capstone’.

erase

Usage: [ADDR] [COUNT]
Erase all internal flash or a range of sectors.

fill

Usage: [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: 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.

load

Usage: FILENAME [ADDR]
Load a binary, hex, or elf file with optional base address.

loadmem

Usage: 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: 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: 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: 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: 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: ADDR LEN FILENAME
Save a range of memory to a binary file.

write16

Aliases: wh
Usage: 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: 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: 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: 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.

Openocd_compatibility

init

Usage: init
Ignored; for OpenOCD compatibility.

Probe

flushprobe

Usage:
Ensure all debug probe requests have been completed.

Registers

reg

Aliases: rr
Usage: [-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: [-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.

Semihosting

arm

Usage: 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: {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: {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: NAME
Show a symbol’s value. An ELF file must have been specified with the –elf option.

where

Usage: [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:
Show the target’s current state.

Threads

threads

Usage: {flush,enable,disable,status}
Control thread awareness.

Values

set

Usage: NAME VALUE
Set a value.

show

Usage: NAME
Display a value.