Skip to content

Commit

Permalink
[docs][TypeProf]Update instrumentation file format document (llvm#83309)
Browse files Browse the repository at this point in the history
This is a follow-up to the profile format change in llvm#82711
  • Loading branch information
mingmingl-llvm authored Mar 28, 2024
1 parent d0b4780 commit 07a1fbe
Showing 1 changed file with 53 additions and 0 deletions.
53 changes: 53 additions & 0 deletions llvm/docs/InstrProfileFormat.rst
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,13 @@ Header
Records the in-memory address of name section. Not used except for raw profile
reader error checking.

``NumVTables``
Records the number of instrumented vtable entries in the binary. Used for
`type profiling`_.

``VNamesSize``
Records the byte size in the virtual table names section. Used for `type profiling`_.

``ValueKindLast``
Records the number of value kinds. Macro `VALUE_PROF_KIND`_ defines the value
kinds with a description of the kind.
Expand Down Expand Up @@ -323,6 +330,8 @@ for the design.
.. _`Modified Condition/Decision Coverage`: https://en.wikipedia.org/wiki/Modified_condition/decision_coverage
.. _`Bitmap RFC`: https://discourse.llvm.org/t/rfc-source-based-mc-dc-code-coverage/59244

.. _`function names`:

Names
^^^^^^

Expand All @@ -333,6 +342,37 @@ Function names serve as keys in the PGO data hash table when raw profiles are
converted into indexed profiles. They are also crucial for ``llvm-profdata`` to
show the profiles in a human-readable way.

Virtual Table Profile Data
^^^^^^^^^^^^^^^^^^^^^^^^^^^

This section is used for `type profiling`_. Each entry corresponds to one virtual
table and is defined by the following C++ struct

.. code-block:: c++

struct VTableProfData {
// The start address of the vtable, collected at runtime.
uint64_t StartAddress;
// The byte size of the vtable. `StartAddress` and `ByteSize` specifies an address range to look up.
uint32_t ByteSize;
// The hash of vtable's (PGO) name
uint64_t MD5HashOfName;
};

At profile use time, the compiler looks up a profiled address in the sorted vtable
address ranges and maps the address to a specific vtable through hashed name.

Virtual Table Names
^^^^^^^^^^^^^^^^^^^^

This section is similar to `function names`_ section above, except it contains the PGO
names of profiled virtual tables. It's a standalone section such that raw profile
readers could directly find each name set by accessing the corresponding profile
data section.

This section is stored in raw profiles such that `llvm-profdata` could show the
profiles in a human-readable way.

Value Profile Data
^^^^^^^^^^^^^^^^^^^^

Expand Down Expand Up @@ -426,6 +466,8 @@ This section is right after profile header. It stores the serialized profile
summary. For context-sensitive IR-based instrumentation PGO, this section stores
an additional profile summary corresponding to the context-sensitive profiles.

.. _`function data`:

Function data
^^^^^^^^^^^^^^^^^^
This section stores functions and their profiling data as an on-disk hash table.
Expand Down Expand Up @@ -453,6 +495,16 @@ Temporal Profile Traces
The section is used to carry on temporal profile information from raw profiles.
See `temporal profiling`_ for the design.

Virtual Table Names
^^^^^^^^^^^^^^^^^^^^
This section is used to store the names of vtables from raw profile in the indexed
profile.

Unlike function names which are stored as keys of `function data`_ hash table,
vtable names need to be stored in a standalone section in indexed profiles.
This way, `llvm-profdata` could show the profiled vtable information in a
human-readable way.

Profile Data Usage
=======================================

Expand All @@ -476,3 +528,4 @@ based profile data. For supported usages, check out `llvm-profdata documentation
.. _`single-byte counters`: https://discourse.llvm.org/t/rfc-single-byte-counters-for-source-based-code-coverage/75685
.. _`binary profile correlation`: https://discourse.llvm.org/t/rfc-add-binary-profile-correlation-to-not-load-profile-metadata-sections-into-memory-at-runtime/74565
.. _`binary id`: https://lists.llvm.org/pipermail/llvm-dev/2021-June/151154.html
.. _`type profiling`: https://discourse.llvm.org/t/rfc-dynamic-type-profiling-and-optimizations-in-llvm/74600

0 comments on commit 07a1fbe

Please sign in to comment.