How to use SystemView Heap Monitoring

Intro

This document explains how to use the SystemView heap functionality by adapting the existing code in a least intrusive way. A downloadable Embedded Studio project illustrating these techniques is provided too. Although having read the SystemView manual is not a prerequisite for understanding this tutorial, it is highly recommended to consult it (and the SEGGER Linker Manual) to obtain a deeper understanding on the subject, and especially the SEGGER_SYSVIEW_Heap* APIs.

Initializing the SystemView

The SEGGER_SYSVIEW_Init function must be called on the target prior to connecting SystemView with it and executing any other SystemView APIs. In our case it is called through the function SEGGER_SYSVIEW_Conf which is part of the HW initialization functionality defined in the function OS_InitHW. Please consult the SystemView manual and the attached example for getting more details.

SystemView Heap APIs

To provide the heap usage data to SystemView, the following APIs must be used:

• SEGGER_SYSVIEW_HeapDefine : Describes the internal heap organization. The heap memory can be organized in many different ways on embedded systems, therefore the specifics of the one used in the concrete case must be provided by using this function. Taking a look into the linker script file and using some of the symbols it defines will most likely be needed too (e.g. __heap_start__ and __heap_size__ in the example project). This function must be called prior to using any SystemView heap APIs, therefore it is called as part of the callback argument of the SEGGER_SYSVIEW_Init function. Please consult the SystemView manual and the attached example for getting more details.

• SEGGER_SYSVIEW_HeapAlloc

This function should be called each time an allocation has been done. Keep in mind to provide the real internally allocated chunk which is usually bigger than the one requested by the user.

• SEGGER_SYSVIEW_HeapFree

This function should be called each time memory has been freed.

So, these APIs must accompany the calls to the their respective heap management counterparts. In this article we will cover the case of C standard library heap functions malloc, realloc, and free (the calloc function is left out because it is just a variant of malloc and it would be trivial to implement it by following the malloc example), and the question arises: how to do this most efficiently in case of existing projects (i.e. not the ones created from scratch with this information in mind)?

Linker Wrapping of Heap Functions

Existing projects might already reference C standard library functions in many places in the code. Using conventional programming methods, to enable calling the counterpart SystemView APIs too, a user would then be forced to substantially change the existing code by introducing wrapper functionality for these calls and substitute all references to the stdlib heap functions in the code with it. Luckily, the SEGGER linker provides a generic wrapping functionality for any linker symbol. By issuing --wrap <function_name> (a linker command-line example), the linker will rename the existing definition to __real_<function_name>, and resolve any calls to the function <funtion_name> to __wrap_<function_name>. A user would then define the __wrap_malloc, __wrap_realloc and __wrap_free functions which will most likely call the __real_malloc, __real_realloc and __real_free (or an own custom heap management functionality, see Custom Heap Management and SystemView), accompanied by the corresponding calls to SEGGER_SYSVIEW_HeapAlloc and SEGGER_SYSVIEW_HeapFree.

This linker wrapping functionality can be comfortably invoked through Embedded Studio by adding the following lines in the Project Options/Linker/Additional Linker Options dialog:

Example Code

The example Embedded Studio project code (SystemView_malloc_example.7z) uses embOS as an underlying real-time OS. Three tasks are created which do some somewhat random allocations and corresponding deallocations, by using the standard C heap functionality. Because of the linker wrapping functionality described above, these calls will yield calling the SystemView heap APIs too, which will dispatch the necessary information to the SystemView app.

A sample saved SystemView session with the heap messages is available here for offline (i.e. without a target HW) browsing: embOS_Heap.SVData.