What's on that Access Port?

In my last post, I wrote about debugging the Nordic Semiconductor nRF54LM20 when a peripheral, specifically the Key Management Unit (KMU), writes directly to memory while the CPU is halted. Or I should really say that I wrote about debugging the application core (Cortex-M33), as the nRF54LM20 also has a RISC-V coprocessor (VPR) referred to as the Fast Lightweight Peripheral Processor (FLPR). Around the time that Nordic announced the VPR core, I wrote two posts; one about its architecture and the other about how communication works between it and an application core.

In the latter VPR post, I attached to the application core with GDB and JLinkGDBServer in the same manner that I did in my recent KMU exploration post in order to step through the communication protocol. This strategy was appropriate for the operations described in the respective posts, but in some cases it may be desirable to connect to the VPR core for debugging.

Typically, silicon vendors will provide tooling, or work with open source projects, to make it easy to designate the core you want to connect to at a higher level of abstraction. For example, Nordic products have robust suport in the Zephyr RTOS ecosystem, and Zephyr’s meta CLI, west, can be used to build (west build) and flash (west flash) firmware on all chips. west supports building and flashing multiple images in one operation using System Build (Sysbuild). Each build system managed by Sysbuild is referred to as a domain, and the --domain flag can be used to perform the specified operation for only the specified domain.

While we typically want to target all domains when building and flashing, west debug is a great example of how the --domain flag can be useful. For example, if we were building the Zephyr blinky sample for the nRF54LM20, using the FLPR for GPIO control via Nordic’s High Performance Framework (HPF) (stay tuned for a future post on HPF), we would use the following command to build the blinky application for the application core and the GPIO application for the FLPR core.

west build -p -b nrf54lm20dk/nrf54lm20b/cpuapp nrf/samples/zephyr/basic/blinky -- -DSB_CONFIG_HPF=y -DSB_CONFIG_HPF_GPIO=y -DSB_CONFIG_HPF_GPIO_BACKEND_ICMSG=y -DEXTRA_DTC_OVERLAY_FILE="./boards/nrf54lm20dk_nrf54lm20b_cpuapp_hpf_gpio.overlay"

In the resulting build/ directory, we would see a top-level domains.yaml file with the following contents.

default: blinky
build_dir: <local-path>/build
domains:
  - name: blinky
    build_dir: <local-application-path>/build/blinky
  - name: hpf_gpio
    build_dir: <local-application-path>/build/hpf_gpio
flash_order:
  - blinky
  - hpf_gpio

Issuing a west flash command would flash both of the images onto the device, but because we can only debug one core at a time, west debug with no flags would target the default domain (blinky) and connect to the application core. Specifying hpf_gpio would instead connect to the FLPR.

west debug --domain hpf_gpio

If you prefer a graphical UX, you could leverage this same functionality via Nordic’s VSCode tooling, as described in this post by my Nordic coworker Sebastian Viviani.

Behind the scenes, Zephyr includes board support files that help west know how to setup the debugging connection. If we were to look in each specific domain’s build/<domain>/zephyr/ directory, we would find a runners.yaml file. For example, the hpf_gpio domain in the previous build includes the following contents.

# Available runners configured by board.cmake.
runners:
- nrfutil
- jlink

# Default flash runner if --runner is not given.
flash-runner: nrfutil

# Default debug runner if --runner is not given.
debug-runner: jlink

# Common runner configuration values.
config:
  board_dir: <local-application-path>/zephyr/boards/nordic/nrf54lm20dk
  # Build outputs:
  elf_file: zephyr.elf
  hex_file: zephyr.hex
  bin_file: zephyr.bin
  # Host tools:
  gdb: <local-zephyr-sdk-path>/zephyr-sdk-1.0.1/gnu/riscv64-zephyr-elf/bin/riscv64-zephyr-elf-gdb
  openocd: <local-zephyr-sdk-path>/zephyr-sdk-1.0.1/hosttools/usr/bin/openocd
  openocd_search:
    - <local-zephyr-sdk-path>/zephyr-sdk-1.0.1/hosttools/opt/openocd/share/openocd/scripts

