Instrumentation Profile Format

Overview

Clang supports two types of profiling via instrumentation [1]: frontend-based and IR-based, and both could support a variety of use cases [2] . This document describes two binary serialization formats (raw and indexed) to store instrumented profiles with a specific emphasis on IRPGO use case, in the sense that when specific header fields and payload sections have different ways of interpretation across use cases, the documentation is based on IRPGO.

Note

Frontend-generated profiles are used together with coverage mapping for source-based code coverage. The coverage mapping format is different from profile format.

Raw Profile Format

The raw profile is generated by running the instrumented binary. The raw profile data from an executable or a shared library [3] consists of a header and multiple sections, with each section as a memory dump. The raw profile data needs to be reasonably compact and fast to generate.

There are no backward or forward version compatibility guarantees for the raw profile format. That is, compilers and tools require a specific raw profile version to parse the profiles.

To feed profiles back into compilers for an optimized build (e.g., via -fprofile-use for IR instrumentation), a raw profile must to be converted into indexed format.

General Storage Layout

The storage layout of raw profile data format is illustrated below. Basically, when the raw profile is read into an memory buffer, the actual byte offset of a section is inferred from the section’s order in the layout and size information of all the sections ahead of it.

+----+-----------------------+
|    |        Magic          |
|    +-----------------------+
|    |        Version        |
|    +-----------------------+
H    |   Size Info for       |
E    |      Section 1        |
A    +-----------------------+
D    |   Size Info for       |
E    |      Section 2        |
R    +-----------------------+
|    |          ...          |
|    +-----------------------+
|    |   Size Info for       |
|    |      Section N        |
+----+-----------------------+
P    |       Section 1       |