pyOCD Debugger

The CMSIS-Toolbox provides a structure for debugger projects and their configuration options. This chapter describes how to use the pyOCD Debugger with the CMSIS-Toolbox.

  • Extended Options explains additional configuration features that are required in specific use-cases.
  • Command Line Invocation describes how to call pyOCD directly from the command-line.
  • cbuild-run: explains the configuration file that describes the overall pyOCD system setup.

Other manual sections describe how to configure debuggers:

Extended Options

The section CSolution Project Format - pyOCD contains the pyOCD configuration for typical systems.

Extended YML options are required to configure specific use-cases or overwrite information that is typically provided in the DFP.

CMSIS-DAP based Debug Adapters implement debug access sequences that are configured in the DFP for a device.

connect:

Configures the behavior for connecting pyOCD to the hardware target.

  Description
connect: Optional Selects the connect mode: pre-reset, under-reset, attach (default), halt.
Connect Mode Description
pre-reset Apply a hardware reset before connect. Sequence: ResetHardware.
under-reset Asserts a hardware reset during connect and deasserts after core(s) are halted. Sequence: ResetHardwareAssert, ResetHardwareDeassert.
attach Do not change status of the core(s).
halt Halt core(s) after connect.

reset:

Configures the reset behavior for each core when a reset is requested.

reset: Description
- pname: Optional Identifies the processor (not required for single core system).
    type: Required Selects the reset type: hardware, system, core. Default: specified in DFP.
Reset Types Description
hardware Use a system-wide reset via dedicated debugger reset line. Sequence: ResetHardware.
system Use a system-wide reset via software mechanism. Sequence: ResetSystem.
core Use a processor reset via software mechanism. Sequence: ResetProcessor

Note

The defaultResetSequence in DFP element /package/devices/family/.../debug can define a different default reset type. If no defaultResetSequence, the default reset type is system.

load-setup:

Configures the debug sequences executed during the load command of pyOCD.

load-setup: Description
    halt: Optional Halt core(s) before load: on (default), off.
    pre-reset: Optional Reset type before loading: off, hardware, system, core. Default: specified in DFP or defined with reset.
    post-reset: Optional Reset type after loading: off, hardware (default), system, core.

Examples:

debugger:
  name: CMSIS-DAP@pyOCD     # default connect, halt and reset behavior

debugger:
  name: CMSIS-DAP@pyOCD
  connect: under-reset      # connect under hardware reset
  reset:
    - type: system          # use system reset
  load-setup:
    halt: on                # halt core(s) before load
    post-reset: hardware    # use hardware reset after load

debugger:
  name: CMSIS-DAP@pyOCD
  connect: pre-reset        # apply hardware reset before connect
  reset:
    - pname: Core0          # for Core0
      type: hardware        # use hardware reset
    - pname: Core1          # for Core1
      type: system          # use system reset
  load-setup:
    pre-reset: system       # use system reset before load
    post-reset: off         # no reset after load

trace:

Note

The trace: feature will be implemented in the future. This section is only a preview.

CMSIS-DAP supports the SWO trace output of Cortex-M devices. The device-specific trace features are configured using the *.dbgconf file.

The default trace output file and location is derived from the cbuild-run.yml file and uses the extension <pname>.txt, format: <solution-name>+<target-type>.trace

trace: Description
    mode: Required Trace: off (default), server, file.
    clock: Required Trace clock frequency in Hz.
    port-type: Optional Set Trace Port transport mode. Currently only SWO-UART is accepted.
    baudrate: Optional Maximum baudrate for SWO-UART mode.
    port: Optional Set TCP/IP port number of Trace server (default: 5555).
    file: Optional Explicit path and name of the trace output file. Default: <solution-name>+<target-type>.trace.

Command Line Invocation

The CMSIS-Toolbox debugger configuration is provided in the file *.cbuild-run.yml. Use the following command line syntax to leverage this information:

>pyOCD <command> --cbuild-run <cbuild-run.yml file> [options]
<command> Description
gdbserver Start GDB server(s).
run Execute application.
erase Erase device.
load Load image to device.
reset Reset device.

gdbserver

Start GDB servers for each target device core, used for debugging the applications.

