How to use SystemView with embOS

This wiki article describes how to use SystemView with embOS. For general information about SystemView and other interface options refer to the SystemView Wiki or User Guide.

Supported embOS

SystemView support is included in embOS since embOS version 4.12a. It allows to display and record application and operating-system execution. Any embOS library mode which includes the API embOS trace feature has SystemView support enabled by default:

Name / Define	SystemView Support
OS_LIBMODE_XR
OS_LIBMODE_R
OS_LIBMODE_S
OS_LIBMODE_SP	●
OS_LIBMODE_D
OS_LIBMODE_DP	●
OS_LIBMODE_DT	●
OS_LIBMODE_SAFE	●

Additionally, embOS source code projects can be individually configured for SystemView support. Either by adding OS_SUPPORT_TRACE_API=1 to your preprocessor settings or including the definition in source code e.g. in OS_Config.h. embOS sample projects come with a pre-setup SystemView interface in debug configuration.

Note: SystemView does not share the same communication interface with embOSView and such has to be setup separately.

Adding SystemView to an embOS project

If you want to add SystemView to your existing embOS project several adaptions are necessary. The following descriptions are based on a Cortex-M4 core. For deviating project structures each step has to be individually applied.

Get SystemView target files

For guaranteed compatibility use the SystemView target files delivered with a suitable embOS port sample project from the embOS download page. Alternatively use the SystemView target files from the SystemView download page.

Add SystemView default target files to the SEGGER folder in your project

• SEGGER_RTT.c
• SEGGER_RTT.h
• SEGGER_RTT_Conf.h
• SEGGER_SYSVIEW.c
• SEGGER_SYSVIEW.h
• SEGGER_SYSVIEW_ConfDefaults.h
• SEGGER_SYSVIEW_embOS.c
• SEGGER_SYSVIEW_embos.h
• SEGGER_SYSVIEW_Int.h

Add SystemView device specific target files to the SEGGER folder in your project

• SYSVIEW_Conf.h
• SEGGER_RTT_ASM_ARMv7M.S (ARMv7-M only)

Call SEGGER_SYSVIEW_Conf()

SEGGER_SYSVIEW_Conf() configures everything necessary for SystemView to function. By default the recording does not start until a connection to the host application is established. For detailed information about the start options refer to the SystemView Wiki. Examplary you can add SEGGER_SYSVIEW_Conf() after the clock and SystTick initialization in OS_InitHW() in RTOSInit_<Device>.c:

 1 void OS_InitHW(void) {
 2 /* 
 3  * ... Clock initialization ...
 4  */
 5 #if (OS_SUPPORT_TRACE_API != 0)
 6   SEGGER_SYSVIEW_Conf();
 7 #endif
 8 /* 
 9  * ...
10  */
11 }

Event timestamp for SystemView

To provide event timestamps to SystemView the target must supply a tick base. If available, Cortex-M devices use the integrated Data Watchpoint and Trace Unit (DWT) cycle counter which is configured by the SystemView target application. With SEGGER_SYSVIEW_DWT_IS_ENABLED() the SystemView target application either uses the DWT or increments SEGGER_SYSVIEW_TickCnt depending on DWT availability. This allows a generic implementation to increment the SEGGER_SYSVIEW_TickCnt for all Cortex-M devices:

 1 void SysTick_Handler(void) {
 2 #if (OS_SUPPORT_TRACE_API != 0)
 3   if (SEGGER_SYSVIEW_DWT_IS_ENABLED() == 0u) {
 4     SEGGER_SYSVIEW_TickCnt++;
 5   }
 6 #endif
 7   OS_INT_EnterNestable();
 8   OS_TICK_Handle();
 9   /*
10    * ...
11    */
12   OS_INT_LeaveNestable();
13 }

SEGGER_SYSVIEW_X_GetTimestamp() implementation

Architectures and cores without DWT need an individual implementation of SEGGER_SYSVIEW_X_GetTimestamp() in SEGGER_SYSVIEW_Config_embOS_<Device>.c. SEGGER offers tested configuration files for devices to enable SystemView with embOS. Currently configuration files for the following devices are available:

Device / Core	Filename
Generic ARM Cortex-M0, M0+, M1	SEGGER_SYSVIEW_Config_embOS_CM0.c
Generic ARM Cortex M3, M4, M7, M33, M55	SEGGER_SYSVIEW_Config_embOS.c
Generic cores with ARMv7-A and ARMv7-R architecture with PMU	SEGGER_SYSVIEW_Config_embOS_ARMv7_PMU.c
NXP Semiconductors i.MX6 family	SEGGER_SYSVIEW_Config_embOS_iMX6.c
Analog Devices MAX3263x family	SEGGER_SYSVIEW_Config_embOS_MAX3263x.c
Nordic Semiconductor nRF51822	SEGGER_SYSVIEW_Config_embOS_nRF51822.c
Generic RISC-V cores	SEGGER_SYSVIEW_Config_embOS_RISCV.c
Generic Renesas RX devices	SEGGER_SYSVIEW_Config_embOS_RX.c
embOS Windows Simulator	SEGGER_SYSVIEW_Config_embOS_Win32.c

Cortex-A MMU specifics

For SystemView with its underlaying SEGGER Real Time Transfer (RTT) background memory accesses are performed. Regarding the presence of a Memory Management Unit (MMU) the RTT control block must be placed in non-cacheable and non writeable memory. For more information refer to the RTT Wiki. As an example the following shows the memory and MMU configuration for a Xilinx Zynq 7000. The implementation can be found in the __low_level_init() function in $PROJ_DIR$\Setup\RTOSInit_<Device>.c:

1 OS_INTERWORK int __low_level_init(void) {
2 [...] 
3   //                                         Mode                                Permissions            Execute Never             VAddr  PAddr  Size[MB]
4   OS_ARM_MMU_AddTTEntries(_TranslationTable, OS_ARM_CACHEMODE_WRITE_BACK_ALLOC | OS_ARM_MMU_READWRITE,                            0x000, 0x000, 0x001);  // 256 KB iRAM, needs to be write back allocate on Zynq since iRAM is very slow (23 cycles)
5   OS_ARM_MMU_AddTTEntries(_TranslationTable, OS_ARM_CACHEMODE_NON_CACHEABLE    | OS_ARM_MMU_READWRITE,                            0xFB1, 0x000, 0x001);  // Mapped to 256 KB iRAM @ address 0x0. Non-cacheable Normal memory. Necessary for RTT.
6 [...]
7 }

Also make sure SEGGER_RTT_UNCACHED_OFF in SEGGER_RTT_Conf.h is set accordingly to your MMU settings:

1 //
2 // Take in and set to correct values for Cortex-A systems with CPU cache
3 //
4 #define SEGGER_RTT_CPU_CACHE_LINE_SIZE            (32)          // Largest cache line size (in bytes) in the current system
5 #define SEGGER_RTT_UNCACHED_OFF                   (0xFB100000)  // Address alias where RTT CB and buffers can be accessed uncached

Troubleshooting

If you have trouble getting SystemView to work with embOS in your setup, please try the following:

• Make sure the target connection is configured correctly.
  • Choose Target->Recorder Configuration and setup the recorder interface

If the RTT control block can not be found try to address it manually.

• Find the address of the symbol _SEGGER_RTT which is the RTT control block. Either look at the linker map file or debug the project.
• Use the identified address in the RTT Control Block Detection settings.

Hint: Make sure your application does not interfere with SystemView by testing your project with embOS sample applications or Board Support Packages distributed with embOS ports.

For any other issues refer to the Troubleshooting chapter of RTT Wiki or SystemView Wiki.