J-Run

Automate test runs on real hardware

Overview

J-Run is a command-line utility for programming embedded hardware with test applications, controlling execution, and retrieving test results. It can be used to automate test runs that would otherwise involve considerable manual work.

J-Run works with any Arm or RISC-V device supported by J-Link and is compatible with standard ELF output. During a test, J-Run captures target output via RTT or Semihosting and detects when a test has finished.

Test application output can be displayed in the terminal or redirected to other tools for further analysis.

Use cases

J-Run can be used for any test task that needs to run on target hardware. It is especially useful for automating recurring tests or single test setups that require running multiple test variations in sequence. Using J-Run can save significant manual effort and eliminate errors caused by manual execution.

Firmware integrity tests

When new capabilities are added to firmware during development, the overall integrity of the firmware must be ensured (i.e., that the target executes as expected). While regular debugging usually focuses on finding bugs or testing only the changed functions, automated tests can check all aspects of the firmware. A test can run the firmware in a self-test mode, which exercises all modules and outputs the results.

These tests, especially when peripherals are involved or timing is critical, need to run on actual hardware. J-Run enables performing such tests. Test runs can be triggered automatically after each build, manually by a developer, or from a continuous integration (CI) system.

Performance tests

Increasing the performance of embedded software can be time-consuming. After optimization opportunities are identified and implemented, execution tests must be rerun to verify the expected results. While some performance improvements affect only a single firmware in one configuration, other changes may need to be deployed across multiple systems. In such cases, multiple tests must be run for each change.

J-Run can be fully controlled from the command line and integrated into test scripts or test environments. This enables running different tests without manual intervention.

Software

J-Run comes as part of the J-Link Software and Documentation Package. The software package is free for any J-Link or J-Trace device and can be downloaded here:

How J-Run works

J-Run downloads the application image from ELF executables. The regular output of a toolchain or build system can be used without further modification. Additional information for output control is also extracted from the ELF file. As with a regular debug build, symbols must be present.

After the application image is programmed to the target device, the target is reset and started. While the test application is running, J-Run captures its output, supporting both RTT and semihosting.

J-Run continues running until it captures the exit string indicating that the test is complete or receives the semihosting exit command.

Capturing test output

J-Run provides flexible methods for capturing output from test applications running on target hardware. It supports both RTT and semihosting, enabling reliable test execution and result collection across a wide range of targets.

Output via RTT

J-Run can capture output from the test application via RTT and prints all output to the terminal. RTT allows tests to run without interruption and is especially useful for timing-sensitive tasks.

When J-Run captures a line that matches the exit wildcard string (default "STOP"), the test is complete, and J-Run exits.

Output via semihosting

J-Run can perform semihosting operations to capture output from the test application. For semihosting, the target application is temporarily halted for each operation, but it can be used on any target, including those that do not support RTT.

In addition to completing a test with the exit wildcard string, J-Run also supports the semihosting exit operation.

Example output

C:> jrun -device STM32F407IE ApplicationTest.elf
J-Run compiled Feb 01 2021 12:09:19
(c) 2018-2021 SEGGER Microcontroller GmbH    www.segger.com

Open application...OK
Set target device to STM32F407IE...OK
Select SWD interface...OK
Set interface speed to 4000 kHz...OK
Reset target...OK
Download 08000000-08002E19...OK
SEGGER_SEMIHOST_DebugHalt found at 0x08000734
Start target application...OK
Reading output from target until exit command.
==============================================

Application Test
Compiled 02.02.2021 08:11:19
Starting OS... OK.
Testing Hardware... OK. Running at 168 MHz.
Testing IP... OK. Connected at 192.168.12.9
Testing Filesystem... OK. 3.8 GB free.
All tests done. STOP.

J-Run finished. Press any key to exit.
C:> _

C:> jrun -device STM32F407IE -if SWD --semihost --silent PerformanceTest_sinf_v7EM.elf
Testing sinf...
Took 2582433 cycles
C:> _