(Read only you are interested in)
Allows Trice over the debug probe without using a pin or UART.
This document needs a rework, currently it is a mess, sorry!
Table of Contents
This technique needs to be considered as experimental:
- RTT works good with a SEGGER J-Link debug probe but needs some closed source software components.
- Also ST-Link is usable for trice logs, but maybe not parallel with debugging.
- Most investigations where done with a NUCLEO64-STM32F030R8 evaluation board which contains an on-board debug probe reflashed with a SEGGER J-Link OB software (see below).
- When using very high trice loads over RTT for a long time, sometimes an on-board J-Link (re-flashed ST-Link) could get internally into an inconsistent state (probably internal buffer overrun), what needs a power cycle then.
- You could consider RTT over open-OCD as an alternative.
- The default SEGGER up-buffer size is 1024 bytes, enough for most cases. If not, adapt it in your SEGGER_RTT_Conf.h file.
- Possible: Parallel usage of RTT direct mode with UART deferred mode. You can define
TRICE_UARTA_MIN_ID
andTRICE_UARTA_MAX_ID
inside triceConfig.h to log only a specific ID range over UARTA in deferred mode for example. (#446)
The default SEGGER tools only suport RTT channel 0.
- JLink.exe β
connect β β S β
and keep it active. - Start in Git-Bash or s.th. similar:
trice l -p TCP4 -args localhost:19021
- You may need a trice tool restart after firmware reload.
This is just the SEGGER J-Link server here for demonstration, but if your target device has an TCP4 interface, you can replace this with your target server.
ms@DESKTOP-7POEGPB MINGW64 ~/repos/trice (master)
$ jlink
SEGGER J-Link Commander V7.92g (Compiled Sep 27 2023 15:36:46)
DLL version V7.92g, compiled Sep 27 2023 15:35:10
Connecting to J-Link via USB...O.K.
Firmware: J-Link STLink V21 compiled Aug 12 2019 10:29:20
Hardware version: V1.00
J-Link uptime (since boot): N/A (Not supported by this model)
S/N: 770806762
VTref=3.300V
Type "connect" to establish a target connection, '?' for help
J-Link>connect
Please specify device / core. <Default>: STM32G0B1RE
Type '?' for selection dialog
Device>
Please specify target interface:
J) JTAG (Default)
S) SWD
T) cJTAG
TIF>s
Specify target interface speed [kHz]. <Default>: 4000 kHz
Speed>
Device "STM32G0B1RE" selected.
Connecting to target via SWD
InitTarget() start
SWD selected. Executing JTAG -> SWD switching sequence.
DAP initialized successfully.
InitTarget() end - Took 36.3ms
Found SW-DP with ID 0x0BC11477
DPv0 detected
CoreSight SoC-400 or earlier
Scanning AP map to find all available APs
AP[1]: Stopped AP scan as end of AP map has been reached
AP[0]: AHB-AP (IDR: 0x04770031)
Iterating through AP map to find AHB-AP to use
AP[0]: Core found
AP[0]: AHB-AP ROM base: 0xF0000000
CPUID register: 0x410CC601. Implementer code: 0x41 (ARM)
Found Cortex-M0 r0p1, Little endian.
FPUnit: 4 code (BP) slots and 0 literal slots
CoreSight components:
ROMTbl[0] @ F0000000
[0][0]: E00FF000 CID B105100D PID 000BB4C0 ROM Table
ROMTbl[1] @ E00FF000
[1][0]: E000E000 CID B105E00D PID 000BB008 SCS
[1][1]: E0001000 CID B105E00D PID 000BB00A DWT
[1][2]: E0002000 CID B105E00D PID 000BB00B FPB
Memory zones:
Zone: "Default" Description: Default access mode
Cortex-M0 identified.
J-Link>
Now the TCP4 server is running and you can start the Trice tool as TCP4 client, which connects to the TCP4 server to receive the binary log data:
$ trice l -p TCP4 -args="127.0.0.1:19021" -til ../examples/G0B1_inst/til.json -li ../examples/G0B1_inst/li.json -d16 -pf none
In this G0B1_inst example we use the additional -d16
and -pf none
switches to decode the RTT data correctly.
This is just a demonstration and test for the -port TCP4
usage possibility. Using RTT with J-Link is more easy possible as shown in the next point.
- Start inside Git-Bash or s.th. similar:
trice l -p JLINK -args "-Device STM32F030R8 -if SWD -Speed 4000 -RTTChannel 0"
- Replace CLI details with your settings.
- For G01B_inst:
trice l -p JLINK -args "-Device STM32G0B1RE -if SWD -Speed 4000 -RTTChannel 0" -d16 -pf none
- You can add the
-verbose
CLI switch for more details.
- You may not need a trice tool restart after firmware reload.
- Prerequisite is a processor with memory background access support like ARM Cortex-M cores.
- If you can use a Segger J-Link or an STM ST-Link debug probe (ST Microelectronics eval boards have it) this is an easy and fast way to use Trice without any UART or other port.
- Detailed description can be found in document UM08001_JLink.pdf in chapter 16 which is part of https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack.
- Following examples are for Windows, but should work similar also on Linux and Darwin (MacOS).
- Trice can use the Segger RTT protocol in different ways.
- Hardware paths:
- Use J-Link or J-Link OB (on-board). J-Link OB can be flashed to many ST Microelectronics evaluation boards (v2.0 link hardware) and for example is also usable with NXP and Atmel. For that you can also use a spare STM32 evaluation board (10 EUR) with jumper changes and breakout wires.
- Use ST-Link with gostlink. It uses only one USB endpoint so debugging and trice output in parallel is not possible.
- Use some other Debug-Probe with target memory access (support welcome)
- RTT channel selection (on target and on host)
- RECOMMENDED:
trice l -p JLINK
or shortertrice l
for STM32F030R8 (default port is JLINK) starts in background aJLinkRTTLogger.exe
which connects to J-Link and writes to a logfile which in turn is read by the trice tool. On exit theJLinkRTTLogger.exe
is killed automatically.- It expects a target sending messages over RTT channel 0 (zero). Chapter 16.3.3 in UM08001_JLink.pdf refers to "Up-Channel 1" but this maybe is a typo and probably a 0 is mend. The
JLinkRTTLogger.exe
main advantage against other free available SEGGER tools is, that all bytes are transferred. Other SEGGER tools assume ASCII characters and useFF 00
toFF 0F
as a terminal switch command and filter that out causing Trice data disturbances. - It should be possible to start several instances on on different targets using
-SelectEmuBySN <SN>
inside the-args
Trice CLI switch. JLinkRTTLogger
binaries for Linux & Darwin can be found at https://www.segger.com/downloads/jlink/.
- It expects a target sending messages over RTT channel 0 (zero). Chapter 16.3.3 in UM08001_JLink.pdf refers to "Up-Channel 1" but this maybe is a typo and probably a 0 is mend. The
trice l -p STLINK
starts in background atrice/third_party/goST/stRttLogger.exe
which connects to ST-Link and writes to a logfile which in turn is read by the trice tool. On exit thestRttLogger.exe
is killed automatically. It expects a target sending messages over RTT channel 0 (other channels supported too but may not work).
It is possible to start several instances on different channels as well as on different targets. The source code is in https://github.com/bbnote/gostlink and should work also at least under Linux.
- If you have the choice, prefer J-Link. It allows parallel debugging and trice output.
- The full
-args
string is normally required and depends on the used device. Example:trice l -args="-Device STM32F070RB -if SWD -Speed 4000 -RTTChannel 0 -RTTSearchRanges 0x20000000_0x1000"
. The-RTTSearchRanges
part is mostly optional. - Enter
trice h -log
and read info for-args
switch:
- RECOMMENDED:
- Hardware paths:
-args string
Use to pass port specific parameters. The "default" value depends on the used port:
port "COMn": default="", use "TARM" for a different driver. (For baud rate settings see -baud.)
port "J-LINK": default="-Device STM32F030R8 -if SWD -Speed 4000 -RTTChannel 0 -RTTSearchRanges 0x20000000_0x1000",
The -RTTSearchRanges "..." need to be written without extra "" and with _ instead of space.
For args options see JLinkRTTLogger in SEGGER UM08001_JLink.pdf.
port "ST-LINK": default="-Device STM32F030R8 -if SWD -Speed 4000 -RTTChannel 0 -RTTSearchRanges 0x20000000_0x1000",
The -RTTSearchRanges "..." need to be written without extra "" and with _ instead of space.
For args options see JLinkRTTLogger in SEGGER UM08001_JLink.pdf.
port "BUFFER": default="0 0 0 0", Option for args is any byte sequence.
(default "default")
- Prerequisite is a SEGGER J-Link debug probe or a development board with an on-board J-Link option.
- Following steps describe the needed action for a ST Microelectronics evaluation board and windows - adapt them to your environment.
- It is always possible to turn back to the ST-Link OB firmware with the SEGGER
STLinkReflash.exe
tool but afterwards the ST-Link Upgrade tool should be used again to get the latest version.
- Get & install STM32 ST-LINK utility
- Run from default install location
"C:\Program Files (x86)\STMicroelectronics\STM32 ST-LINKUtility\ST-LINK Utility\ST-LinkUpgrade.exe"
) - Enable checkbox
Change Type
and select radio buttonSTM32 Debug+Mass storage + VCP
. TheSTM32Debug+ VCP
wonΒ΄t be detected by Segger reflash utility.
- Check Converting ST-LINK On-Board Into a J-Link
- Use
STLinkReflash.exe
to convert NUCLEO from ST-Link on-board to J-Link on-board.STM32 Debug+ VCP
wonΒ΄t be detected by Segger reflash utility.
- Download J-Link Software and Documentation Pack and install.
- You may need to add
C:\Program Files\SEGGER\JLink
to the %PATH% variable.
- You may need to add
- Tested with NUCLEO64-STM32F030R8 evaluation board.
- For example: Compile and flash
../_test/MDK-ARM_STM32F030R8
project.- Check in ../_test/MDK-ARM_STM32F030R8/Core/Inc/triceConfig.h if
#define TRICE_RTT_CHANNEL 0
is set as output option.
- Check in ../_test/MDK-ARM_STM32F030R8/Core/Inc/triceConfig.h if
JLink.exe
is the SEGGER J-Link commander. It starts the J-Link driver/server and one can connect to it- Info found here:
- J-Link Commander can be started with different command line options for test and automation
- purposes. In the following, the command line options which are available for J-Link
- Commander are explained. All command line options are case insensitive.
- Command Explanation
- -AutoConnect Automatically start the target connect sequence
- -CommanderScript Passes a CommandFile to J-Link
- -CommandFile Passes a CommandFile to J-Link
- -Device Pre-selects the device J-Link Commander shall connect to
- -ExitOnError Commander exits after error.
- -If Pre-selects the target interface
- -IP Selects IP as host interface
- -JLinkScriptFile Passes a JLinkScriptFile to J-Link
- -JTAGConf Sets IRPre and DRPre
- -Log Sets logfile path
- -RTTTelnetPort Sets the RTT Telnetport
- -SelectEmuBySN Connects to a J-Link with a specific S/N over USB
- -SettingsFile Passes a SettingsFile to J-Link
- -Speed Starts J-Link Commander with a given initial speed
- Documentation: https://wiki.segger.com/J-Link_Commander
- If you run successful
jlink -device STM32F030R8 -if SWD -speed 4000 -autoconnect 1
the target is stopped.- To let in run you need manually execute
go
as command in the open jlink window. - To automate that create a text file named for example
jlink.go
containing thego
command:echo go > jlink.go
and do ajlink -device STM32F030R8 -if SWD -speed 4000 -autoconnect 1 -CommandFile jlink.go
- To let in run you need manually execute
- It is possible to see some output with Firefox (but not with Chrome?) for example: .
- After closing the Firefox the trice tool can connect to it too:
- Open a commandline and run:
trice log -port TCP4 -args localhost:19021
- trice output is visible
- With
h
alt andg
o inside the Jlink window the MCU can get haltes and released - It is possible in parallel to debug-step with a debugger (tested with ARM-MDK)
- Open a commandline and run:
- PLUS:
- Works reliable.
- No file interface needed.
- Trice can connect over TCP localhost:19021 and display logs over RTT channel 0.
- The open
jlink
CLI can be handy to control the target:[r]eset, [g]o. [h]alt
- No need to restart the trice tool after changed firmware download.
- MINUS:
- Uses RTT up-channel 0 and therefore RTT up-channel 0 is not usable differently.
- No down-channel usable.
- Needs a separate manual start of the
jlink
binary with CLI parameters.- I would not recommend to automate that too, because this step is needed only once after PC power on.
JLinkRTTLogger.exe
is a CLI tool and connects via the SEGGER API to the target. It is usable for writing RTT channel 0 data from target into a file.- PLUS:
- MINUS:
- Logs in a file, so the trice tool needs to read from that file.
- The trice tool can watch the output file and display the Trices: `trice log -port JLINK -args "-Device STM32F030R8 -if SWD -Speed 4000 -RTTChannel 0"
JLinkRTTClient.exe
can be used for simple text transmitting to the target, it also displays strings from target coming over channel 0. It is not used by the trice tool.- PLUS:
- Target stimulation with proprietary protocol over RTT down-channel 0 possible.
- MINUS:
- Unfortunately it cannot run separately parallel to stimulate the target with any proprietary protocol because it connects to localhost:19021 and therefore blockades the only one possible connection.
- PLUS:
JLinkRTTViewer.exe
is a GUI tool and connects via the SEGGER API to the target. It expects ASCII codes and is not used by the trice tool. The switching between the 16 possible terminals is done viaFF 00
...FF 0F
. These byte pairs can occur inside the trice data.
-
The main advantages are:
- Speed
- No
TriceTransfer()
nor any interrupt is needed in the background - No UART or other output is needed
-
This is, because automatically done by SeggerRTT. This way one can debug code as comfortable as with
printf()
but with all the TRICE advantages. Have a look here: -
Avoid trice buffering inside target and write with TRICE macro directly into the RTT buffer (direct Trice mode =
#define TRICE_MODE 0
inside triceConfig.h). -
Write the bytes per Trice directly (little time & some space overhead on target, but no changes on host side)
- Segger offers a SeggerRTT SDK which allows to use more than just channel 0 and you can develop your own tooling with it.
- The
trice -port JLINK
is ok for usage as is right now. However if you wish more comfort check here: - Question: How-to-access-multiple-RTT-channels
- "Developer pack used to write your own program for the J-Link. Please be sure you agree to the terms of the associated license found on the Licensing Information tab before purchasing this SDK. You will benefit from six months of free email support from the time that this product is ordered."
- The main Segger J-Link SDK disadvantage beside closed source and payment is: One is not allowed to distribute binaries written with the SDK. That makes it only interesting for company internal automatization.
Downloading RTT target package
from https://www.segger.com/products/debug-probes/j-link/technology/about-real-time-transfer/.- Read the manual UM08001_JLink.pdf.
- Extract
../third_party/segger.com/SEGGER_RTT_V760g.zip
to../third_party/segger.com/SEGGER_RTT
. Check for an update @ SEGGER. - Add
SEGGER_RTTI.c
to target project
-
Check OpenOCD!
- Use OpenOCD and its built-in RTT feature. OpenOCD then starts a server on localhost:17001 where it dumps all RTT messages.
-
The GoST project offers a way bypassing JLINK. Used -port STLINK instead.
-
Maybe
libusb
together withlibjaylink
offer some options too. -
Checkout https://github.com/deadsy/jaylink.
-
"C:\Program Files (x86)\SEGGER\JLink\JMem.exe"
shows a memory dump. -
Go to https://libusb.info/
- -> Downloads -> Latest Windows Binaries
- extract
libusb-1.0.23
(or later version)
libusb-1.0.23\examples\bin64> .\listdevs.exe
2109:2811 (bus 2, device 8) path: 6
1022:145f (bus 1, device 0)
1022:43d5 (bus 2, device 0)
0a12:0001 (bus 2, device 1) path: 13
1366:0105 (bus 2, device 10) path: 5
- Repeat without connected Segger JLink
libusb-1.0.23\examples\bin64> .\listdevs.exe
2109:2811 (bus 2, device 8) path: 6
1022:145f (bus 1, device 0)
1022:43d5 (bus 2, device 0)
0a12:0001 (bus 2, device 1) path: 13
- In this case
1366:0105 (bus 2, device 10) path: 5
is missing, sovid=1366
,did=0105
as example - On Windows install WSL2. The real Linux kernel is needed for full USB access.
Info: https://www.st.com/en/evaluation-tools/nucleo-f030r8.html
#define TRICE_RTT_CHANNEL 0
:- If you use a NUCLEO-F030R8 with the original ST-Link on board after firmware download enter:
trice l -p ST-LINK -args "-Device STM32F030R8 -if SWD -Speed 4000 -RTTChannel 0 -RTTSearchRanges 0x20000000_0x2000"
. After pressing the reset button output becomes visible: - It works with both ST-Link variants (with or without mass storage device.)
- Observations:
- When pressing the black reset button, you need to restart the trice tool.
- When restarting the trice tool, a target reset occurs.
- Other channel numbers than
0
seam not to work for some reason.
- These boards seem not to work reliable with RTT over J-Link on-board firmware.
- NUCLEO-G071RB
- NUCLEO_G031K8
- After flashing back the ST-LINK OB firmware with the SEGGER tool, it is recommended to use the ST tool to update the ST-LINK OB firmware. Otherwise issues could occur.
- https://www.codeinsideout.com/blog/stm32/j-link-rtt/ (A good explanation of SEGGER J-Link Realtime Transfer - Fast Debug protocol: - only suitable for ASCII transfer)
- USB over WSL2? (Maybe intersting for OpenOCD)