< for the compiler you are using and search for the sub-chapter that includes the word **Coverage**.
This application note is written for compilers that are based on Clang and LLVM such as the tiarmclang toolset. If you are using a different TI compiler please refer to
[Code Coverage using TI Compilers](https://software-dl.ti.com/ccs/esd/documents/application_notes/appnote-code_coverage_compiler.html) as the instructions are different.
# References
[TI Arm Clang Users Guide](https://software-dl.ti.com/codegen/docs/tiarmclang/compiler_tools_user_guide/compiler_manual/code_coverage/source_based_code_coverage.html)
# Supported Compilers
* tiarmclang 1.1 and later
# Procedure
###CIO Operation
C Input/Output features of the C runtime library are required in order to transfer the coverage data from the device to the host workstation. Thus it is advised to ensure that you are able to successfully use prinf() in your application as a way to test that CIO is working. This may involve needing to increase your stack and heap sizes. For help with enabling printf please refer to: [Tips for Using Printf](../sdto_cgt_tips_for_using_printf.html)
###New Project Configurations
This step is optional but recommended to make it easier to use.
Code Composer Studio projects typically have multiple build configurations such as debug and release. Make a copy of the build configuration that you wish to add Code Coverage to.
* Right-click on the project and select **Build Configurations -> Manage...**
* Click the **New...** button to create a new build configuration. Give this configuration a name such as **Collect**.
[[y Warning:
Do not include a space in the name of the configuration.
]]
Select the existing build configuraiton that you want to copy the settings from.
* Repeat the previous step and create an **Analyze** configuration.
###Enabling collection
Now we are going to setup the **Collect** configuration to capture code coverage information.
* Right click on your project and select **Properties**
* Ensure that the **Collect** configuration is select in the drop down box at the top of the dialog box.
* In the tree on the left go to **Build -> Arm Compiler -> Advanced Options -> Instrumentation Options**.
* Check the box to **Generate coverage mapping to enable code coverage analysis (--fcoverage_mapping)**
* Check the box to **Generate instrumented code to collect coverage info (--fprofile_instr_generate)**
Now when this build configuration is compiled it will be instrumented to collect the information necessary for code Coverage.
###Setting up data transfer
It is necessary to add a function call to complete the transfer of coverage data.
* Add a call to __llvm_profile_write_file() at the point in which you wish to transfer the coverage data.
```
__llvm_profile_write_file();
```
* At the top of the same source file it will be necessary to add
```
extern void __llvm_profile_write_file(void);
```
[[b Note:
It is also possible to use scripting inside Code Composer Studio to read the buffer from the target and write it to a file. There is information on this in the [TI Arm Clang Users Guide](https://software-dl.ti.com/codegen/docs/tiarmclang/compiler_tools_user_guide/compiler_manual/code_coverage/source_based_code_coverage.html) .
]]
###Collecting data
* Build the **Collect** build configuration by selecting the down arrow beside the build button on the toolbar and selecting **Collect**.
* Once the build has finished click on the **Debug** button to launch the debugger and load the application.
[<img src="images/DebugButton.png" width=32/>](images/DebugButton.png)
* Next you will need to run the application to collect the data and transfer it to the host workstation. If you added a call to **__llvm_profile_write_file()** to your application then it is suggested to set a breakpoint on the line immediately after it. Then run. Once the breakpoint has been hit the data should have been captured and transferred. Click the **Resume** button.
[<img src="images/RunButton.png" width=32/>](images/RunButton.png)
[[b Note:
If you added a call to **__llvm_profile_write_file()** to your application then it is suggested to set a breakpoint on the line immediately after it. Then run. Once the breakpoint has been it the data should have been captured and transferred.
]]
* Terminate your debug session by clicking on the **Terminate** button.
[<img src="images/TerminateButton.png" width=32/>](images/TerminateButton.png)
* A file called **default.profraw** should be present in the build configuration folder of your project. In this case it would be in the **\Collect** folder.
###Analyzing the data
Now there are a couple of utilities that need to be run to prepare the code coverage data. We are going to leverage the Analyze configuration that we created earlier to do this.
Go to your project properties.
Ensure that the **Analyze** configuration is selected in the drop down at the top.
We need to now execute the **profdata** utility. This will process the raw data file (default.profraw) into a .profdata file.
We are going to add a pre-build step to do this.
* Select **Build** in the tree on the left.
* Next select the **Steps** tab in the middle of the dialog.
* We are now going to invoke the profdata utility. We pass it the program file, name of the file to output and the raw data file. We are going to make use of build variables to make this more robust. If you named your **Collect** configuration something else you will have to adjust the commands below.
```
"${CG_TOOL_ROOT}/bin/tiarmprofdata" merge -sparse -obj-file="${CCS_PROJECT_DIR}/Collect/${BuildArtifactFileName}" "${CCS_PROJECT_DIR}/Collect/default.profraw" -o "${ProjName}.profdata"
```
Now we need to process the .profdata file and generated an html file that can be viewed. This can be done by adding a post build step.
* Add the following post build step.
```
"${CG_TOOL_ROOT}/bin/tiarmcov" show --format=html --show-expansions --show-instantiations --show-branches=count --object="${CCS_PROJECT_DIR}/Collect/${BuildArtifactFileName}" -instr-profile="${CCS_PROJECT_DIR}/Analyze/${ProjName}.profdata" --output-dir="${CCS_PROJECT_DIR}/Analyze"
```
* Now build the Analyze configuration by going to the down arrow beside the build button and selecting **Analyze**.
In the Analyze folder there will now be an **index.html** file that has coverage information.
* Double-click on this file to open it inside Code Composer Studio.
[[b Note:
The pre and post build steps will only run if the source code has changed. Thus you may need to run **clean project** for the **analyze** configuration prior to building to ensure that the report is generated. Alternatively it is possible to setup a batch file to run these steps that could be executed from the command line and not rely on building the **Analyze** configuration.
]]
<!-- End of markdown source -->
<div id="resources" align="center" style="margin-top: 4em; font-size: smaller;">
</div>
<div align="center" style="margin-top: 4em; font-size: smaller;">
<a rel="license" href="https://creativecommons.org/licenses/by-nc-nd/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://software-dl.ti.com/ccs/esd/documents/web_support_v2/cc_license_icon.png" /></a><br />This work is licensed under a <a rel="license" href="https://creativecommons.org/licenses/by-nc-nd/4.0/">Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License</a>.</div>
<div id="timestamp" align="center" style="margin-top: 4em; font-size: smaller;">
</div>
]]>