1========================= 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 62Guarantees on Code Generation 63============================= 64 65Attaching ``!pcsections`` metadata to LLVM IR instructions *shall not* affect 66optimizations or code generation outside the requested PC sections. 67 68While relying on LLVM IR metadata to request PC sections makes the above 69guarantee relatively trivial, propagation of metadata through the optimization 70and code generation pipeline has the following guarantees. 71 72Metadata Propagation 73-------------------- 74 75In general, LLVM *does not make any guarantees* about preserving IR metadata 76(attached to an ``Instruction``) through IR transformations. When using PC 77sections metadata, this guarantee is unchanged, and ``!pcsections`` metadata is 78remains *optional* until lowering to machine IR (MIR). 79 80Note for Code Generation 81------------------------ 82 83As with other LLVM IR metadata, there are no requirements for LLVM IR 84transformation passes to preserve ``!pcsections`` metadata, with the following 85exceptions: 86 87 * The ``AtomicExpandPass`` shall preserve ``!pcsections`` metadata 88 according to the below rules 1-4. 89 90When translating LLVM IR to MIR, the ``!pcsections`` metadata shall be copied 91from the source ``Instruction`` to the target ``MachineInstr`` (set with 92``MachineInstr::setPCSections()``). The instruction selectors and MIR 93optimization passes shall preserve PC sections metadata as follows: 94 95 1. Replacements will preserve PC sections metadata of the replaced 96 instruction. 97 98 2. Duplications will preserve PC sections metadata of the copied 99 instruction. 100 101 3. Merging will preserve PC sections metadata of one of the two 102 instructions (no guarantee on which instruction's metadata is used). 103 104 4. Deletions will loose PC sections metadata. 105 106This is similar to debug info, and the ``BuildMI()`` helper provides a 107convenient way to propagate debug info and ``!pcsections`` metadata in the 108``MIMetadata`` bundle. 109 110Note for Metadata Users 111----------------------- 112 113Use cases for ``!pcsections`` metadata should either be fully tolerant to 114missing metadata, or the passes inserting ``!pcsections`` metadata should run 115*after* all LLVM IR optimization passes to preserve the metadata until being 116translated to MIR. 117