5.2.12 Code Coverage

After purchase of the Analysis Tool Suite License (SW006027-2), the compiler's code coverage feature can be used to facilitate analysis of the extent to which a project’s source code has been executed.

This feature is available in the compiler for all enhanced Mid-range and PIC18 devices.

When enabled, this feature instruments the project’s program image with small assembly sequences. When the program image is executed, these sequences record the execution of the code that they represent in reserved areas of device RAM. The records stored in the device can be later analyzed to determine which parts of a project’s source code have been executed. Compiler-supplied library code is not instrumented.

This feature differs from function profiling (Function Profiling) in that code coverage indicates program execution of smaller blocks of code, as opposed to execution of a function, and is primarily used as part of a testing regime to ensure that all parts of a program have been executed and hence tested. It does not verify that code executed correctly nor provide any indication of code execution times, which can be determined using the function profiling feature.

When code coverage is enabled, the compiler will execute an external tool called xc-ccov to determine the most efficient way to instrument the project. The tool considers the program’s basic blocks, which can be considered as sequences of one or more instructions with only one entry point, located at the start of the sequence and only one exit located at the end. Not all of these blocks need to be instrumented, with the tool determining the minimum set of blocks that will allow the program to be fully analyzed.

Use the -mcodecov option to enable code coverage in the compiler. The preprocessor macro __CODECOV will be defined once the feature is enabled.

All compiler options you use to build the project, when using code coverage, are significant, as these will affect the program image that is ultimately instrumented. To ensure that the analysis accurately reflects the shipped product, the build options should be the same as those that will be used for the final release build.

If code coverage is enabled, there will be 1 bit of RAM allocated per instrumented basic block, which will increase the data memory requirement of the project.

There is one assembly instruction inserted into each instrumented basic block. Other instructions might be required to perform bank selection, depending on where the code coverage bits are located and which target device is being used. Note that some optimizations are disabled when enabling the code coverage feature, and this will increase the size of the built project.

The instrumented project code must be executed for code coverage data to be generated and this execution will be fractionally slower due to the added assembly sequences. Provide the running program with input and stimulus that should exercise all parts of the program code, so that execution of all parts of the program source can be recorded.

Code coverage data can be analyzed in the MPLAB X IDE. Information in the ELF file produced by the compiler will allow the plugin to locate and read the device memory containing the code coverage results and display this in a usable format. See Microchip's Analysis Tool Suite License webpage for further information on the code coverage feature and other analysis tools.