blob: 4238ce687e3c3e373c47b39378b4e6c568c0a2ef [file] [log] [blame]
Marco Elverc70f6e12022-09-06 15:48:23 +02001=========================
2LLVM PC Sections Metadata
3=========================
4
5.. contents::
6 :local:
7
8Introduction
9============
10
11PC Sections Metadata can be attached to instructions and functions, for which
12addresses, viz. program counters (PCs), are to be emitted in specially encoded
13binary sections. Metadata is assigned as an ``MDNode`` of the ``MD_pcsections``
14(``!pcsections``) kind; the following section describes the metadata format.
15
16Metadata Format
17===============
18
19An arbitrary number of interleaved ``MDString`` and constant operators can be
20added, where a new ``MDString`` always denotes a section name, followed by an
21arbitrary number of auxiliary constant data encoded along the PC of the
22instruction or function. The first operator must be a ``MDString`` denoting the
23first section.
24
25.. code-block:: none
26
27 !0 = !{
28 !"<section#1>"
29 [ , !1 ... ]
30 [ !"<section#2">
31 [ , !2 ... ]
32 ... ]
33 }
34 !1 = !{ iXX <aux-consts#1>, ... }
35 !2 = !{ iXX <aux-consts#2>, ... }
36 ...
37
38The occurrence of ``section#1``, ``section#2``, ..., ``section#N`` in the
39metadata causes the backend to emit the PC for the associated instruction or
40function to all named sections. For each emitted PC in a section #N, the
41constants ``aux-consts#N`` in the tuple ``!N`` will be emitted after the PC.
42Multiple tuples with constant data may be provided after a section name string
43(e.g. ``!0 = !{"s1", !1, !2}``), and a single constant tuple may be reused for
44different sections (e.g. ``!0 = !{"s1", !1, "s2", !1}``).
45
46Binary Encoding
47===============
48
49*Instructions* result in emitting a single PC, and *functions* result in
50emission of the start of the function and a 32-bit size. This is followed by
51the auxiliary constants that followed the respective section name in the
52``MD_pcsections`` metadata.
53
54To avoid relocations in the final binary, each PC address stored at ``entry``
55is a relative relocation, computed as ``pc - entry``. To decode, a user has to
56compute ``entry + *entry``.
57
58The size of each entry depends on the code model. With large and medium sized
59code models, the entry size matches pointer size. For any smaller code model
60the entry size is just 32 bits.
61
Marco Elverbf9814b72023-02-08 12:25:01 +010062Encoding Options
63----------------
64
65Optional encoding options can be passed in the first ``MDString`` operator:
66``<section>!<options>``. The following options are available:
67
68 * ``C`` -- Compress constant integers of size 2-8 bytes as ULEB128; this
69 includes the function size (but excludes the PC entry).
70
71For example, ``foo!C`` will emit into section ``foo`` with all constants
72encoded as ULEB128.
73
Marco Elverc70f6e12022-09-06 15:48:23 +020074Guarantees on Code Generation
75=============================
76
77Attaching ``!pcsections`` metadata to LLVM IR instructions *shall not* affect
78optimizations or code generation outside the requested PC sections.
79
80While relying on LLVM IR metadata to request PC sections makes the above
81guarantee relatively trivial, propagation of metadata through the optimization
82and code generation pipeline has the following guarantees.
83
84Metadata Propagation
85--------------------
86
87In general, LLVM *does not make any guarantees* about preserving IR metadata
88(attached to an ``Instruction``) through IR transformations. When using PC
89sections metadata, this guarantee is unchanged, and ``!pcsections`` metadata is
90remains *optional* until lowering to machine IR (MIR).
91
92Note for Code Generation
93------------------------
94
95As with other LLVM IR metadata, there are no requirements for LLVM IR
96transformation passes to preserve ``!pcsections`` metadata, with the following
97exceptions:
98
99 * The ``AtomicExpandPass`` shall preserve ``!pcsections`` metadata
100 according to the below rules 1-4.
101
102When translating LLVM IR to MIR, the ``!pcsections`` metadata shall be copied
103from the source ``Instruction`` to the target ``MachineInstr`` (set with
104``MachineInstr::setPCSections()``). The instruction selectors and MIR
105optimization passes shall preserve PC sections metadata as follows:
106
107 1. Replacements will preserve PC sections metadata of the replaced
108 instruction.
109
110 2. Duplications will preserve PC sections metadata of the copied
111 instruction.
112
113 3. Merging will preserve PC sections metadata of one of the two
114 instructions (no guarantee on which instruction's metadata is used).
115
116 4. Deletions will loose PC sections metadata.
117
118This is similar to debug info, and the ``BuildMI()`` helper provides a
119convenient way to propagate debug info and ``!pcsections`` metadata in the
120``MIMetadata`` bundle.
121
122Note for Metadata Users
123-----------------------
124
125Use cases for ``!pcsections`` metadata should either be fully tolerant to
126missing metadata, or the passes inserting ``!pcsections`` metadata should run
127*after* all LLVM IR optimization passes to preserve the metadata until being
128translated to MIR.