Skip to main content

How to use the xPack OpenOCD

This page is intended for those who plan to use the xPack OpenOCD binaries in their workflows.

Versioning​

The version string used by the upstream OpenOCD project is a three number string like 0.12.0-4; to this string the xPack distribution adds a fourth number, but since SemVer allows only three numbers, all additional ones can be added only as pre-release strings, separated by a dash, like 0.12.0-4. When published as a npm package, the version gets a fifth number, like 0.12.0-4.1.

Since adherence of third party packages to SemVer is not guaranteed, it is recommended to avoid referring to the xPack OpenOCD dependency via a SemVer expressions like ^0.12.0-4 or ~0.12.0-4, and prefer exact matches, like 0.12.0-4.1.

Shared libraries​

On all platforms the binary xpm packages are standalone, and expect only the standard runtime to be present on the host.

All dependencies that are built as shared libraries are copied locally in the libexec folder (or in the same folder as the executable for Windows).

DT_RPATH and LD_LIBRARY_PATH​

On GNU/Linux the binaries are adjusted to use a relative path:

$ readelf -d library.so | grep rpath
 0x000000000000001d (RPATH)            Library rpath: [$ORIGIN]

In the GNU ld.so search strategy, the DT_RPATH has the highest priority, higher than LD_LIBRARY_PATH, so if this latter one is set in the environment, it should not interfere with the xPack binaries.

Please note that previous versions, up to mid-2020, used DT_RUNPATH, which has a priority lower than LD_LIBRARY_PATH; setting LD_LIBRARY_PATH in the environment overrode DT_RUNPATH, resulting in failures to load the libraries.

@rpath and @loader_path​

Similarly, on macOS, the binaries are adjusted with install_name_tool (part of CLT) to use a relative path.

Drivers​

Windows drivers​

Most JTAG probes require separate drivers on Windows. For additional information, please refer to the Install Guide page.

GNU/Linux UDEV subsystem​

For the JTAG probes implemented as USB devices (actually most of them), the last installation step on GNU/Linux is to configure the UDEV subsystem. For additional information, please refer to the Install Guide page.

macOS​

On macOS, JTAG probes implemented as USB devices usually are recognised directly and do not need explicit drivers.

Using openocd in testing​

OpenOCD provides a fairly good implementation of Arm semihosting which can be used for automated testing. For this the application must be build with full semihosting support.

note

The details of semihosted builds are beyound the scope of this page.

CMake example​

The easiest way to build automated tests is with CMake in xPack applications.

Windows

Since on Windows the xPack OpenOCD uses .cmd forwarders, it is necessary to explicitly define the extension, later used when invoking openocd:

if("${CMAKE_HOST_SYSTEM_NAME}" STREQUAL "Windows")
  set(extension ".cmd")
endif()

To run the test, the semihosted application must be first programmed into the board and executed in an environment with semihosting enabled.

An example of such a test running on a STM32F4 board can be:

if (ENABLE_RTOS_APIS_TEST)

  add_executable(rtos-apis-test)
  set_target_properties(rtos-apis-test PROPERTIES OUTPUT_NAME "rtos-apis-test")

  // ... definitions to build the application with semihosting support ...

  add_test(
    NAME "rtos-apis-test"

    COMMAND openocd${extension}
      # -d3
      -c "gdb_port disabled"
      -c "tcl_port disabled"
      -c "telnet_port disabled"
      -f interface/stlink-dap.cfg
      -f target/stm32f4x.cfg
      -c "program rtos-apis-test.elf verify"
      -c "arm semihosting enable"
      -c "arm semihosting_cmdline rtos-apis-test"
      -c "reset"
    )

endif ()
tip

The commands to disable the various ports are required to avoid possible port collisions with other debug sessions or tests running in parallel on other boards.

The commented out -d3 is there for just in case something wrong happens, to enable a detailed debug log.

In an xPack application, the tests can be invoked by running an xPack action, like this:

xpm run test

This asssumes that in package.json there is an action named test and that all required tools were previously installed:

{
  "...": "...",

  "xpack": {
    "actions": {
      "...": "...",
      "test": "ctest -V"
    },
    "devDependencies": {
      "@xpack-dev-tools/cmake": "3.26.5-1.1",
      "@xpack-dev-tools/ninja-build": "1.11.1-3.1",
      "@xpack-dev-tools/openocd": "0.12.0-3.1",
      "@xpack-dev-tools/arm-none-eabi-gcc": "12.3.1-1.2.1"
    }
  }
}

The xPack action runs the defined command (ctest -V in this case) in an environment where xpacks/.bin is prepended to the PATH, so the tools installed locally by xpm are available and prefered to possibly other similar tools installed in the system, thus achieving a good reproducibility.