<options> Description
--semihosting Enable semihosting (default disabled).
--persist Keep GDB server running even after remote has detached (default disabled).
--probe <uid> Select specific debug probe (also: --uid).
--reset-run Reset and run before running GDB server.

Example:

pyocd gdbserver --probe cmsisdap: --persist --reset-run --semihosting --cbuild-run out/DualCore+Alif-AppKit-E7.cbuild-run.yml

run

Run the target until timelimit is reached or an EOT (0x04) character is detected on stdout.

<options> Description
--timelimit <sec> Maximum execution time in seconds before terminating (default no time limit).
--eot Terminate execution when EOT character (0x04) is detected on stdout (default disabled).
--probe <id> Select a specific debug probe (also: --uid).

Example:

pyocd run --cbuild-run out/DualCore+Alif-AppKit-E7.cbuild-run.yml --eot --timelimit 30

erase

Erase target using chip erase.

<options> Description
--chip Perform a chip erase.

Example:

pyocd erase --chip --cbuild-run out/DualCore+Alif-AppKit-E7.cbuild-run.yml

load

Program target with images listed under the output node.

Example:

pyocd load --cbuild-run out/DualCore+Alif-AppKit-E7.cbuild-run.yml

reset

Reset target using selected reset type.

Example

pyocd reset --cbuild-run out/DualCore+Alif-AppKit-E7.cbuild-run.yml

Content of cbuild-run.yml

This section details the content of cbuild-run.yml file and how it is used to configure pyOCD. The cbuild-run.yml file is generated by the CMSIS-Toolbox from the information provided in the csolution project. However, it is possible to create a *.cbuild-run.yml file manually and the following section explains the file structure.

cbuild-run:

The cbuild-run: node is the start of a *.cbuild-run.yml file. The table below is an excerpt of the File Structure of *.cbuild-run.yml

cbuild-run: Content
    device: Optional Identifies the device.
    device-pack: Optional Identifies the device pack used.
    board-pack: Optional Identifies the board pack used.
    output: Optional Lists the images (ELF, HEX, BIN) in this solution.
    system-resources: Optional Lists target system resources.
    system-descriptions: Optional Lists target's description files for peripherals and software components.
    programming: Optional Lists flash algorithms for programming.
    debugger: Optional Configures the debugger.
    debug-vars: Optional Debug variables.
    debug-sequences: Optional Debug sequences.
    debug-topology: Optional Debug topology.

device:

pyOCD uses the device node to name the target in the current debug session. The node value is structured as [<vendor>::]<device>[:<pname>], where only the <device> part is used to name the target. The default value is an empty string.

Example:

  device: Alif Semiconductor::AE722F80F55D5LS

device-pack:

The device-pack (DFP) improves pyOCD's error reporting when a required file is provided by the device pack.

Example:

  device-pack: AlifSemiconductor::Ensemble@2.0.4

board-pack:

The board-pack (BSP) improves pyOCD's error reporting when a required file is provided by the board pack.

Example:

  board-pack: AlifSemiconductor::Ensemble@2.0.4

output:

pyOCD uses the information from the output node to determine which images need to be loaded into the device's flash memory and at what addresses. The image file type is determined by the type node, and the load offset for binary image files is provided by the load-offset node. Only files with image in the load: node are programmed to the device.

output: Content
- file: Required Specifies the file name.
    type: Required Specifies the file type.
    info: Optional Brief description of the file.
    load: Required Load mode of the image file for programmers and debug tools.
    load-offset: Optional Offset applied in *.csolution.yml when loading the binary image file.
    pname: Optional Image belongs to processor in a multi-core system.

Example:

  output:
    - file: M55_HP/Alif-AppKit-E7/Debug/M55_HP.axf
      info: generate by M55_HP.Debug+Alif-AppKit-E7
      type: elf
      load: image+symbols
      pname: M55_HP
    - file: M55_HE/Alif-AppKit-E7/Debug/M55_HE.axf
      info: generate by M55_HE.Debug+Alif-AppKit-E7
      type: elf
      load: symbols
      pname: M55_HE
    - file: M55_HE/Alif-AppKit-E7/Debug/M55_HE.hex
      info: generate by M55_HE.Debug+Alif-AppKit-E7
      type: hex
      load: image
      pname: M55_HE
    - file: M55_HE/Alif-AppKit-E7/Debug/M55_HE.bin
      info: generate by M55_HE.Debug+Alif-AppKit-E7
      type: bin
      load: none
      pname: M55_HE