# Runner specific arguments
args:
  nrfutil:
    []

  jlink:
    - --dt-flash=y
    - --device=nRF54LM20A_RV32
    - --speed=4000

If we were to look at the nRF54LM20 DK board support files in the Zephyr source tree, we would find the following CMake snippet.

boards/nordic/nrf54lm20dk/board.cmake

if(CONFIG_SOC_NRF54LM20A_CPUAPP OR CONFIG_SOC_NRF54LM20B_CPUAPP)
  board_runner_args(jlink "--device=nRF54LM20A_M33" "--speed=4000")
elseif(CONFIG_SOC_NRF54LM20A_CPUFLPR OR CONFIG_SOC_NRF54LM20B_CPUFLPR)
  board_runner_args(jlink "--device=nRF54LM20A_RV32" "--speed=4000")
endif()

if(CONFIG_TFM_FLASH_MERGED_BINARY)
  set_property(TARGET runners_yaml_props_target PROPERTY hex_file tfm_merged.hex)
endif()

include(${ZEPHYR_BASE}/boards/common/nrfutil.board.cmake)
include(${ZEPHYR_BASE}/boards/common/jlink.board.cmake)

The args.jlink flags at the bottom of the runners.yaml file are sourced from these board_runner_args() CMake macros, and they are passed to JLinkGDBServer when invoking west debug for the corresponding domain. Because J-Link has native multi-core support for the nRF54L series, the --device flag can be used to tell JLinkGDBServer to consult its internal database for information on how to connect to each of the respective cores.

If the debugger is not already knowledgeable of the SoC architecture, it may be necessary to provide more detailed information. For example, see the nRF54H20 J-Link script for connecting to the application core.

In fact, if we were to connect to the FLPR core on the nRF54LM20 using JLinkExe -device nRF54LM20A_RV32 directly, we would see the following sequence of lines in the initial output.

Found SW-DP with ID 0x6BA02477
RISC-V behind DAP detected
DPIDR: 0x6BA02477
CoreSight SoC-400 or earlier
AP[1] (AHB-AP) specified by user as debug AP.
AP map scan skipped.
AP map:
  AP[0]: AHB-AP, APAddr = 0x00000000
  AP[1]: AHB-AP, APAddr = 0x01000000
  AP[2]: MEM-AP, APAddr = 0x02000000
Core base addr: 0x5004C400 (user configured)

In my nRF54LM20 KMU post, I included the following diagram from the nRF54LM20 datasheet that describes the debug architecture, including the three Access Ports (APs) that are available via the Debug Access Port (DAP).

The datasheet also includes a table describing the functionality of each access port.

As observed in the JLinkExe output, it opts to forego scanning the access port map in favor of connecting directly to the second AHB-AP (AP[1]), which it knows to be the access port for the RISC-V FLPR core. If instead invoking JLinkExe -device nRF54LM20A_M33 to debug the Cortex-M33 application core, the following output would be observed.

Found SW-DP with ID 0x6BA02477
DPIDR: 0x6BA02477
CoreSight SoC-400 or earlier
AP map detection skipped. Manually configured AP map found.
AP[0]: AHB-AP (IDR: Not set, ADDR: 0x00000000)
AP[1]: APB-AP (IDR: Not set, ADDR: 0x00000000)
AP[2]: MEM-AP (IDR: Not set, ADDR: 0x00000000)
Iterating through AP map to find AHB-AP to use
AP[0]: Core found
AP[0]: AHB-AP ROM base: 0xE00FE000
CPUID register: 0x411FD210. Implementer code: 0x41 (ARM)

