Automate C/C++ Code Profiling on Targets Using Polyspace Platform Projects

Using Polyspace® Test™, you can calculate C/C++ code profiling metrics, such as code coverage, execution time, and memory use:

  • The metric Code Coverage measures how much of your code is validated by the existing test cases. Measure the value of different code coverage metrics by using Polyspace Test and add appropriate test cases to achieve your desired level of coverage. Polyspace Test calculates code coverage for standard metrics. See Review Code Profiling Results.

  • The metric Execution Time computes the time required to execute the different callable entities of your code. See Execution Time.

  • The metric Memory Use measures how the callable entities use the available stack memory. See Memory Use.

To calculate these metrics on a target, you can follow one of these two possible workflows:

  • Using a Polyspace Platform project — If you have a Polyspace Platform project (.psprjx) containing your source files and tests, you can perform these calculations on your target hardware by registering a target in the project. To register a target, use a registration file, which is a MATLAB® file that sets up the connection between your target and Polyspace Test. You can execute this workflow either in the Polyspace Platform user interface or by using the Polyspace Test command-line interface.

  • Without using a Polyspace Platform project — If you have xUnit API-based tests that you link with your source files using your own toolchain, then you can perform these calculations on your target hardware without requiring a Polyspace Platform project. In this workflow, you cross-compile your source and tests for the hardware board using your own cross-compiler.

This example shows how to automate the calculation of code profiling metrics by using a Polyspace Platform project at the command line. To do these calculations using the Polyspace Platform user interface, see Calculate C/C++ Code Profiling Metrics on Target in Polyspace Platform User Interface. To do these calculations without requiring a Polyspace Platform project, see Calculate C/C++ Code Profiling Metrics by Using xUnit API-Based Tests on Target.

Prerequisites

To perform this workflow:

  • You require a valid Polyspace Platform project containing the source files and tests. For this workflow, your project must contain at least one test.

  • You must have created a valid registration file for your target. For more information on target registration files, see Run C/C++ Tests on Target in Polyspace Platform User Interface.

    Your target registration file might require additional information beyond the basic details, depending on the type of code profiling you want to perform. For instance:

    • If you want to calculate execution time on a target, the target registration file must define appropriate timer functions for your target.

    • If you want to calculate memory use on a target, the target registration file must define functions that can locate the current position of the stack pointer on your target.

  • You must have set up a host compiler for use with Polyspace Test. A host compiler is required for on-target code profiling, as certain generated source files need to be compiled on the host before cross-compiling your sources for the specified target.

You can calculate only one of the code coverage, execution time, or memory use metrics at a time. Calculate these metrics sequentially if you need more than one of the metrics.

Calculate Code Profile

When you run your tests on a target by using a Polyspace Platform project, Polyspace Test builds an appropriate test executable for your target, establishes communication with the target, runs the test executable on the target, collects data, and creates the results files. You do not have to manually build the test executable or manage communications with the target board.

Register Target

To execute tests on a target, register the target using a registration file. A registration file enables Polyspace Test to build and run tests on a target board. registration files are MATLAB files (.m) that:

  • Define your target and the toolchain needed for the target.

  • Define how to time execution on the target.

  • Define how to calculate the stack pointer location on the target.

  • Define how to communicate with the target from the host.

For more details about registration files, see Set Up PIL Connectivity by Using Target Framework (Embedded Coder).

After registering a target, you can subsequently run any project on the target.

To register a target with Polyspace Test, at the command line, enter:

polyspace-test -manage-target-package -register-from-file <Path_to_Package.m>
Here, <Path_to_Package.m> is the path to the registration file.

To check that the target is successfully registered, verify that your board and toolchain are among the registered boards and toolchain:

polyspace-test -manage-target-package -list Board
polyspace-test -manage-target-package -list Toolchain
If you do not see your board or toolchain, check the registration file and see if it correctly defines your board and toolchain.

Specify the path to the registration file as the value to the environment variable MATLABPATH. For instance, you can use the commands setenv or export in your UNIX® shell:

setenv MATLABPATH <Path_to_Package.m>
export MATLABPATH=<Path_to_Package.m>
Setting this environment variable enables Polyspace Test to recognize and execute the files in the registration file.

Generate Code Profiling Metrics

After registering the target, generate the code profiling metrics data by running an instrumented test executable on the target. To generate the code metrics:

  • Polyspace Test first instruments the source files with appropriate macros to enable code coverage, execution time, or memory use calculation. Then, Polyspace Test uses the toolchain defined in your registration file to compile the instrumented source into a test executable appropriate for your target.

  • Using the communication methods defined in the package, Polyspace Test executes the instrumented test executable on the target and gathers the code profiling data in a results (.psprof) file.

To calculate the code coverage metrics, at the command line, enter:

polyspace-test -run -project <project>.psprjx -board <myBoard> -toolchain <myToolchain> -results-dir <Results> -profiling-mode coverage -cov-metric-level mcdc
To calculate the execution time metrics, enter:
polyspace-test -run -project <project>.psprjx -board <myBoard> -toolchain <myToolchain> -results-dir <Results> -profiling-mode execution-profile
To calculate the memory use metrics, enter:
polyspace-test -run -project <project>.psprjx -board <myBoard> -toolchain <myToolchain> -results-dir <Results> -profiling-mode stack-profile
Here:

  • <project>.psprjx is the Polyspace Platform project containing tests that you want to run on the target.

  • <myBoard> is the name of the target board. The name is defined in the registration file.

  • <myToolchain> is the name of the toolchain required to build test executables for the target. The toolchain is defined in the registration file.

  • The option -cov-metric-level specifies which code coverage metrics you want to calculate. To calculate the code coverage of all supported coverage metrics, use the value mcdc

  • <Results> is the folder where Polyspace Test stores the results.

Verify that a results (.psprof) file is stored in the Results folder.

Create Report

To create an HTML report from the results (.psprof) file, at the command line, enter:

polyspace-test -report -html -report-dir <reportFolder> TestResults
Verify that the HTML report is created in the <reportFolder>.

Unregister Target

After completing the code profile calculation, you can unregister the target from Polyspace Test. At the command line, enter:

polyspace-test -manage-target-package -unregister-from-file <Path_to_Package_removal.m>
Here, <Path_to_Package_removal.m> is the MATLAB file that unregisters the target.

See Also

| |

Topics