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

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 [NUM]
Select CPU core by number 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 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
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.

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.

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.

Values

set

Usage: set NAME VALUE
Set a value.

show

Usage: show NAME
Display a value.

Value details

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.

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.

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.

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).