SystemView

Principle

SystemView is a real-time recording and visualization tool for embedded systems that reveals the actual runtime behavior of an application, going far deeper than the system insights provided by debuggers. This is particularly effective when developing and working with complex embedded systems comprising multiple threads and interrupts: SystemView can ensure a system performs as designed, can track down inefficiencies, and show unintended interactions and resource conflicts, with a focus on the details of every single system tick.

A specific SystemView extension made by MicroEJ allows to trace the OS tasks and the MicroEJ Java threads at the same time. This chapter explains how to add SystemView feature to a platform and set it up.

A SystemView support is provided to use the software with a MicroEJ system. This documentation shows how to set up your BSP and your Java application.

Note

SystemView support for MicroEJ is compatible with FreeRTOS 9 and FreeRTOS 10.

Note

This SystemView section has been written for SystemView version V2.52a. Later versions may or may not work, and may need modification to the following steps.

Here is an example when analyzing the Demo Widget running on the STM32F7508-DK platform.

SystemView analysis of DemoWidget on STM32F7508 Platform

References

Installation

SystemView installation consists of adding several items in the BSP. The following steps describe them, and they must be performed in the right order. If SystemView support is already available in the BSP, apply only modifications made by MicroEJ on SystemView files and SystemView for FreeRTOS files to enable MicroEJ Java threads monitoring.

  1. Download and install SystemView V2.52a: http://segger.com/downloads/systemview/.

  2. Apply SystemView for FreeRTOS patch as described in the documentation (https://www.segger.com/downloads/jlink/UM08027); the patch is available in the installation folder SEGGER\SystemView\Src\Sample\FreeRTOSVxx.

Note

If you are using FreeRTOS V10.2.0, use the patch located here: https://forum.segger.com/index.php/Thread/6158-SOLVED-SystemView-Kernelpatch-for-FreeRTOS-10-2-0/?s=add3b0f6a33159b9c4b602da0082475afeceb89a

  1. Check if the patch disabled SystemView systick events in port.c, if not remove these lines manually:

Disable systick events (too many events are generated).

  1. Add SEGGER\SystemView\Src\Sample\FreeRTOSVxx\Config\SEGGER_SYSVIEW_Config_FreeRTOS.c in your BSP.

This file can be modified to fit your system configuration:

  • Update SYSVIEW_APP_NAME, SYSVIEW_DEVICE_NAME, and SYSVIEW_RAM_BASE defines to fit your system information.

  • To add MicroEJ Java threads management in SystemView tasks initialization:

    • Add these includes #include "task.h", #include "LLMJVM_MONITOR_SYSVIEW.h", #include "LLTRACE_SYSVIEW_configuration.h", #include "SEGGER_SYSVIEW_configuration.h" and the include that declares the external variable pvMEJCoreEngineTask. pvMEJCoreEngineTask must be the FreeRTOS task handle used to create the MicroEJ Core Engine task. Initializes this variable at NULL before the call of the FreeRTOS scheduler.

    • In function _cbSendSystemDesc(void), add this instruction: SEGGER_SYSVIEW_SendSysDesc("N="SYSVIEW_APP_NAME",D="SYSVIEW_DEVICE_NAME",O=FreeRTOS"); before SEGGER_SYSVIEW_SendSysDesc("I#15=SysTick");.

    • Replace the Global function section with this code:

    /*********************************************************************
*
*       Global functions
*
**********************************************************************
*/

SEGGER_SYSVIEW_OS_API SYSVIEW_MICROEJ_X_OS_TraceAPI;

static void SYSVIEW_MICROEJ_X_OS_SendTaskList(void){
   SYSVIEW_X_OS_TraceAPI.pfSendTaskList();

// The strategy to send tasks info is different in post mortem and live analysis.
#if (1 == SEGGER_SYSVIEW_POST_MORTEM_MODE)
   /**
   * POST MORTEM analysis
   *
   * Using the post mortem analysis, FreeRTOS tasks regularly call the SYSVIEW_MICROEJ_X_OS_SendTaskList() function when
   * a packet (systemview event) is sent to the SEGGER circular buffer. It is necessary because the information of tasks
   * must be regularly uploaded in the circular buffer in order to provide a valid analysis at any moment.
   * Consequently, we only allow to call LLMJVM_MONITOR_SYSTEMVIEW_send_task_list() when the current task is the MicroEJ Core Engine.
   */

   /* Obtain the handle of the current task. */
   TaskHandle_t xHandle = xTaskGetCurrentTaskHandle();
   configASSERT( xHandle ); // Check the handle is not NULL.

   // Check if the current task handle is the MicroEJ Core Engine task handle. pvMEJCoreEngineTask is an external variable.
   if( xHandle == pvMEJCoreEngineTask){
      // Launched by the MicroEJ Core Engine, we execute LLMJVM_MONITOR_SYSTEMVIEW_send_task_list()
      LLMJVM_MONITOR_SYSTEMVIEW_send_task_list();
   }
#else
   /**
   * LIVE analysis
   *
   * Using the live analysis, the call of SYSVIEW_MICROEJ_X_OS_SendTaskList() is triggered by
   * the SystemView Software through the J-Link probe. Consequently, the MicroEJ Core Engine task will never call
   * the function LLMJVM_MONITOR_SYSTEMVIEW_send_task_list(). However, if the MicroEJ Core Engine task is created,
   * the function must be called LLMJVM_MONITOR_SYSTEMVIEW_send_task_list().
   */
   // Check if the MicroEJ Core Engine task handle is not NULL. pvMEJCoreEngineTask is an external variable.
   if( NULL != pvMEJCoreEngineTask){
      // The MicroEJ Core Engine task is running, we execute LLMJVM_MONITOR_SYSTEMVIEW_send_task_list()
      LLMJVM_MONITOR_SYSTEMVIEW_send_task_list();
   }
#endif
}

void SEGGER_SYSVIEW_Conf(void) {
   SYSVIEW_MICROEJ_X_OS_TraceAPI.pfGetTime = SYSVIEW_X_OS_TraceAPI.pfGetTime;
   SYSVIEW_MICROEJ_X_OS_TraceAPI.pfSendTaskList = SYSVIEW_MICROEJ_X_OS_SendTaskList;

   SEGGER_SYSVIEW_Init(SYSVIEW_TIMESTAMP_FREQ, SYSVIEW_CPU_FREQ, &SYSVIEW_MICROEJ_X_OS_TraceAPI, _cbSendSystemDesc);
   SEGGER_SYSVIEW_SetRAMBase(SYSVIEW_RAM_BASE);
}

  1. Add in your BSP the MicroEJ C module files for SystemView: com.microej.clibrary.thirdparty#systemview (or check the differences between pre-installed SystemView and C files provided by this module)

  2. Add in your BSP the MicroEJ C module files for SystemView FreeRTOS support (or check the differences between pre-installed SystemView and C files provided by this module)

  3. Install the Abstraction Layer implementation of the Java Trace API for SystemView by adding C module files in your BSP: com.microej.clibrary.llimpl#trace-systemview

  4. Make FreeRTOS compatible with SystemView: open FreeRTOSConfig.h and:

    • add #define INCLUDE_xTaskGetIdleTaskHandle 1

    • add #define INCLUDE_pxTaskGetStackStart 1

    • add #define INCLUDE_uxTaskPriorityGet 1

    • comment the line #define traceTASK_SWITCHED_OUT() if defined

    • comment the line #define traceTASK_SWITCHED_IN() if defined

    • add #include "SEGGER_SYSVIEW_FreeRTOS.h" at the end of the file

  5. Enable SystemView on startup (before creating the first OS task): call SEGGER_SYSVIEW_Conf();. The following include directive is required: #include "SEGGER_SYSVIEW.h".

  6. Print the RTT block address to the serial port on startup: printf("SEGGER_RTT block address: %p\n", &(_SEGGER_RTT));. The following include directive is required: #include "SEGGER_RTT.h".

Note

This is useful if SystemView does not automatically find the RTT block address. See section RTT Control Block Not Found for more details.

Note

You may also find the RTT block address in RAM by searching _SEGGER_RTT in the .map file generated with the firmware binary.

  1. Add a call to SEGGER_SYSVIEW_setMicroJVMTask((U32)pvCreatedTask); just after creating the OS task to register the MicroEJ Core Engine OS task. The handler to give is the one filled by the xTaskCreate function.

  2. Copy the file /YourPlatformProject-bsp/projects/microej/trace/systemview/SYSVIEW_MicroEJ.txt to the SystemView installation path, such as SEGGER/SystemView_V252a/Description/. If you use MicroUI traces, you can also copy the file in the section Debug Traces

MicroEJ Core Engine OS Task

The MicroEJ Core Engine task is the OS task that executes MicroEJ Java threads. Once it is started (by calling SNI_startVM), it executes the initialization code and rapidly starts to execute the MicroEJ Application main thread. At that time, the events produced by this OS task (context switch, semaphores, etc.) are dispatched to the current MicroEJ Java thread. Consequently, this OS task is useless when the MicroEJ Application is running.

SystemView for MicroEJ disables the visibility of this OS task when the MicroEJ Application is running. It simplifies the SystemView client debugging.

OS Tasks and Java Threads Names

To make a distinction between the OS tasks and the MicroEJ Java threads, a prefix is added to the OS tasks names ([OS]) and the Java threads names ([MEJ]).

OS and Thread Names

OS Tasks and Java Threads Names

Note

SystemView limits the number of characters to 32. The prefix length is included in these 32 characters; consequently, the end of the original OS task or Java thread name can be cropped.

OS Tasks and Java Threads Priorities

SystemView lists the OS tasks and Java threads according to their priorities. However, the priority notion does not have the same signification when talking about OS tasks or Java threads: a Java thread priority depends on the MicroEJ Core Engine OS task priority.

As a consequence, a Java thread with the priority 5 may not appear between an OS task with the priority 4 and another OS task with priority 6:

  • if the MicroEJ Core Engine OS task priority is 3, the Java thread must appear below an OS task with priority 4.

  • if the MicroEJ Core Engine OS task priority is 7, the Java thread must appear above an OS task with priority 6.

To keep a consistent line ordering in SystemView, the priorities sent to the SystemView client respect the following rules:

  • OS task: priority_sent = task_priority * 100.

  • MicroEJ Java thread: priority_sent = MicroJvm_task_priority * 100 + thread_priority.

Use

MicroEJ Architecture can generate specific events that allow monitoring of current Java thread, Java exceptions, Java allocations, … as well as custom application events. Please refer to the Event Tracing section.

To enable events recording, refer to the Event Recording section to configure the required Application Options.

Troubleshooting

SystemView doesn’t see any activity in MicroEJ Tasks

You have to enable runtime traces of your Java application.

  • In Run > Run configuration, select your Java application launcher.

  • Then, go to Configuration tab > Runtime > Trace.

  • Finally, check checkboxes Enable execution traces and Start execution traces automatically as shown in the picture below.

  • Rebuild your firmware with the new Java application version, which should fix the issue.

Enable traces of the Java application.

You may only check the first checkbox when you know when you want to start the trace recording. For more information, please refer to the Event Recording section to configure the required Application Options.

OVERFLOW Events in SystemView

Depending on the application, OVERFLOW events can be seen in System View. To mitigate this problem, the default SEGGER_SYSVIEW_RTT_BUFFER_SIZE can be increased from the default 1kB to a more appropriate size of 4kB. Still, if OVERFLOW events are still visible, the user can further increase this configuration found in /YourPlatformProject-bsp/projects/microej/thirdparty/systemview/inc/SEGGER_SYSVIEW_configuration.h.

RTT Control Block Not Found

RTT Block not found.

  • Get the RTT block address from the standard output by resetting the board (it is printed at the beginning of the firmware program),

  • In SystemView, select Target > Start recording,

  • In RTT Control Block Detection, select Address and put the address retrieved. You can also try with Search Range option.

RTT block found by SystemView but no traces displayed

  • Be sure that your MCU is running. The BSP may use semi-hosting traces that block the MCU execution if the application is running out of a Debug session.

  • You can check the state of the MCU using J-Link tools such as J-Link Commander and Ozone to start a Debug session.

Bus hardfault when running SystemView without Java Virtual Machine (JVM)

The function LLMJVM_MONITOR_SYSTEMVIEW_send_task_list(); triggers a Bus Hardfault when no JVM is launched. To solve this issue, comment this function call out in SEGGER_SYSVIEW_Config_FreeRTOS.c when you run SystemView without launching the JVM.