Difference between revisions of "J-Link RTT Viewer"

From SEGGER Wiki
Jump to: navigation, search
(--connection)
(Force Go on Connect)
 
(4 intermediate revisions by the same user not shown)
Line 36: Line 36:
 
## For TCP/IP the IP or hostname of the J-Link has to be entered.
 
## For TCP/IP the IP or hostname of the J-Link has to be entered.
 
# Select the target device to connect to. This allows J-Link to search in the known RAM of the target.
 
# Select the target device to connect to. This allows J-Link to search in the known RAM of the target.
  +
# Select if the device should be forced to be running after connect (see [[#Force Go on Connect|here]]).
 
# Select the target interface and interface speed.
 
# Select the target interface and interface speed.
 
# The RTT Control Block can be searched for fully automatically, it can be set to a fixed address or it can be searched for in one or more specific memory ranges.
 
# The RTT Control Block can be searched for fully automatically, it can be set to a fixed address or it can be searched for in one or more specific memory ranges.
 
## Please note that the RTT Control Block cannot be found automatically, if it is not placed in the RAM are specified by the J-Link DLL.<br>In such a case, the address, or RAM range has to be specified by the user.
 
## Please note that the RTT Control Block cannot be found automatically, if it is not placed in the RAM are specified by the J-Link DLL.<br>In such a case, the address, or RAM range has to be specified by the user.
  +
  +
===== Force Go on Connect =====
  +
Some devices may not be running after J-Link connects to them.
  +
Even though this is a rare case, it may happen for devices which require it e.g. to prevent the application on the device to turn off or re-assign the debug pins,
  +
which would disable the debug capabilities. However, data can only be handled by the target device while it is running, which is required for RTT.
  +
  +