system-resources:

Contains a list of memory regions that pyOCD uses to build the device memory map. If no memory regions are provided, pyOCD will fall back to a default Cortex-M memory map.

system-resources: Content
    memory: Optional Identifies the section for memory.
memory: Content
- name: Required Name of the memory region (when PDSC contains id, it uses the id as name).
    access: Required Access attribute string for the memory (see access: table here).
    start: Required Base address of the memory.
    size: Required Size of the memory.
    pname: Optional Only accessible by a specific processor.
    alias: Optional Name of identical memory exposed at a different address.

Example:

  system-resources:
    memory:
      - name: ITCM_HE
        access: rwx
        start: 0x00000000
        size: 0x00040000
        pname: M55_HE
        alias: SRAM4
      - name: ITCM_HP
        access: rwx
        start: 0x00000000
        size: 0x00040000
        pname: M55_HP
        alias: SRAM2
      - name: MRAM
        access: rx
        start: 0x80000000
        size: 0x00580000
      - name: SRAM2
        access: rwx
        start: 0x50000000
        size: 0x00040000
      - name: SRAM4
        access: rwx
        start: 0x58000000
        size: 0x00040000

system-descriptions:

Contains a list of system description files for the target's peripherals and software components. The svd files are processed by pyOCD to present debug views and decode register reads/writes.

system-descriptions: Content
- file: Required Specifies the file name including the path.
    type: Required Specifies the file type (see table below).
    info: Optional Brief description of the file.
    pname: Optional File is used only for a specific processor; default is for all processors.
type: Description
svd System View Description (*.svd) file specified in the DFP.

Note

Currently pyOCD has a limitation of only processing the svd file for the processor listed in start-pname.

Example:

  system-descriptions:
    - file: ${CMSIS_PACK_ROOT}/AlifSemiconductor/Ensemble/2.0.4/Debug/SVD/AE722F80F55D5LS_CM55_HE_View.svd
      type: svd
      pname: M55_HE
    - file: ${CMSIS_PACK_ROOT}/AlifSemiconductor/Ensemble/2.0.4/Debug/SVD/AE722F80F55D5LS_CM55_HP_View.svd
      type: svd
      pname: M55_HP

programming:

Contains a list of the target's flash programming algorithms. pyOCD uses these algorithms to identify which memory regions should be treated as flash, and it will automatically select the appropriate algorithm when programming flash on the target.

programming: Content
- algorithm: Required Programming algorithm file including the path.
    start: Required Start address of memory covered by the programming algorithm.
    size: Required Size of memory covered by the programming algorithm.
    ram-start: Required Start address of RAM where the algorithm will be executed from.
    ram-size: Required Maximum size of RAM available for executing the programming algorithm.
    pname: Optional Specifies the processor for the execution of the algorithm.

Example:

  programming:
    - algorithm: ${CMSIS_PACK_ROOT}/AlifSemiconductor/Ensemble/2.0.4/Flash/algorithms/Ensemble.FLM
      start: 0x80000000
      size: 0x00580000
      ram-start: 0x00000000
      ram-size: 0x00020000
    - algorithm: ${CMSIS_PACK_ROOT}/AlifSemiconductor/Ensemble/2.0.4/Flash/algorithms/Ensemble_IS25WX256.FLM
      start: 0xC0000000
      size: 0x02000000
      ram-start: 0x00000000
      ram-size: 0x00040000

debugger:

Contains the user's debugger configuration settings. The available options are described in detail in the CSolution Project Format section Debugger Configuration - pyOCD.

Example:

  debugger:
    name: CMSIS-DAP@pyOCD
    protocol: swd
    clock: 10000000
    start-pname: M55_HP
    connect: attach
    reset:
      - type: system
        pname: M55_HP
      - type: core
        pname: M55_HE
    gdbserver:
      - port: 3333
        pname: M55_HP
      - port: 3334
        pname: M55_HE
    telnet:
      - mode: console
        pname: M55_HE
        port: 4445
      - mode: monitor
        pname: M55_HP
        port: 4444

