1 =========================
2 LLVM PC Sections Metadata
3 =========================
11 PC Sections Metadata can be attached to instructions and functions, for which
12 addresses, viz. program counters (PCs), are to be emitted in specially encoded
13 binary sections. Metadata is assigned as an ``MDNode`` of the ``MD_pcsections``
14 (``!pcsections``) kind; the following section describes the metadata format.
19 An arbitrary number of interleaved ``MDString`` and constant operators can be
20 added, where a new ``MDString`` always denotes a section name, followed by an
21 arbitrary number of auxiliary constant data encoded along the PC of the
22 instruction or function. The first operator must be a ``MDString`` denoting the
34 !1 = !{ iXX <aux-consts#1>, ... }
35 !2 = !{ iXX <aux-consts#2>, ... }
38 The occurrence of ``section#1``, ``section#2``, ..., ``section#N`` in the
39 metadata causes the backend to emit the PC for the associated instruction or
40 function to all named sections. For each emitted PC in a section #N, the
41 constants ``aux-consts#N`` in the tuple ``!N`` will be emitted after the PC.
42 Multiple 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
44 different sections (e.g. ``!0 = !{"s1", !1, "s2", !1}``).
49 *Instructions* result in emitting a single PC, and *functions* result in
50 emission of the start of the function and a 32-bit size. This is followed by
51 the auxiliary constants that followed the respective section name in the
52 ``MD_pcsections`` metadata.
54 To avoid relocations in the final binary, each PC address stored at ``entry``
55 is a relative relocation, computed as ``pc - entry``. To decode, a user has to
56 compute ``entry + *entry``.
58 The size of each entry depends on the code model. With large and medium sized
59 code models, the entry size matches pointer size. For any smaller code model
60 the entry size is just 32 bits.
65 Optional encoding options can be passed in the first ``MDString`` operator:
66 ``<section>!<options>``. The following options are available:
68 * ``C`` -- Compress constant integers of size 2-8 bytes as ULEB128; this
69 includes the function size (but excludes the PC entry).
71 For example, ``foo!C`` will emit into section ``foo`` with all constants
74 Guarantees on Code Generation
75 =============================
77 Attaching ``!pcsections`` metadata to LLVM IR instructions *shall not* affect
78 optimizations or code generation outside the requested PC sections.
80 While relying on LLVM IR metadata to request PC sections makes the above
81 guarantee relatively trivial, propagation of metadata through the optimization
82 and code generation pipeline has the following guarantees.
87 In general, LLVM *does not make any guarantees* about preserving IR metadata
88 (attached to an ``Instruction``) through IR transformations. When using PC
89 sections metadata, this guarantee is unchanged, and ``!pcsections`` metadata is
90 remains *optional* until lowering to machine IR (MIR).
92 Note for Code Generation
93 ------------------------
95 As with other LLVM IR metadata, there are no requirements for LLVM IR
96 transformation passes to preserve ``!pcsections`` metadata, with the following
99 * The ``AtomicExpandPass`` shall preserve ``!pcsections`` metadata
100 according to the below rules 1-4.
102 When translating LLVM IR to MIR, the ``!pcsections`` metadata shall be copied
103 from the source ``Instruction`` to the target ``MachineInstr`` (set with
104 ``MachineInstr::setPCSections()``). The instruction selectors and MIR
105 optimization passes shall preserve PC sections metadata as follows:
107 1. Replacements will preserve PC sections metadata of the replaced
110 2. Duplications will preserve PC sections metadata of the copied
113 3. Merging will preserve PC sections metadata of one of the two
114 instructions (no guarantee on which instruction's metadata is used).
116 4. Deletions will loose PC sections metadata.
118 This is similar to debug info, and the ``BuildMI()`` helper provides a
119 convenient way to propagate debug info and ``!pcsections`` metadata in the
120 ``MIMetadata`` bundle.
122 Note for Metadata Users
123 -----------------------
125 Use cases for ``!pcsections`` metadata should either be fully tolerant to
126 missing metadata, or the passes inserting ``!pcsections`` metadata should run
127 *after* all LLVM IR optimization passes to preserve the metadata until being