Review and Address Memory Use Results

You can use Polyspace^® Test™ to calculate how much stack memory is used by callable entities in your C/C++ code. See Memory Use.

Review the Memory Use results to:

• Determine whether your code meets the memory constraints of your target hardware.

• Identify code sections that require memory optimization.

Prerequisite

To follow this topic, copy the content of the folder polyspaceroot\polyspace\examples\doc_pstest\memory_use to a writable folder. Here, polyspaceroot is the Polyspace Test installation folder, for instance, C:\Program Files\Polyspace\R2026a. The folder contains a subfolder src, where the required sources are stored. A Makefile to generate the memory use report is also available in the folder.

Before using the Makefile, specify your installation folder as the variable POLYSPACEROOT. For details about using Makefiles to calculate code profile, see Calculate Code Profile by Using Makefile.

The code in this folder demonstrates a convolution algorithm and includes an xUnit test that verifies the accuracy of the implementation.

Calculate Memory Use

You can calculate the memory use of your source code either using the Polyspace Platform user interface or the command line.

Use Polyspace Platform User Interface

To calculate the memory use using the Polyspace Platform user interface:

1. Create a new Polyspace Platform project.

2. Add the file src/src.c to the project. Parse the added code.

3. Add the Polyspace xUnit test file test/test.c.

4. In the Profiling section of the toolstrip, select Memory Use from the drop-down menu.

5. Open the Testing & Profiling pane in the Configuration tab. Specify the folder memory_use\src in the field Folders to profile.

6. Click Build Project and then Run Tests to run the added test. This steps generates the results.

Use Command Line

At the command line, you can either use the make utility or the polyspace-code-profiler command.

If you have the make utility:

1. Open the file Makefile and specify your installation folder as the variable POLYSPACEROOT.

2. Navigate to the folder where you copied the content of memory_use and, at the command line, enter:

   make report

   The HTML report containing the Memory Use results is stored in the folder reportFolder.

To calculate the memory use results using the command polyspace-code-profiler, use these scripts:

•  Windows

  @echo off
  set polyspaceroot=C:\Program Files\Polyspace\R2023b
  set TEST_SOURCE=%polyspaceroot%\polyspace\pstest\pstunit\src\pstunit.c 
  set TEST_INCLUDE=%polyspaceroot%\polyspace\pstest\pstunit\include
  set PSPROFILELIB=%polyspaceroot%\polyspace\psprofile\lib\win64\libmwpsprofile_cli_runtime.lib
  
  polyspace-code-profiler -instrument -limit-instrumentation-to src/ -instrum-dir instrumFolder/ -stack-metric-level detailed -prof-counter-size 64 -- gcc test/test.c src/src.c  %TEST_SOURCE% -I %TEST_INCLUDE%
  gcc src.o pstunit.o test.o %PSPROFILELIB%
  polyspace-code-profiler -run -instrum-dir instrumFolder/ -results-dir resultFolder/ -- a.exe
  polyspace-code-profiler -report -report-dir reportFolder/ -html resultFolder/
  
  Pause
  

•  Linux

  set polyspaceroot = /usr/local/Polyspace/R2026a
  set TEST_SOURCE = polyspaceroot/polyspace/pstest/pstunit/src/pstunit.c 
  set TEST_INCLUDE = polyspaceroot/polyspace/pstest/pstunit/include
  set  PSPROFILELIB=polyspaceroot/polyspace/psprofile/lib/glnxa64/static/libmwpsprofile_cli_runtime.a
  polyspace-code-profiler -instrument -limit-instrumentation-to src/ -instrum-dir instrumFolder/ -stack-metric-level detailed -prof-counter-size 64 -- gcc test/test.c src/src.c   $TEST_SOURCE -I $TEST_INCLUDE 
  gcc src.o pstunit.o test.o $PSPROFILELIB 
  polyspace-code-profiler -run -instrum-dir instrumFolder/ -results-dir resultFolder/ -- a.out
  polyspace-code-profiler -report -report-dir reportFolder/ -html resultFolder/

After executing these commands, the HTML report containing the Memory Use is stored in the folder reportFolder. For details about these commands, see Calculate Execution Time and Memory Use of C/C++ Code.