To allow RTT Viewer to work in stand-alone mode for such devices too, the '''Force go on connect'' option exists.
  +
It will automatically trigger a go after a successful connect.
  +
The option has no effect, when the device is already running after connect.
   
 
==== Attach mode ====
 
==== Attach mode ====
 
By selecting ''Connection to J-Link:'' > ''Existing Session'' RTT Viewer is started in attach mode.
 
By selecting ''Connection to J-Link:'' > ''Existing Session'' RTT Viewer is started in attach mode.
 
In attach mode J-Link RTT Viewer does usually not require any additional settings, however RTT Control Block Address or Search Ranges can still be selected if required.
 
In attach mode J-Link RTT Viewer does usually not require any additional settings, however RTT Control Block Address or Search Ranges can still be selected if required.
  +
<ul>
 
For attach mode a connection to J-Link has to be opened and configured by another application like a debugger or simply [[J-Link Commander]].
+
<li>For attach mode a connection to J-Link has to be opened and configured by another application like a debugger or simply [[J-Link Commander]].</li>
  +
<li>The attach mode is especially useful when using a third party debugger or IDE working with a J-Link (e.g. Eclipse).</li>
 
  +
<li>When running multiple J-Link processes, it is possible to connect to a specific session by selecting the related TELNET port:<br>[[File:RTTViewer_ConfigDialog_SpecProcess.PNG]]<br>The TELNET-port can be determined via the [[J-Link_-_Web_control_panel#Status_&_Settings | J-Link - Web control panel]] of the J-Link DLL used by the specific process.</li>
The attach mode is especially useful when using a third party debugger or IDE working with a J-Link (e.g. Eclipse).
 
  +
</ul>
 
When running multiple J-Link processes, it is possible to connect to a specific session by selecting the related TELNET port:<br>
 
[[File:RTTViewer_ConfigDialog_SpecProcess.PNG]]
 
   
 
== The Terminal Tabs ==
 
== The Terminal Tabs ==
Line 192: Line 200:
   
 
=== --scriptfile ===
 
=== --scriptfile ===
  +
Sets the [[J-Link Script file]] to be used.
Executes a JLink command script on startup, setting options in advance (e.g. Device = AT91SAM7S256)
 
   
 
'''Syntax'''
 
'''Syntax'''
Line 439: Line 447:
 
== Troubleshooting ==
 
== Troubleshooting ==
 
# Under some circumstances, the RTT Control Block cannot be detected automatically.<br>This happens for example when the RTT Control Block is not located in the RAM address range specified in the J-Link DLL.<br>In such a case, the J-Link RTT Control Block location has to be set in the J-Link RTT Viewer's Configuration dialog, under section ''RTT Control Block''.
 
# Under some circumstances, the RTT Control Block cannot be detected automatically.<br>This happens for example when the RTT Control Block is not located in the RAM address range specified in the J-Link DLL.<br>In such a case, the J-Link RTT Control Block location has to be set in the J-Link RTT Viewer's Configuration dialog, under section ''RTT Control Block''.
# If the control block is found, but the data is still not shown in the RTT Viewer, please make sure that you use '''channel 0''' for all transmissions, as only channel 0 is supported for the terminal view.<br>'''Channel 0''' is not equal to '''Terminal 0''' (see information provided in this article).
+
# If the control block is found, but the data is still not shown in the RTT Viewer, please make sure that you use '''channel 0''' for all transmissions, as only channel 0 is supported for the terminal view.<br>'''Channel 0''' is not equal to '''Terminal 0''' (see information provided in this article). To send data to different terminals, please consider using [[RTT#SEGGER_RTT_TerminalOut()|SEGGER_RTT_TerminalOut()]].
 
# For additional troubleshooting please refer to [[RTT#Troubleshooting | RTT Troubleshooting]] article.
 
# For additional troubleshooting please refer to [[RTT#Troubleshooting | RTT Troubleshooting]] article.

Latest revision as of 08:41, 4 March 2024

J-Link RTT Viewer

J-Link RTT Viewer is a GUI application available for Windows, MacOS and Linux and can be downloaded as part of the J-Link Software and Documentation Pack. It enables you to use all features of RTT in one application. It supports:

  • Displaying terminal output of Channel 0.
  • Up to 16 virtual Terminals on Channel 0.
  • Sending text input to Channel 0.
  • Interpreting text control codes for colored text and controlling the Terminal.
  • Logging terminal data into a file.
  • Logging data on Channel 1.

J-Link RTT Viewer Startup

Make sure J-Link and target device are connected and powered up.
Start J-Link RTT Viewer by opening the executable (JLinkRTTViewer.exe/JLinkRTTViewerExe) from the installation folder of the J-Link Software or the start menu. Unless the command line parameter --autoconnect is set, the Configuration Dialog will pop up.
Configure the Connection Settings as described below and click OK.
The connection settings and all in app configuration will be saved for the next start of J-Link RTT Viewer.

J-Link RTT Viewer Configuration dialog

The J-Link RTT Viewer Configuration dialog is used to set all necessary device specifics to successfully connect and read/send RTT data from/to the target device.

J-Link RTT Viewer Config dialog

Connection Settings

J-Link RTT Viewer can be used in two modes:

  • Stand-alone, opening an own connection to J-Link and target.
  • In attach mode, connecting to an existing J-Link connection of a debugger.

Stand-alone

In stand-alone mode J-Link RTT Viewer needs to know some settings of J-Link and target device:

  1. Select USB or TCP/IP as the connection to J-Link.
    1. For USB a specific J-Link serial number can optionally be entered
    2. For TCP/IP the IP or hostname of the J-Link has to be entered.
  2. Select the target device to connect to. This allows J-Link to search in the known RAM of the target.
  3. Select if the device should be forced to be running after connect (see here).
  4. Select the target interface and interface speed.
  5. The RTT Control Block can be searched for fully automatically, it can be set to a fixed address or it can be searched for in one or more specific memory ranges.
    1. Please note that the RTT Control Block cannot be found automatically, if it is not placed in the RAM are specified by the J-Link DLL.
      In such a case, the address, or RAM range has to be specified by the user.
Force Go on Connect

Some devices may not be running after J-Link connects to them. Even though this is a rare case, it may happen for devices which require it e.g. to prevent the application on the device to turn off or re-assign the debug pins, which would disable the debug capabilities. However, data can only be handled by the target device while it is running, which is required for RTT.

To allow RTT Viewer to work in stand-alone mode for such devices too, the 'Force go on connect option exists. It will automatically trigger a go after a successful connect. The option has no effect, when the device is already running after connect.

Attach mode

By selecting Connection to J-Link: > Existing Session RTT Viewer is started in attach mode. In attach mode J-Link RTT Viewer does usually not require any additional settings, however RTT Control Block Address or Search Ranges can still be selected if required.

  • For attach mode a connection to J-Link has to be opened and configured by another application like a debugger or simply J-Link Commander.
  • The attach mode is especially useful when using a third party debugger or IDE working with a J-Link (e.g. Eclipse).
  • When running multiple J-Link processes, it is possible to connect to a specific session by selecting the related TELNET port:
    RTTViewer ConfigDialog SpecProcess.PNG
    The TELNET-port can be determined via the J-Link - Web control panel of the J-Link DLL used by the specific process.

The Terminal Tabs

J-Link RTT Viewer allows displaying the output of Channel 0 in different "virtual" Terminals. The target application can switch between terminals with SEGGER_RTT_SetTerminal() and SEGGER_RTT_TerminalOut(). J-Link RTT Viewer displays the Terminals in different tabs.

J-Link RTT Viewer example in-/output


All Terminals

The All Terminals tab displays the complete output of RTT Channel 0 and can display the user input (Check Input -> Echo input... -> Echo to "All Terminals").\n Each output line is prefixed by the Terminal it has been sent to. Additionally, output on Terminal 1 is shown in red, output on Terminals 2 - 15 in gray.

Terminal 0 - 15

Each tab Terminal 0 - Terminal 15 displays the output which has been sent to this Terminal. The Terminal tabs interpret and display Text Control Codes as sent by the application to show colored text or erase the screen.
By default, if the RTT application does not set a Terminal Id, the output is displayed in Terminal 0.
The Terminal 0 tab can additionally display the user input. (Check Input -> Echo input... -> Echo to "Terminal 0")
Each Terminal tab can be shown or hidden via the menu Terminals -> Terminals... or their respective shortcuts as described below.

Sending Input

J-Link RTT Viewer "Sending input" dialog

J-Link RTT Viewer supports sending user input to RTT Down Channel 0 which can be read by the target application with SEGGER_RTT_GetKey() and SEGGER_RTT_Read().
Input can be entered in the text box below the Terminal Tabs.
J-Link RTT Viewer can be configured to directly send each character while typing or buffer it until Enter is pressed (Menu Input -> Sending...).
In stand-alone mode J-Link RTT Viewer can retry to send input, in case the target input buffer is full, until all data could be sent to the target via Input -> Sending... -> Block if FIFO full.

Logging output

The output of Channel 0 and Channel 1 can be logged into a text file.

Terminal output (Channel 0)

The format is the same as used in the All Terminals tab.
Terminal Logging can be started via Logging -> Start Terminal Logging...

Data output (Channel 1)

Channel 1 logging can for example be used to sent instrumented event tracing data. The data log file contains header and footer and the binary data as received from the application.
Data Logging can be started via Logging -> Start Data Logging...

NOTE: Data Logging is only available in stand-alone mode.

Command line options

J-Link RTT Viewer can be configured via command line parameters. In the following, the command line options which are available for J-Link RTT Viewer are explained. All command line options are case insensitive. Short and long command names have the same syntax.

Command line option Description
-b, --bright Bright theme for GUI
-d, --device Select the connected target device
-ct, --connection Sets the connection type
-if, --interface Sets the interface type
-ip, --host The IP address of the J-Link
-s, --speed Interface speed in kHz
-sf, --scriptfile Executes a command script on start up
-sn, --serialnumber Select the J-Link with a specific S/N
-ra, --rttaddr Sets the address of the RTT control block
-rr, --rttrange Specify RTT search range
-a, --autoconnect Automatically connect to target, suppress settings dialog
-ti, --terminalindex Opens the specified terminal application start
-swt, --setwindowtitle Opens the specified terminal application start

--bright

Starts the RTT Viewer in bright theme.

Syntax

--bright

Example

JLinkRTTViewer.exe --bright

--device

Selects the device J-Link RTT Viewer shall connect to.

Syntax

--device <DeviceName>

Example

JLinkRTTViewer.exe --device STM32F103ZE

--connection

Sets the connection type. The connection to the J-Link can either be made directly over USB, IP or using an existing running session (e.g. the IDE's debug session). In case of using an existing session, no further configuration options are required.

Syntax

--connection <usb|ip|sess|localport> [<PortNo (localport only)>]

Example

JLinkRTTViewer.exe --connection ip
JLinkRTTViewer.exe --connection localport 19021

--interface

Sets the interface J-Link shall use to connect to the target. As interface types FINE, JTAG and SWD are supported.

Syntax

--interface <fine|jtag|swd>

Example

JLinkRTTViewer.exe --interface swd

--host

Enter the IP address or hostname of the J-Link. This option only applies, if connection type IP is used. Use * as <IPAddr> for a list of available J-Links in the local subnet.

Syntax

--host <IPAddr>

Example

JLinkRTTViewer.exe --host 192.168.1.17

--speed

Sets the interface speed in kHz for target communication.

Syntax

--speed <speed>

Example

JLinkRTTViewer.exe --speed 4000

--scriptfile

Sets the J-Link Script file to be used.

Syntax

--scriptfile <FilePath>

Example

JLinkRTTViewer.exe --scriptfile C:\\tmp\\<Scriptfilename>

--serialnumber

Connect to a J-Link with a specific serial number via USB. Useful if multiple J-Links are connected to the same PC and multiple instances of J-Link RTT Viewer shall run and each connects to another J-Link.

Syntax

--serialnumber <SerialNo>

Example

JLinkRTTViewer.exe --serialnumber 580011111

--rttaddr

Sets a fixed address as location of the RTT control block. Automatic searching for the RTT control block is disabled.

Syntax

--rttaddr <RTTCBAddr>

Example

JLinkRTTViewer.exe --rttaddr 0x20000000

--rttrange

Sets one or more memory ranges, where the J-Link DLL shall search for the RTT control block.

Syntax

--rttrange <RangeStart[Hex]> <RangeSize >[, <Range1Start [Hex]> <Range1Size>]>

Example

JLinkRTTViewer.exe --rttrange "20000000 400"

--autoconnect

Let J-Link RTT Viewer connect automatically to the target without showing the Connection Settings (see Connection Settings).

Syntax

--autoconnect

Example

JLinkRTTViewer.exe --autoconnect

--terminalindex

Opens the terminal with the specified index on application start
The value of index can be [0:16], with 0 == All Terminals, 1 == Terminal 0 ... 16 == Terminal 15

Syntax

--terminalindex <Index>

Example

JLinkRTTViewer.exe --terminalindex 7

--setwindowtitle

Extends the window title of the main window to <sTitle>. This makes it easier to distinguish between multiple J-Link RTT Viewer instances running at the same time. The length of the title extension is capped at 127 characters. Longer strings will be cropped after 127 characters.

Syntax

--setwindowtitle <sTitle>

Example

JLinkRTTViewer.exe --setwindowtitle "Test board #1234"

Menus and Shortcuts

The J-Link RTT Viewer has a range of options available in the menu bar.

File menu elements

Menu entry Contents Shortcut
-> Connect... Opens the connect dialog and connects to the targets F2
-> Disconnect Disconnects from the target F3
-> Exit Closes connection and exit RTT Viewer. Alt-F4

Terminals menu elements

Menu entry Contents Shortcut
-> Add next terminal Opens the next available Terminal Tab. Alt-A
-> Clear active terminal Clears the currently selected terminal tab. Alt-R
-> Close active terminal Closes the active Terminal Tab. Alt-W
-> Open Terminal on output If selected, a terminal is automatically created, if data for this terminal is received. None
-> Edit font size Opens the font size selection dialog. None
Terminals -> Terminals...
-> Terminal 0 - 15 Opens or closes the Terminal Tab. Alt-Shift-0, ..., Alt-Shift-F

Input menu elements

Menu entry Contents Shortcut
-> Clear input field Clears the input field without sending entered data. Button "Clear"
Input -> Sending...
-> Send on Input If selected, entered input will be sent directly to the target while typing. None
-> Send on Enter If selected, entered input will be sent when pressing Enter. None
-> Block if FIFO full If checked, RTT Viewer will retry to send all input to the target when the target buffer is full. None
Input -> End of line...
-> Windows format (CR+LF)
-> Unix format (LF)
-> Mac format (CR)
-> None
Selects the end of line character to be sent on Enter. None
Input -> Echo input...
-> Echo to "All Terminals" If checked, sent input will be displayed in the All Terminals Tab. None
-> Echo to "Terminal 0" If checked, sent input will be displayed in the Terminal Tab 0. None

Logging menu elements

Menu entry Contents Shortcut
-> Start Terminal logging... Starts logging terminal data to a file. F5
-> Stop Terminal logging Stops logging terminal data and closes the file. Shift-F5
-> Start Data logging... Starts logging data of Channel 1 to a file. F6
-> Stop Data logging Stops logging data and closes the file. Shift-F6
-> Channel infos... Displays information about all available RTT channels. F8

Help menu elements

Menu entry Contents Shortcut
-> About... Shows version info of RTT Viewer. F12
-> J-Link Manual... Opens the J-Link Manual PDF file. F11
-> RTT Webpage... Opens the RTT webpage. F10

Tab context menu elements

Menu entry Contents Shortcut
-> Close Terminal Closes this Terminal Tab Alt-W
-> Clear Terminal Clears the displayed output of this Terminal Tab. Alt-R

Using "virtual" Terminals in RTT

For virtual Terminals the target application needs only Up Channel 0. This is especially important on targets with low RAM.
Notes

  • If no terminal is specified, all data is sent to Terminal 0.
  • The Terminal to show all following Write, WriteString or printf outputs can be set with SEGGER_RTT_SetTerminal().
  • Output of only one string via a specific Terminal can be done with SEGGER_RTT_TerminalOut().
  • The sequences sent to change the Terminal are interpreted by J-Link RTT Viewer. Other applications like a Telnet Client will ignore them.

Using Text Control Codes

RTT allows using Text Control Codes (ANSI escape codes) to configure the display of text. J-Link RTT Viewer supports changing the text color and background color and can erase the Terminal. These Control Codes are pre-defined in the RTT application and can easily be used in the application.

Examples

Please refer to the following examples for the correct implementation of the ANSI escape codes in combination with RTT.

Example 1

SEGGER_RTT_WriteString(0,
                       RTT_CTRL_RESET"Red: " \
                       RTT_CTRL_TEXT_BRIGHT_RED"This text is red. " \
                       RTT_CTRL_TEXT_BLACK"" \
                       RTT_CTRL_BG_BRIGHT_RED"This background is red. " \
                       RTT_CTRL_RESET"Normal text again."
                      );

Example 2

SEGGER_RTT_printf(0, "%sTime:%s%s %.7d\n",
                      RTT_CTRL_RESET,
                      RTT_CTRL_BG_BRIGHT_RED,
                      RTT_CTRL_TEXT_BRIGHT_WHITE,
                      1111111
                 );
//
// Clear the terminal.
// The first line will not be shown after this command.
//
SEGGER_RTT_WriteString(0, RTT_CTRL_CLEAR);

SEGGER_RTT_printf(0, "%sTime: %s%s%.7d\n",
                      RTT_CTRL_RESET,
                      RTT_CTRL_BG_BRIGHT_RED,
                      RTT_CTRL_TEXT_BRIGHT_WHITE,
                      2222222
                 );

Using Timestamps

The J-Link RTT Viewer does not provide functionality to show host PC sided timestamps, because of the following reasons:

  • Timestamps created on host PC side (HS) do not represent the actual time the data was written to the RTT buffer on device side (DS), but the time when the data was received by the J-Link RTT Viewer.
  • The delay between writing data to the RTT buffer (DS) and receiving it via the RTT Viewer (HS) is not constant but varying.
  • In case data is written very fast to the RTT buffer (DS), multiple messages that were originally intended as single messages would be presented with one single timestamp, when received with a single data read (HS).
  • In case data is already present in the RTT buffer (DS) before the RTT Viewer connects to it, all this data would have one timestamp (HS), even when they were not written to the buffer at the same time originally.

Connclusion: The correct way to implement timestamps for RTT is on target side, as PC sided timestamps do not represent the real, on target behavior.

Example

To create timestamps for all log messages reliably, a wrapper function can be used:

/*********************************************************************
*
*       _WriteStringWTS()
*
*  Function description
*    Example wrapper function for SEGGER_RTT_WriteString(), adding a Timestamp.
*/
static unsigned _WriteStringWTS(unsigned BufferIndex, const char* s) {
  const char* sTimestamp;

  sTimestamp = _GetTimestamp();                    // Creates a timestamp string of desired format (e.g. "MM:ss.SSSS - ", since program start)
  SEGGER_RTT_WriteString(BufferIndex, sTimestamp); // Write current timestamp
  return SEGGER_RTT_WriteString(BufferIndex, s);   // Write actual data
}

Troubleshooting

  1. Under some circumstances, the RTT Control Block cannot be detected automatically.
    This happens for example when the RTT Control Block is not located in the RAM address range specified in the J-Link DLL.
    In such a case, the J-Link RTT Control Block location has to be set in the J-Link RTT Viewer's Configuration dialog, under section RTT Control Block.
  2. If the control block is found, but the data is still not shown in the RTT Viewer, please make sure that you use channel 0 for all transmissions, as only channel 0 is supported for the terminal view.
    Channel 0 is not equal to Terminal 0 (see information provided in this article). To send data to different terminals, please consider using SEGGER_RTT_TerminalOut().
  3. For additional troubleshooting please refer to RTT Troubleshooting article.