J-Run

J-Run is a command line utility for automated tests. It loads an application (elf) file to the device under test, runs it, and captures the application's output.

The origin on J-Run is described in this blog post: https://blog.segger.com/j-run-automating-performance-tests

Test Applications

J-Run supports any ARM and RISC-V device which is supported by J-Link, and elf output from most toolchains.

The test application can do standard printf-style debug output to the debugger. J-Run supports handling of RTT and Semihosting.

When the test application is finished, it can call the Semihosting exit operation or print the wildcard exit string (by default "*STOP*"), to exit the J-Run test.

The target output is printed to the terminal. It can be redirected to a file or application for further analysis.

Usage

JRun [options] elf-file

Option	Default	Description	Alias
--usb <SerialNo>/<Nickname>	Not set	Connect to J-Link with SN <SerialNo> or nickname <Nickname> via USB.	-usb
--ip <Hostname>/<SerialNo>/<Nickname>	Not set	Connect to J-Link with IP <Hostname>, SN <SerialNo> or nickname <Nickname> via IP.	-ip
--device <str>	STM32F407IE	Set device name to <str>.	-device, --d, -d
--if SWD/JTAG	SWD	Select SWD or JTAG as target interface.	-if
--speed <khz>	4000	Set interface speed to <khz> kHz.	-speed
--rtt	Auto	Force RTT enabled.
--nortt	Auto	Force RTT disabled.
--semihost	Auto	Force semihosting enabled.	--sh
--nosemihost	Auto	Force semihosting disabled.	--nosh
--args <args>	Not set	Arguments passed to target application via semihosting and RTT.
--send <str>	Not set	Send specified string to target.
--trigger <str>	Not set	Wait for this string before sending the string specified with --send to the target; Send immediately if not set.
--wargs <str>	*ARGS*	Set RTT getargs wildcard to <str>.
--wexit <str>	*STOP*	Set exit wildcard to <str>.	--exit, -x, --x
--wpass <str>	Not set	Set pass wildcard to <str>.	--pass
--wfail <str>	Not set	Set fail wildcard to <str>.	--fail
--nodelete	Off	Disable deletion of files through semihosting file I/O.
--norename	Off	Disable renaming of files through semihosting file I/O.
--nosandbox	Off	Disable sandbox for file I/O.
--redirect-rtt <chan> <port>	Not set	Redirect RTT channel <chan> to local port <port>.
--quit	On	Automatically exit J-Run on application exit.
--wait	Off	Wait for key press on application exit.
--stderr	Off	Also send target output to stderr.	--2, -2
--silent	Off	Work silently.	--s, -s
--verbose	Off	Increase verbosity.	--v, -v
--dryrun	Off	Dry run. Parse elf-file only.
--jlinkscriptfile <str>	Not set	Set path of J-Link script file to use to <str>. Further info: J-Link script files.
--pc <mode>/0xXXXXXXXX	vec	Initialize PC before start (according to <mode> or fixed address). <mode>: vec - Vector table, elf - ELF start address, off - do not init.
--sp <mode>/0xXXXXXXXX	vec	Initialize SP before start (according to <mode> or fixed address). <mode>: vec - Vector table, off - do not init.
--log <file>	Off	Write output to logfile.
--fileonly	Off	Write output _only_ to logfile.

Note:
In case some arguments are not available, please consider updating to the latest J-Link version.

Example Output

C:\Work\JLink\JRun\Test>JRun.exe Target\ST_STM32F407_RTT_JRun_Demo.elf
SEGGER J-Run V1.24 (Compiled Sep 16 2024 10:08:12)
Open application...OK
Connecting to J-Link...OK
Connected to J-Trace PRO V3  compiled Jul  3 2024 16:59:08 (S/N 1223000038).
DLL Version: 7.96j
Set target device to STM32F407IE...OK
Select SWD interface...OK
Set interface speed to 4000 kHz...OK
Reset target...OK
Download 0x08000000 - 0x08000FC9...OK
Set RTT control block at 0x20000000...OK
Start RTT...OK
Start target application (SP 0x20020000, PC 0x08000E9F)... OK
Reading output from target until exit command.
==============================================

SEGGER J-Run demo.

Took 8395654 cycles

Target Application exit.

Passing arguments to target application

J-Run can supply arguments to your application via Semihosting and via RTT. Arguments can be passed by using the "--args"option

C:\Work\JLink\Output\Debug_x64>JRun --wait ST_STM32F407_SemihostArgs_Example.elf --args "foo baz --verbose"

Argument passing is support for three implementations that will need counterpart in target code

• Standard Semihosting
• Segger Semihosting
• Segger RTT, device to send *ARGS* (or another wildcard specified with --wargs) and receive <args>

For more information on passing arguments please refer to Passing Command-line arguments in C for Embedded Targets

Alternatively, the --send <str> option can be used to send a string to the target. If a trigger was specified using --trigger <str>, the string gets send after the target send the specified trigger string. Otherwise, the send string gets send immediately.

Returning arguments from target application

