129 lines · plain
1=========================2LLVM PC Sections Metadata3=========================4 5.. contents::6 :local:7 8Introduction9============10 11PC Sections Metadata can be attached to instructions and functions, for which12addresses, viz. program counters (PCs), are to be emitted in specially encoded13binary sections. Metadata is assigned as an ``MDNode`` of the ``MD_pcsections``14(``!pcsections``) kind; the following section describes the metadata format.15 16Metadata Format17===============18 19An arbitrary number of interleaved ``MDString`` and constant operators can be20added, where a new ``MDString`` always denotes a section name, followed by an21arbitrary number of auxiliary constant data encoded along the PC of the22instruction or function. The first operator must be a ``MDString`` denoting the23first section.24 25.. code-block:: none26 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 the39metadata causes the backend to emit the PC for the associated instruction or40function to all named sections. For each emitted PC in a section #N, the41constants ``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 string43(e.g. ``!0 = !{"s1", !1, !2}``), and a single constant tuple may be reused for44different sections (e.g. ``!0 = !{"s1", !1, "s2", !1}``).45 46Binary Encoding47===============48 49*Instructions* result in emitting a single PC, and *functions* result in50emission of the start of the function and a 32-bit size. This is followed by51the auxiliary constants that followed the respective section name in the52``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 to56compute ``entry + *entry``.57 58The size of each entry depends on the code model. With large and medium sized59code models, the entry size matches pointer size. For any smaller code model60the entry size is just 32 bits.61 62Encoding Options63----------------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; this69 includes the function size (but excludes the PC entry).70 71For example, ``foo!C`` will emit into section ``foo`` with all constants72encoded as ULEB128.73 74Guarantees on Code Generation75=============================76 77Attaching ``!pcsections`` metadata to LLVM IR instructions *shall not* affect78optimizations or code generation outside the requested PC sections.79 80While relying on LLVM IR metadata to request PC sections makes the above81guarantee relatively trivial, propagation of metadata through the optimization82and code generation pipeline has the following guarantees.83 84Metadata Propagation85--------------------86 87In general, LLVM *does not make any guarantees* about preserving IR metadata88(attached to an ``Instruction``) through IR transformations. When using PC89sections metadata, this guarantee is unchanged, and ``!pcsections`` metadata is90remains *optional* until lowering to machine IR (MIR).91 92Note for Code Generation93------------------------94 95As with other LLVM IR metadata, there are no requirements for LLVM IR96transformation passes to preserve ``!pcsections`` metadata, with the following97exceptions:98 99 * The ``AtomicExpandPass`` shall preserve ``!pcsections`` metadata100 according to the below rules 1-4.101 102When translating LLVM IR to MIR, the ``!pcsections`` metadata shall be copied103from the source ``Instruction`` to the target ``MachineInstr`` (set with104``MachineInstr::setPCSections()``). The instruction selectors and MIR105optimization passes shall preserve PC sections metadata as follows:106 107 1. Replacements will preserve PC sections metadata of the replaced108 instruction.109 110 2. Duplications will preserve PC sections metadata of the copied111 instruction.112 113 3. Merging will preserve PC sections metadata of one of the two114 instructions (no guarantee on which instruction's metadata is used).115 116 4. Deletions will lose PC sections metadata.117 118This is similar to debug info, and the ``BuildMI()`` helper provides a119convenient way to propagate debug info and ``!pcsections`` metadata in the120``MIMetadata`` bundle.121 122Note for Metadata Users123-----------------------124 125Use cases for ``!pcsections`` metadata should either be fully tolerant to126missing metadata, or the passes inserting ``!pcsections`` metadata should run127*after* all LLVM IR optimization passes to preserve the metadata until being128translated to MIR.129