UM08028 J-Scope

From SEGGER Wiki
Revision as of 14:10, 16 September 2021 by Matthias (talk | contribs) (Technology used)
Jump to: navigation, search

Introduction

The following chapter introduces J-Scope, highlights some of its features and gives a beginners guide on how to use it.

What is J-Scope?

J-Scope is a free-of-charge software to analyze and visualize data on a micro-controller in real-time, while the target is running. J-Flash requires a J-Link / Flasher as an interface to the target hardware.

Technology used

Sampling can be done using either SEGGER High-Speed-Sampling (HSS) or SEGGER Real Time Transfer (RTT) technology. Both technologies are available to all MCUs that provide background memory access. SEGGER HSS can be used without any further preparation. SEGGER RTT enables faster sampling speeds, however this requires instrumentation of the target application as described in RTT: Instrumenting an application to use it with J-Scope.

UI Overview

The symbol selection dialog is used for HSS projects. All symbols that are found in a given .elf file are displayed in this dialog.

Main Window

J-Scope main window

The main window includes the toolbar, grapharea, symbol table and status bar.

Toolbar

J-Scope toolbar

The toolbar contains has the following controls:

  • JScope Sampling.png Sampling control button group
    • JScope Sampling Start.pngJScope Sampling Pause.png Start/Pause sampling: Starts/pauses the sampling of all selected symbols. When paused, all incoming samples are discarded. When starting a sampling session and sampling was previously stopped, all samples of the prior session are discarded.
    • JScope Sampling Stop.png Stop sampling: Fully stops a sampling session.
  • JScope Target.png Target control button group
    • JScope Target Go.pngJScope Target Halt.png Go/Halt target device: Sends the Go/Halt command to the target device.
    • JScope Target Reset.png Reset target device: Resets the target device.
  • JScope XResControls.png X-Resolution controls (Zoom)
    • JScope XResControls Increase.png Increase X-Resolution (Zoom in): Increases the X-Resolution in predefined steps
    • JScope XResControls Decrease.png Decrease X-Resolution (Zoom out): Decreases the X-Resolution in predefined steps
    • JScope XResControls Select.png Select X-Resolution: Directly select the X-Resolution in seconds/Div
  • JScope TargetFPS.png Target FPS: Select the desired update rate of the UI.
  • JScope Autoscroll.png Autoscroll: If checked, the graph will automatically scroll as soon as it hits the edge of the graph area.
  • JScope Trigger.png Trigger control button group
    • JScope Trigger Rising.png Trigger on rising edge: Sampling is triggered when a rising edge is detected.
    • JScope Trigger Falling.png Trigger on falling edge: Sampling is triggered when a falling edge is detected.
    • JScope Trigger Both.png Trigger on both rising and falling edge: Sampling is triggered when a rising or falling edge is detected.
    • JScope Trigger Symbol.png Trigger symbol selection: The symbol for which the trigger condition is active.
    • JScope Trigger Threshold.png Trigger threshold: The threshold that which a rising/falling edge muss cross.

Graph area

J-Scope graph area

The graph area displays the graphs of the sampled symbols. By clicking and dragging, the user can move the displayed graphs to the left/right. The graph area also contains the following UI elements:

  • JScope Graph YControl.png
    Graph Y-Control: Each graph has a Y-Control in its corresponding color. By clicking and dragging the Y-Control, the user can adjust the Y-Offset of the graphs.
  • JScope Graph Cursor.png
    Cursor: The cursor follows the mouse cursor.
    • JScope Graph CursorTooltip.png
      Cursor tooltip: Displays the value of the sample that is at the current cursor position.

Symbol table

J-Scope symbol table

Each column of symbol table displays relevant data of each selected symbol. The columns are:

  • Color: The color of the symbols graph. By clicking the color, the user can choose another color.
    • JScope SymbolTable AddSymbol.png When using HSS, the last row of the color column contains the "Add symbol" button. This opens the symbol selection and lets the user select other symbols.
  • Name: The name of the symbol. Note: When using RTT, the symbols actual name is not known.
  • Address: The symbols hexadecimal memory address.
  • Size: The size in bytes of the symbol.
  • Type: The symbols type.
  • Value: The value of the symbol at the current cursor position.
  • Min: The lowest sampled value.
  • Max: The highest sampled value.
  • Moving average: the average of all sampled values.
  • Y Resolution: The resolution per div in Y direction. Note: One div is defined as 100px (The same size as the black background squares)
  • Y Offset: The amount of pixels the graph is offset in Y direction from the X-Axis.

Symbol context menu

Symbol context menu