debug-vars:

Contains default values for debug sequence variables. These values can be overridden by explicit settings in a *.dbgconf file provided in the debugger: node.

Example:

  debug-vars:
    vars: |
      // Default values for variables in debug sequences. Are configured with a *.dbgconf file in the user project
      __var SWO_Pin               = 0;                    // Serial Wire Output pin: 0 = PIO0_10, 1 = PIO0_8
      __var Dbg_CR                = 0x00000000;           // DBG_CR
      __var BootTime              = 10000;                // 10 milliseconds

debug-sequences:

Contains debug sequences from the DFP for the target. A sequence with no blocks disables the default sequence; sequence names can override default sequences from the DFP.

Example:

  debug-sequences:
    - name: DisableWarmResetHandshake
      blocks:
        - execute: |
            Write32(0x1A601024, 0);
      pname: M55_HE
    - name: DisableWarmResetHandshake
      blocks:
        - execute: |
            Write32(0x1A600024, 0);
      pname: M55_HP
    - name: DebugDeviceUnlock
      blocks:
        - execute: |
            DAP_Delay(500000);  // Delay for 500ms
    - name: ResetSystem
      blocks:
        - execute: |
            Sequence("DisableWarmResetHandshake");
        - execute: |
            // System Control Space (SCS) offset as defined in Armv6-M/Armv7-M.

            __var SCS_Addr   = 0xE000E000;
            __var AIRCR_Addr = SCS_Addr + 0xD0C;
            __var DHCSR_Addr = SCS_Addr + 0xDF0;

            // Execute SYSRESETREQ via AIRCR
            Write32(AIRCR_Addr, 0x05FA0004);
        - while: (Read32(DHCSR_Addr) & 0x02000000)
          timeout: 500000

debug-topology:

Describes the properties of the system hardware for debug functionality. The information for this node is taken from the DFP. If the information is not provided in the *.cbuild-run.yml file, pyOCD will use the default values described below.

debug-topology: Content
    debugports: Optional Describes the CoreSight debug ports of the device and its capabilities.
    processors: Optional Map of pname identifiers to access port IDs (mandatory for multi-processor devices).
    swj: Optional Device allows switching between Serial Wire Debug (SWD) and JTAG protocols (true or false).
    dormant: Optional Device requires the dormant state to switch debug protocols (true or false).
debugports: Content
- dpid: Required Unique ID of this debug port.
    accessports: Optional List of CoreSight access ports (APv1/APv2) (mandatory for multi-processor devices).
accessports: Content
- apid: Required Unique ID of this access port. If only apid is provided, access port (APv1) with index 0 will be implicitly used.
    index: Optional Index to select this access port (APv1) for a target access.
    address: Optional Address to select this access port (APv2) in its parent's address space for a target access.

Note

index: and address: cannot be specified at the same time.

processors: Content
- pname: Required Processor identifier (mandatory for multi-processor devices).
    apid: Optional Access port ID to use for this processor.
    reset-sequence: Optional Name of debug sequence for reset operation (default: ResetSystem sequence).

Default values:

debug-topology:
  dormant: false
  swj: true
  debugports:
    - dpid: 0
      accessports:
        - apid: 0
          index: 0

Example:

  debug-topology:
    debugports:
      - dpid: 0
        accessports:
          - apid: 0
            address: 0x00200000
          - apid: 1
            address: 0x00300000
    processors:
      - pname: M55_HP
        apid: 0
      - pname: M55_HE
        apid: 1
    dormant: true

Sequence diagrams for pyOCD subcommands

pyOCD connects to the target as shown in the Open-CMSIS-Pack "Usage of debug access sequences" Connect Debugger to Device diagram. Additionally, pyOCD supports the attach connect mode (see connect:), which connects without resetting, or halting the target.

Note

The diagram arrow "Repeat for each Processor Core" is misleading. Only the following blocks are executed once per processor core: Read Target Features, DebugCoreStart, Stop Processor / ResetCatchSet, Wait for Processor to Stop, and Initialize Debug Components. The remaining diagram elements run once for the device as a whole. This distinction is important for multi-core targets, where some blocks run once per core and others run once for the device.

Info

Blue blocks are clickable and open the linked documentation.

