Review and Address Execution Time Results

You can use Polyspace^® Test™ to calculate the metric Execution Time, which computes the time required to execute the different callable entities of your code. See Execution Time.

Review Execution Time results to:

• Determine whether your code meets your requirements for code execution time in host or target hardware.

• Identify code sections that require execution speed enhancements.

Prerequisites

To follow this topic, copy the content of the folder polyspaceroot\polyspace\examples\doc_pstest\execution_profiling to a writable folder. Here, polyspaceroot is the Polyspace Test installation folder, for instance, C:\Program Files\Polyspace\R2026a. The subfolder src contains the required source file, and the subfolder test contains the required xUnit test file. A makefile to generate the execution time 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 the code profile, see Calculate Code Profile by Using Makefile.

Calculate Execution Time

You can calculate the execution time of the source code using either the Polyspace Platform user interface or the command line.

Use Polyspace Platform User Interface

To calculate the execution time using the Polyspace Platform user interface:

1. Create a new Polyspace Platform project.

2. Add the file src/container.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 Execution Time from the menu.

5. Click Build Project and then Run Tests to run the added test. This step generates the execution time results.

Use Command Line

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

If you have the make utility:

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

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

   make report

   The HTML report containing the Execution Time results is stored in the folder reportFolder.

To calculate the execution time 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/ -exec-metric-level detailed -prof-counter-size 64 -- gcc test/test.c src/container.c  %TEST_SOURCE% -I %TEST_INCLUDE%
  gcc container.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/ -exec-metric-level detailed -prof-counter-size 64 -- gcc test/test.c src/container.c   $TEST_SOURCE -I $TEST_INCLUDE 
  gcc container.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, Polyspace Test stores the HTML report containing the Execution Time in the folder reportFolder. For details about these commands, see Calculate Execution Time and Memory Use of C/C++ Code.

Open Execution Time Results

You can open execution time results in the Polyspace Platform user interface or in the Polyspace Access™ web interface:

• You can see execution time 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 Execution 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 execution time 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 an execution time 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 execution time results in the Polyspace Platform user interface and the Polyspace Access web interface.

View Execution Time Results on Dashboard

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

• The Project Overview dashboard contains an Execution Profiling section showing execution time metrics such as Self Time and Max Total Time.

  • The self-time of a function is the time spent in the function during test execution, excluding any time spent in the function callees. The Self Time metric reported on the dashboard is the sum of self-time of all the functions. This metric provides an insight into the time spent in test execution or execution of the main function if there are no tests.

  • The total-time of a function is the time spent in the function during test execution, including any time spent in the function callees. The Max Total Time metric reported on the dashboard is the total time of the function with the longest value of total time. This metric provides an insight into the time spent in the function where most time is consumed during test execution.

  Note that by definition, the self-time of a function is less than the total time spent in the function. However, the Self Time reported at the top of the dashboard is the sum of self-times of all functions and can be greater than the Max Total Time, which is the total time spent in a single function (including time spent in its callees).

  The metric values are reported in ticks, where a single tick corresponds to one hundred nanoseconds.

• The Execution Profiling dashboard consists of these sections:

  • Execution Profiling: This section shows the metrics Self Time and Max Total Time that you also see on the Project Overview dashboard.

    

  • View by File: This section shows a breakdown of the execution time by file and function. In the rightmost column, the dark bands correspond to the self-time and the light bands correspond to the total time spent in the function (including time spent in callees).

    For instance, in the following table, you see that the function container_resize() has the longest dark band. Therefore, you can see at a glance that most of the time is spent in this function during test execution.

    

  • Flame Graph: This section shows a graphical representation of the function call hierarchy. Functions at the same level of the call hierarchy are shown in the same horizontal layer. The width of the bar corresponding to a function is proportional to the total time spent in the function.

    For instance, in the following flame graph, all functions except container_resize() are called directly from tests, therefore, they appear in the first layer of the flame graph. The function container_resize() is called from another function that is called in the tests, therefore, it appears in the second layer. Of the functions called directly in the tests, the function container_add() takes up the most time.

    

  • 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 Execution Profiling dashboard in Polyspace Access has this additional section that shows a per-project breakdown of the test results.

View Execution Time Results in Report

You can open an HTML report containing details of execution time results.

If you use the Polyspace Platform user interface:

1. In the Results pane, right -click Execution Profiling and select Open Review.

2. The user interface does not support reviewing the Execution Time 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, open the HTML report in the folder reportFolder.

The results show the functions invoked in the code, the number of times each function is called, and their execution time.

The report contains both the Self execution time and the Total execution time. For instance, the Self time of container_add is 31% while the Total time of container_add is 68%. This indicates that in total, 68% of the execution time is spent to execute container_add including all the function calls within container_add. Excluding the called functions, the function container_add uses 31% of the execution time. Click each individual function to see more details about them. For more information on all execution time metrics, see Execution Time.

Depending on your hardware and compiler, your results might vary slightly from the example.

Review Results and Identify Bottleneck

Review the HTML report to identify possible bottlenecks in your code.

The results indicate that among the individual functions, container_add() requires the most execution time. This function might represent a bottleneck. Improving the performance of container_add() can speed up the overall execution time of the code.

When you review container_add(), you see that the function adds an element to the container if the container is not full. If the container is full, the function resizes the container to have one more element:

void container_add(container* foo, void* element)
{
    if (foo->numel == foo->total)
        container_resize(foo, foo->numel +1); //Resizing to have one more element
    foo->buffer[foo->total++] = element;
}

Because container_add() resizes the container to have one more element, the function counter_resize() is called frequently, which is inefficient. In the report, you see that for 50 calls to container_add(), there are 50 calls to container_resize().

Because of frequent resizing, the execution spends more than 8000 ticks in container_add(). Minimizing the number of calls to container_resize() can speed up the code.

To improve the execution speed of your code, modify the function container_add. Resize the container to have twice as many elements as it had previously:

void container_add(container* foo, void* element)
{
    if (foo->numel == foo->total)
        container_resize(foo, foo->numel *2 ); //Resizing to have twice as many elements
    foo->buffer[foo->total++] = element;
}

After making this change, calculate the execution time again. This time, for 50 calls to container_add(), there are 10 calls to container_resize(). Because the container is resized less frequently, the execution spends less than 5000 ticks in container_add(), which reduces the execution time of the code.

Depending on your hardware and software, you might get slightly different numbers. Regardless of the exact number, the time required to execute container_add() reduces if you resize the container less frequently.

By reviewing the execution time results, you can identify the bottlenecks in your code. Common causes of bottlenecks include inefficient coding patterns and poorly designed architecture. The strategy to resolve code bottlenecks depends on the context of the code. You can run a Polyspace static analysis on your code to identify performance inefficiencies or unwanted code complexity. See:

• Performance Defects (Polyspace Bug Finder)

• Identify and Reduce Software Complexity (Polyspace Bug Finder)