pyOCD Documentation

To effectively use pyOCD, it is helpful to understand its core terminology regarding debug hardware, protocols, and software abstractions:

Hardware and Connectivity

• debug probe: The hardware device (usually USB-connected) that drives the wire protocol.
• debug link: The physical connection between the debugger and the target.
• target: The device being controlled by pyOCD.
• SoC (System on Chip): The complete computer on a single chip (e.g., a microcontroller).
• unique ID: The identifier for a debug probe, typically its serial number.

Protocols and Architecture

• wire protocol: The communication standard used on the debug link, typically JTAG or SWD (Serial Wire Debug).
• SWO (Serial Wire Output): A single-pin output for SWV frames, accessible only when using SWD.
• SWV (Serial Wire Viewer): A trace capability for monitoring reads, writes, exceptions, PC samples, and printf.
• ADI (Arm Debug Interface): The Arm specification for how JTAG/SWD interfaces with CoreSight.
• DAP (Debug Access Port): The debugging module accessed via JTAG/SWD, composed of a DP (Debug Port) and one or more APs (Access Ports).
• MEM-AP: A standard type of AP used for memory reads and writes (e.g., AHB-AP, AXI-AP).

pyOCD Software Concepts

• commander: The pyocd commander subcommand providing an interactive REPL for exploring the target.
• command: An instruction executed in the commander REPL or as a GDB monitor command.
• session: The representation of a connection to a debug probe and the resulting runtime object graph.
• session option: A named setting (set via CLI or config files) that controls pyOCD features for a specific session.
• target type: The identifier (full part number or shortened form) for the target device.
• flash algorithm: Code downloaded to target RAM to perform flash erase and program operations.
• gdbserver: A server implementing the GDB Remote Serial Protocol (RSP) that allows pyOCD to act as a bridge between GDB and the target.
• user script: A Python script loaded at runtime to extend/modify pyOCD behavior while the pyocd CLI tool is running.

User scripts can define functions that act as hooks at specific points in the connection lifecycle. Common hooks include:

• will_connect(board): Called before the connection is established. The board object is provided as an argument.
• did_connect(): Called after the connection is established. Note that board is not necessarily passed to this hook.

Example: Adding a ROM region (Nordic nRF52)

def will_connect(board):
    # Create the new ROM region for the FICR.
    ficr = RomRegion(
                name="ficr",
                start=0x10000000,
                length=0x460
                )

    # Add the FICR region to the memory map.
    target.memory_map.add_region(ficr)

Example: Overriding a flash algorithm (NXP i.MX RT10x0)

def will_connect():
    # Look up the external flash memory region.
    extFlash = target.memory_map.get_first_matching_region(name="flexspi")

    # Set the path to an .FLM flash algorithm.
    extFlash.flm = "MIMXRT105x_QuadSPI_4KB_SEC.FLM"

Example: Writing to a register after connection (STM32L0x1)

DBG_CR = 0x40015804

def did_connect():
    # Set STANDBY, STOP, and SLEEP bits all to 1.
    target.write32(DBG_CR, 0x7)

# This example applies to the Nordic nRF52 devices.

def will_connect(board):
    # Create the new ROM region for the FICR.
    ficr = RomRegion(
                name="ficr",
                start=0x10000000,
                length=0x460
                )

    # Add the FICR region to the memory map.
    target.memory_map.add_region(ficr)

The pyOCD Python API is structured around a hierarchical object graph. The entry point for any interaction is the Session object, which manages the lifecycle of the debug probe and the board, as well as per-session configuration options.

Key components include:

• Session: The root object holding references to the debug probe and the board.
• Board: Attached to the session; represents the physical hardware setup.
• CoreSightTarget: Represents the MCU and is attached to the board. It manages communication via Debug Ports (DP) and Access Ports (AP).
• CortexM: A subclass of Target representing a specific CPU core on the device. It is owned by the CoreSightTarget.
• Target: An abstract base class for both CoreSightTarget and CortexM.
• MemoryRegion: Objects within a CortexM memory map that define address ranges.
• Flash: An object associated with flash MemoryRegion objects used to control flash programming.

pyOCD uses a layered priority system for session options. When multiple sources define the same option, the value from the highest priority layer (the "front") is used. The OptionsManager manages these layers as an ordered sequence.

Priority Order (from highest to lowest priority):

1. Keyword arguments passed to the Session constructor (typically dedicated CLI arguments).
2. _options_ parameter passed to the Session constructor (typically -O CLI arguments).
3. Options set by CMSIS-Toolbox Run and Debug Management (cbuild-run).
4. Probe-specific options from a config file.
5. Global options from a config file.
6. _option_defaults_ parameter passed to the Session constructor.
7. Default values defined in the option definitions.

Layer Manipulation:

• .set(name, value): Modifies the value in the highest priority layer.
• .add_front(dict): Adds a new dictionary of options to the front (highest priority).
• .add_back(dict): Adds a new dictionary of options to the back (lower priority).