Erase

flowchart TD classDef seq fill:#c7d6ea,stroke:#333; B0(Open-CMSIS-Pack<br>Connect Debugger to Device<br>sequence):::seq click B0 "https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#usage_of_sequences" B0 -.-> B1 B1[Set reset catch on all cores] --> B2 B2[Reset device with<br>primary core using<br>selected reset type] --> B3 B3[Clear reset catch on all cores] --> loop subgraph loop[Loop over algorithms for primary core] B4(Open-CMSIS-Pack<br>Flash Erase<br>sequence):::seq click B4 "https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/algorithmFunc.html" B4 --> B5 B5[Put primary core in deadloop] end loop -.-> B6 B6(Open-CMSIS-Pack<br>Disconnect Debugger<br>sequence):::seq click B6 "https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#usage_of_sequences"

Load

flowchart TD classDef seq fill:#c7d6ea,stroke:#333; B0(Open-CMSIS-Pack<br>Connect Debugger to Device<br>sequence):::seq click B0 "https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#usage_of_sequences" B0 -.-> B1 B1([Evaluate pre-reset type]) B1 --> B2 B2[Set reset catch on all cores] --> B3 B3[Reset device with<br>primary core using<br>selected pre-reset type] --> B4 B4[Clear reset catch on all cores] --> loop B1 -- off --> loop subgraph loop[Loop over algorithms for primary core] B5(Open-CMSIS-Pack<br>Flash Program<br>sequence):::seq click B5 "https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/algorithmFunc.html" B5 --> B6 B6[Put primary core in deadloop] end loop -.-> B7 B7([Evaluate post-reset type]) B7 --> B8 B8[Reset device with<br>primary core using<br>selected post-reset type] --> B9 B7 -- off --> B9 B9(Open-CMSIS-Pack<br>Disconnect Debugger<br>sequence):::seq click B9 "https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#usage_of_sequences"

GDB server

flowchart TD classDef seq fill:#c7d6ea,stroke:#333; B0(Open-CMSIS-Pack<br>Connect Debugger to Device<br>sequence):::seq click B0 "https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#usage_of_sequences" B0 -.-> B1 B1{Is reset-run<br>option set?} B1 -- Yes --> B2 B2[Reset device with<br>primary core using<br>selected reset type] --> B3 B1 -- No --> B3 B3[Create GDB servers for all cores] --> gdbserver subgraph gdbserver[Core's GDB server] B4([Wait for GDB client<br>connection to server]) end gdbserver -.-> gdbclient subgraph gdbclient[GDB client connection] B5[GDB client connected] --> B6 B6[Halt core] --> loop subgraph loop[Loop] B7([Process GDB<br>commands]) -.-> B8 B8[Client detached<br>or disconnected] end B8 --> B9 B9[Close GDB client connection] end gdbclient -.-> gdbserver2 subgraph gdbserver2[Core's GDB server] B10([Wait for all GDB client<br>connections to close]) -.-> B11 B11[Resume core] --> B12 B12[Close core's GDB server] end gdbserver2 -.-> B13 B13([Wait for all servers to close]) --> B14 B14(Open-CMSIS-Pack<br>Disconnect Debugger<br>sequence):::seq click B14 "https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#usage_of_sequences"

Run

flowchart TD classDef seq fill:#c7d6ea,stroke:#333; B0(Open-CMSIS-Pack<br>Connect Debugger to Device<br>sequence):::seq click B0 "https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#usage_of_sequences" B0 -.-> B1 B1[Halt all cores] --> B2 B2[Create Run servers for all cores] --> B3 B3[Reset device with<br>primary core using<br>selected reset type] B3 ---> runserver subgraph runserver[Core's Run server loop] B4([Process<br>Semihosting + RTT]) -.-> B6 B6{EOT<br>received?} end B3 --> loop subgraph loop[Loop] B7{Timelimit<br>reached?} B8{User terminated<br>pyOCD instance?} end B6 -- Yes ---> B9 B7 -- Yes ---> B9 B8 -- Yes ---> B9 B9[Close all servers] --> B10 B10(Open-CMSIS-Pack<br>Disconnect Debugger<br>sequence):::seq click B10 "https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#usage_of_sequences"