In this case the J-Link once again reports that the AP map is known, but instead of selecting an access port immediately, it iterates through the map looking for the Cortex-M33 core. While the underlying logic is hidden in the closed source JLinkArm.dll library that underlies most J-Link tooling, it is likely that the default behavior for Arm cores, even those on devices known to the J-Link, is to leverage the information offered by the Arm Debug Interface (ADI) to discover the core and its capabilities.

The ADI specifies the architecture of a Debug Access Port (DAP), which consists of a Debug Port (DP) and one or more Access Ports (APs).

There are multiple types of debug ports: JTAG (JTAG-DP), Serial Wire (SW-DP), and Serial Wire / JTAG (SWJ-DP). Likewise, there are multiple types of access ports, with the Advanced High-performance Bus Access Port (AHB-AP) itself being a type of Memory Access Port (MEM-AP), and the Control Access Port (CTRL-AP) being a custom AP implementation by Nordic. There are a minimum set of registers for DPs and APs respectively, which must be provided by any implementation. The following diagram outlines the interaction between the DP and MEM-APs (and thus AHB-APs).

This diagram gives a hint to how a debug probe, such as the J-Link, may go about discovering the access ports that are available on a given DAP, even if the SoC is not already known. The first relevant register is the DP’s AP Select (SELECT) register (highlighted in the DP registers above). It can be used to select an access port (APSEL) and the register bank (APBANKSEL) within the access port.

If the value in the APSEL bits does not correspond to an access port on the DAP, the ADI defines the following behavior.

If there is no AP with the ID APSEL, all AP transactions return zero on reads and are ignored on writes.

After successfully selecting an access port, the AP’s identification register (IDR) (highlighted in the MEM-AP registers above), which is the only register that must be implemented by all APs, can be used to understand the attributes of the AP. It is always the last register in the AP register space, located at 0xFC.

For the most part, debuggers hide the specific reads and writes to DP and AP registers behind higher levels of abstractions, such as reading a memory address or advancing the program counter of a CPU. However, J-Link does support lower level commands to read and write directly to DPs (ReadDP / WriteDP) and APs (ReadAP / WriteAP). If you wanted to manually scan the AP map, you could use the following sequence of commands.

Write to DP register 2 (SELECT), setting the APSEL value to 0 and the APBANKSEL value to 0xF, which will allow for targeting the IDR register (0xFC) on subsequent AP reads.

J-Link> WriteDP 2 0x000000F0
Writing DP register 2 = 0x000000F0 (0 write repetitions needed)

Read AP register 3 (IDR in bank 0xF).

J-Link> ReadAP 3
Reading AP register 3 = 0x84770001 (0 read repetitions needed)

The resulting value (0x84770001) can be decoded to provide information about the AP, which we already know to be an AHB-AP.

Issuing the same sequence of commands with APSEL set to 1 once again informs us that the second access port is also an AHB-AP.

J-Link> WriteDP 2 0x010000F0
Writing DP register 2 = 0x010000F0 (0 write repetitions needed)

J-Link> ReadAP 3
Reading AP register 3 = 0x84770001 (0 read repetitions needed)

However, reading the third access port (2), returns a different IDR value.

J-Link> WriteDP 2 0x020000F0
Writing DP register 2 = 0x020000F0 (0 write repetitions needed)

J-Link> ReadAP 3
Reading AP register 3 = 0x32880000 (0 read repetitions needed)

This is expected given that the third AP is a Nordic CTRL-AP (0x32880000). Decoding the fields in the register, we can identity Nordic’s JEDEC manufacturing code in the DESIGNER field, as specified in the nRF54LM20 datasheet.

An attempt to select a fourth access port (3) results in a read of the IDR register returning 0x00000000, indicating that we have likely reached the end of the AP map.

Though silicon vendors will typically make understanding the low level details of the debug interface extraneous, having at least cursory knowledge of how a debugger enables you to access and control various components of an SoC can be useful. Direct DP and AP register accesses may be necessary in the event that you are reverse engineering an unknown chip, authoring your own debug tooling, or attempting to verify the security state of your product.