| title |
|---|
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.
| Command | Arguments | Description |
|---|---|---|
| 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] | Reset the target. |
| 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. |
| 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. |
| write8, wb | ADDR DATA+ | Write 8-bit bytes to memory. |
| Registers | ||
| reg | [-f] [REG] | Print core or peripheral register(s). |
| wreg | [-r] 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. |
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 |
|---|---|---|
| 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. |
Usage: ADDR
Set a breakpoint address.
Usage:
List breakpoints.
Usage:
List watchpoints.
Usage: ADDR
Remove a breakpoint.
Usage: ADDR
Remove a watchpoint.
Usage: ADDR [r|w|rw] [1|2|4]
Set a watchpoint address, and optional access type (default rw) and size (4).
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.
Usage:
Init DP and power up debug.
Usage: APSEL
Creates a new AP object for the given APSEL. The type of AP, MEM-AP or generic, is autodetected.
Usage:
Reinitialize the target object.
Aliases: quit
Usage:
Quit pyocd commander.
Usage:
Show available targets.
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.
Usage: [NUM]
Select CPU core by number or print selected core.
Aliases: h
Usage:
Halt the target.
Aliases: s
Usage: [COUNT]
Step one or more instructions.
Aliases: rap
Usage: [APSEL] ADDR
Read AP register.
Aliases: rdp
Usage: ADDR
Read DP register.
Aliases: wap
Usage: [APSEL] ADDR DATA
Write AP register.
Aliases: wdp
Usage: ADDR DATA
Write DP register.
Usage: [halt|-halt|-h]
Reset the target.
Usage:
Unlock security on the target.
Aliases: ?
Usage: [CMD]
Show help for commands.
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.
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'.
Usage: [ADDR] [COUNT]
Erase all internal flash or a range of sectors.
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.
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.
Usage: FILENAME [ADDR]
Load a binary, hex, or elf file with optional base address.
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'.
Aliases: rh
Usage: ADDR [LEN]
Read 16-bit halfwords. Optional length parameter is the number of bytes to read. It must be divisible by 2. If the length is not provided, one halfword is read. The address may be unaligned.
Aliases: rw
Usage: ADDR [LEN]
Read 32-bit words. Optional length parameter is the number of bytes to read. It must be divisible by 4. If the length is not provided, one word is read. The address may be unaligned.
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.
Usage: ADDR LEN FILENAME
Save a range of memory to a binary file.
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.
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.
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.
Usage: [-f] [REG]
Print core or peripheral register(s). If no arguments are provided, all core registers 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. If the -f option is passed, then individual fields of peripheral registers will be printed in addition to the full value.
Usage: [-r] 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.
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.
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.
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.
These commands require an ELF to be set.
Usage: NAME
Show a symbol's value. An ELF file must have been specified with the --elf option.
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.
Aliases: st
Usage:
Show the target's current state.
Usage: {flush,enable,disable,status}
Control thread awareness.
Usage: NAME VALUE
Set a value.
Usage: NAME
Display a value.