J-Run can retrieve return values from target and will exit with the return value received.

Return value retrieval is supported for two implementations that will need counterpart in target code

• Standard Semihosting SYS_EXIT command (SW Reason = ADP_Stopped_ApplicationExit, Subcode = <ret>)
• Segger RTT, device to send *STOP*<ret>

Please note that values <0 are used by J-Run

Return	Value	Comment
-1	JRUN_EXIT_ERR	J-Run error on host side. Check logs.
0	JRUN_EXIT_OK	J-Run succeeded
>0	<ret>	Application specific return value.

J-Run can also be instructed to scan the targets output for wildcards and exit the execution accordingly. Below is an overview of the possible wildcards.

Option	Default	Behavior
--wexit <str>	*STOP*	Checks if target send an integer directly after the wildcard. If yes, J-Run exits with the integer as return code. Else, J-Run exits with 0.
--wpass	Not set.	J-Run exits with 0.
--wfail	Not set.	J-Run exits with -1.

Initialization of PC/SP on start

In order to start the application properly, J-Run needs to setup the target stack pointer (SP) and program counter (PC). While this is done automatically in Segger GUI products like Ozone, user need to take care in J-Run. J-Run will display what it did right before application start as described in the following.

If the values do not match you target needs, it will result in undefined behaviour.

SP and PC initialized by vector table

This is the default behaviour of J-Run and will work for most devices including our STM32F407 trace reference board. The compiler stores the SP and PC values in the vector table, located at start of the target memory.

C:\Work\JLink\JRun\Test>JRun.exe Target\ST_STM32F407_RTT_JRun_Demo.elf
<...>
Start target application (SP 0x20020000, PC 0x08000E9F)... OK
Reading output from target until exit command.

SP initialized by vector table, PC by ELF entry point address

Some toolchains only store the SP in the vector table. In case the entry point is set correctly in the ELF file, we can get it from there.

For this example, the ELF entry point contains same value as the vector table.

C:\Work\JLink\JRun\Test>JRun.exe Target\ST_STM32F407_RTT_JRun_Demo.elf --pc elf
<...>
Start target application (SP 0x20020000, PC 0x08000E9F)... OK
Reading output from target until exit command.

SP and PC initialized by boot loader

Some target devices use a bootloader approach to copy and start the application on the target. In this case, we should not interfere with and rather leave initialization up to the bootloader.

This example will work due to the target PC after reset and startup code.

C:\Work\JLink\JRun\Test>JRun.exe Target\ST_STM32F407_RTT_JRun_Demo.elf --pc off --sp off
<...>
Start target application (SP <noinit>, PC <noinit>)... OK
Reading output from target until exit command.

User defined value

In case your target environment does not support any of the above methods, you can still provide the initial values to J-Run. If you don't have an idea how to find out these values, you might start your test application using Ozone and simply take over the values.

This example will not work - the user provided values will be set as is, starting the application with an invalid SP and a bogus address.

C:\Work\JLink\JRun\Test>JRun.exe Target\ST_STM32F407_RTT_JRun_Demo.elf --pc 0xdeadbeef --sp 0xf00bad00
<...>
Start target application (SP 0xF00BAD00, PC 0xDEADBEEF)... OK
Reading output from target until exit command.

Semihosting File I/O

J-Run supports opening, closing, reading, writing, renaming, and deleting of files by the target via semihostig operations. For an overview see SEGGER_Semihosting and Semihosting.

Below is a list with semihosting file I/O operations J-Run currently supports:

Operation	Description
0x01 SYS_OPEN	Opens a file on the host system and returns a filehandle.
0x02 SYS_CLOSE	Close a file.
0x05 SYS_WRITE	Write into file or stream.
0x06 SYS_READ	Read bytes from a previous opened file.
0x0A SYS_SEEK	Set the file cursor to a given position.
0x0C SYS_FLEN	Get the length of file.
0x0E SYS_REMOVE	Delete a file. Can be deactivated with --nodelete.
0x0F SYS_RENAME	Rename a file. Can be deactivated using --norename.

By default every file operation is sandboxed, meaning only files in the directory J-Run was invoked in and any subdirectory can be accessed. The sandbox can be turned off with the --nosandbox option.

Opening modes

When opening a file the target specifies the opening mode as an integer. The following table shows how the values map to ISO C fopen modes:

mode	0	1	2	3	4	5	6	7	8	9	10	11
ISO C fopen mode	r	rb	r+	r+b	w	wb	w+	w+b	a	ab	a+	a+b

Redirect RTT channels

The --redirect-rtt <chan> <port> command line option makes J-Run redirect the specified RTT channel to the specified port using TCP.

At the start J-Run waits for a connection for every channel that gets redirected. Then everything the target writes to one of the redirected channels will be send to the corresponding port. This works bidirectional, meaning anything send to the port will be redirected to the target on the corresponding RTT channel. This way it is possible to communicate with the target through any TCP capable software like telnet cli or PuTTY, or even integrate it in python scripts via python sockets (https://docs.python.org/3/library/socket.html).