Right-clicking a symbol shows a corresponding context menu. Here the user can select the following options:

  • Show: Shows/Hides the graph of the symbol. The symbol will continue to be sampled.
  • Y-Offset up: Moves the graph up by 10px relativ to the X-Axis.
  • Y-Offset down: Moves the graph down by 10px relativ to the X-Axis.
  • Y-Resolution up: Increases the resolution in Y direction.
  • Y-Resolution down: Decreases the resolution in Y direction.
  • Draw Line: If checked, the sample data for this graph is drawn in the form of lines. If unchecked, points are drawn.
  • Remove Symbol: Removes the symbol from the selected symbols.


Status bar

J-Scope status bar

The status bar holds the following information:

  • The current sampling rate, measured in samples per second.
  • The buffer size and usage
  • The current FPS

Getting started guide

General notes

In this article two different example projects are used as a guide through J-Scope: One for using HSS and one for using RTT. If you are new to J-Scope, you might want to download those projects and to try it yourself. The example projects use SEGGER Embedded Studio and are set up for STM32F407VE devices.

Preparation

Before starting J-Scope make sure the target is running the application. The application can either be downloaded using J-Flash, the J-Link Commander or it can be launched from within an IDE. Start J-Scope by double-clicking on the executable. The welcome dialog appears.

J-Scope welcome dialog

Select “New project” and press OK. The J-Scope Configuration Dialog will open.

Connecting to J-Link

If J-Scope is used in standalone mode, using a dedicated connection to J-Link, choose “USB” or “TCP/IP” as connection type and optionally enter the serial number or the IP address of the J-Link to connect to a specific J-Link.

Asynchronous Mode (HSS)

HSS mode works by sampling memory locations in regular intervals. Therefore the sample rate and an elf-file are mandatory. The ELF file is used to determine the memory addresses of the sampled symbols. It is good practice to declare the symbols “volatile” in order to have them written to the memory as soon as possible.

J-Scope HSS configuration

To use HSS, select your target device and elf-file and click OK. The Symbol Selection Dialog will open.

J-Scope symbol selection dialog

Select the symbols of your application you want to watch and analyze. You can use the search input at the bottom to quickly search for a symbol name, type or address. To select array elements, enter the array index you want to see. For multidimensional arrays, seperate the dimension indices by dots, commas or spaces.

Click OK to finalize the setup.

Synchronous Mode (RTT)

J-Scope RTT configuration

In order to use RTT mode, RTT has to be implemented in the target application. See RTT: Instrumenting an application to use it with J-Scope for more information about the usage of RTT. The data being sampled is determined by the target application and cannot be altered by J-Scope on PC-side. Neither elf-file nor symbol selection is required or available in the RTT mode. After clicking on OK J-Scope will search for a RTT control block and add the found symbols to the symbols view.

Start sampling

From here on the behaviour of HSS and RTT projects do not differ by much. The example will continue with the HSS project.

Data sampling can be started via the JScope Sampling Start.png button in the sampling group on the tool bar. On start of sampling, the connection to the J-Link or to the running session will be established automatically. Sampling can be paused with the JScope Sampling Pause.png button. When paused, all incoming data samples are discarded.

Using trigger conditions

JScope TriggerConditions.png

With trigger conditions it is possible to only start recording samples after certain conditions are met. The parameters for the trigger conditions are:

  • Rising edge/falling edge or both: Trigger conditions are met on rising edge/falling edge or both. If none are selected, trigger conditions are disabled and sampling starts immediately.
  • Symbol: The symbol for which the trigger condition must be true.
  • Threshold: The threshold which the edge has to pass through for the condition to trigger.

In the example pictured above, sampling only starts after a rising edge passing through the threshold of 30000 on the symbol "sin" is detected.

Project Management

The project configuration, which are the J-Link connection settings, the elf-application file and the configuration of the selected symbols can be saved to a J-Scope project file (.jscope). J-Scope projects can be used for further sessions and exchanged between different users. To open a project file, the user can either select “Open Project” in the startup dialog or open a project file in J-Scope using “Open Project…” within the “File” menu.

Exporting Sampled Data

Export to CSV

The sampled data which is currently in the buffer can be exported into CSV format, to be opened and analyzed by other tools, for example spreadsheet programs like Microsoft Excel, Apple Numbers or LibreOffice Calc, by choosing “File”  → “Export Data…”

General concepts / behavior of J-Scope

  • The sample buffer acts like a circular buffer. If the buffer is full, each new entry overwrites the oldest data.
  • If no timestamps are provided in RTT mode, J-Scope will number the incoming packets in order of arrival.

Limits of J-Scope

J-Scope does not limit the sampling speed or number of variables sampled. Information about the capabilities of a J-Link are provided on the SEGGER website. HSS' limits on number of variables and sampling speed are described on the SEGGER J-Scope web page (Section Model comparison).