Open Memory Use Results

You can open memory use results in the Polyspace Platform user interface or in the Polyspace Access™ web interface:

• You can see memory use results after building and running tests in the Polyspace Platform user interface with execution profiling enabled or after calculating execution time using the polyspace-code-profiler command.

  In the Polyspace Platform user interface, once you open execution time results, the Results pane contains an Memory Profiling node. You can right-click this node and open a summary of results in the Dashboard perspective or more detailed information in the Review perspective.

  For more information, see Open Polyspace Results in Polyspace Platform User Interface.

• You can upload memory use results to a Polyspace Access web server, and review the results in a web browser.

  In the Polyspace Access web interface, you see results on the Project Explorer pane. You can select a memory use result set to open a summary of results in the Dashboard perspective or select the Review button on the toolstrip to open more detailed information in the Review perspective.

  For more information, see Upload Results to Polyspace Access.

You see the same display of memory use results in the Polyspace Platform user interface and the Polyspace Access web interface.

View Memory Use Results on Dashboard

In the Dashboard perspective, you can see a Project Overview dashboard containing an overview of all types of results, and an Memory Profiling dashboard containing more details of execution time results. By default, you see the Project Overview dashboard. Select Memory Profiling on the toolstrip to open the Memory Profiling dashboard.

To see an overview of memory use results in the Polyspace Platform user interface:

• The Project Overview dashboard contains a Memory Profiling section showing the metric Stack (Max). The metric value is reported in bytes.

• The Memory Profiling dashboard consists of these sections:

  • Memory Profiling: This section shows the metric Stack (Max) that you also see on the Project Overview dashboard.

    

  • View by File: This section shows a breakdown of the memory use by file and function. In the rightmost column, the dark bands correspond to the self memory usage and the light bands correspond to the maximum stack memory usage.

    

    For more information on memory use metrics, see Memory Use.

  • View by Project: In the Polyspace Access web interface, you can also see a dashboard that spans several projects by selecting a parent folder in the Project Explorer pane. To help you distinguish between results from different projects, the Memory Profiling dashboard in Polyspace Access has this additional section that shows a per-project breakdown of the test results.

View Memory Use Results in Report

You can open an HTML report containing details of memory use results.

If you use the Polyspace Platform user interface:

1. At the Results pane, right -click Memory Profiling and select Open Review.

2. The user interface does not support reviewing the Memory Use results directly. At the prompt, select Yes to open the HTML report.

3. Select a location to save the HTML report.

4. The HTML report opens in your browser.

If you use the command line, the HTML report is already produced. Open the report in the folder reportFolder.

The results list the functions invoked in the code, the number of times each function is called, and their memory use in bytes.

The report contains both the self memory use and the max memory use (in parenthesis). The self memory use represent the stack use of a function excluding the stack use of its called functions. The max memory use indicate the memory use of a function including all the called functions in different execution paths. See Memory Use.

Your results might vary slightly from the preceding results. Click on each individual function to see more details about them.

Address Large Stack Usage

Review the results to identify functions with disproportionately high memory use. The results indicate that the function calculateOutput() might require memory optimization.

After reviewing the code, the function calculateOutput() uses large amount of the stack because it stores a 800 element input signal as a local variable before calculating the output signal. Depending on your platform, the memory use of calculateOutput() might be acceptable. If you want to reduce the memory use of your functions, consider these strategies:

• Consider working with a smaller array. For instance, to calculate the output signal, all 800 samples of the input signal are not necessary at the same time. In this example, the output signal is calculated by convolving the input signal with a 5th order finite impulse response filter. In this case, the nth element of the output signal can be calculated by using the 5 preceding elements of the input signal. Using this strategy, it is possible to calculate the output signal without storing the 800 element input signal in the stack.

• Consider using the heap to store large arrays. Using the heap might increase the execution time, but this strategy reduces the possibility of a stack overflow.

• Consider passing arguments by using references or pointers. Passing by value creates temporary copies of the passed objects in the stack.

For instance, setting the macro SIGNAL_LENGTH in src.h to 50 instead of 800 reduces the memory use of calculateOutput() to around 500 bytes.