Information on speed limitations depending on J-Link model, debug interface speed and RTT buffer size are available on the SEGGER RTT web page (Section Performance).

Further limitations may be caused by the OS or USB implementation of the host PC. J-Link debug probes with Ethernet connectivity can be used with J-Scope in order to allow to achieve speeds beyond the limits introduced by USB.

RTT: Instrumenting an application to use it with J-Scope

Preparation

First of all, SEGGER RTT needs to be included in the target application. The source files and manual of RTT are part of the SEGGGER J-Link Software and Documentation Package. In RTT mode, all data is provided directly by the target application. The target application is responsible for data integrity and providing a reliable time base, if a timestamp is required.

Main concept

The sampled data and its format are given by the target application. This data format is announced to J-Scope by naming the RTT channel. The naming convention is stated below. Once the target application has collected all data needed for a packet, it writes this packet using SEGGER_RTT_Write() to the RTT channel.

RTT channel naming convention

J-Scope searches for the first RTT channel named JScope_FORMAT, where FORMAT defines the format of the data written to the buffer by the target application.

  • All variable identifiers consist of a type identifier and a size indication (in bytes).
  • The data inside a packet has to be in same order as declared in FORMAT.
  • If a timestamp is provided, it needs to be declared as first variable.
Type Supported Sizes Note
t 4 Indicates that every packet is preceded by a 32bit value containing a timestamp in µs
b 1 Specifies a boolean value
f 4 Specifies a 32bit floating point value
i 1,2,4 Specifies a signed 8-, 16- or 32bit value
u 1,2,4 Specifies a unsigned 8-, 16- or 32bit value

Naming Examples

JScope_t4u1i4 Specifies that the data packets are headed by a 32bit time value, followed by an unsigned char and a signed int
JScope_u4i1JScope_u4i1 Specifies that the data packets contain an unsigned int, followed by a signed char

Workflow examples

  • The user wants to sample a signed int, an unsigned int and a signed char
  • The user wants to provide a timestamp.
  • Accordingly, a RTT channel is named JScope_t4i4u4i1
  • Depending on the use case, sampling for example is done on a timer or condition

Case I

  • For this example, the user decides that sampling should be done every 100µs
  • The users adds a time based interrupt which occurs every 100µs. The respective ISR collects the necessary data and the current timestamp.
  • Afterwards, the ISR calls SEGGER_RTT_Write()

Case II

  • In an other use case, the user may decide that sampling should be done once a specific function is called.
  • The user adds a sub-function call to this function. The sub-function prepares the data, which either can be passed as a parameter or can be available in a global scope, and writes it to the RTT Buffer using SEGGER_RTT_Write().

Policies in RTT mode

  • RTT channel name and data format must not be changed during a sampling session.
  • The RTT channel name must be set accordingly to the data format.
  • Only full packets according to the data format declared by the RTT channel name may be written to the RTT channel.
  • RTT packets must be sent in order.
  • RTT mode should be NO_BLOCK_SKIP or BLOCK_IF_FIFO_FULL.

Example code

Below is a short example code that initializes the RTT buffer and writes two values into it:

  • One unsinged int alternating between 0 and 100
  • One singed int alternating between 0 and -100
#include "SEGGER_RTT.h"

int main(void) {
  char JS_RTT_UpBuffer[4096];    // J-Scope RTT Buffer
  int  JS_RTT_Channel = 1;       // J-Scope RTT Channel
  int i;
  //
  // Configure J-Scope RTT buffer for one unsigned int and one signed int
  //
  SEGGER_RTT_ConfigUpBuffer(JS_RTT_Channel, "JScope_U4I4", &JS_RTT_UpBuffer[0], sizeof(JS_RTT_UpBuffer), SEGGER_RTT_MODE_BLOCK_IF_FIFO_FULL);
  //
  // Define RTT block structure
  //
  #pragma pack(push, 1)
  struct {
    unsigned int vU32;
    signed   int vI32;
  } acValBuffer;
  #pragma pack(pop)
    while (1) {
    //
    // Prepare data
    //
    if (i > 0) {
      acValBuffer.vU32 =  100;
      acValBuffer.vI32 = -100;
      i = 0;
    } else {
      acValBuffer.vU32 = 0;
      acValBuffer.vI32 = 0;
      i++;
    }
    //
    // Send data over RTT channel
    //
    SEGGER_RTT_Write(JS_RTT_Channel, &acValBuffer, sizeof(acValBuffer));    
  }
}

Example project

The following example project was created with the SEGGER Embedded Studio project wizard and runs out-of-the-box on the STM32F407VE. It writes three sinus values into a RTT buffer.