Documentation/livepatch/module-elf-format.txt

   1 ===========================
   2 Livepatch module Elf format
   3 ===========================
   4
   5 This document outlines the Elf format requirements that livepatch modules must follow.
   6
   7 -----------------
   8 Table of Contents
   9 -----------------
  10 0. Background and motivation
  11 1. Livepatch modinfo field
  12 2. Livepatch relocation sections
  13    2.1 What are livepatch relocation sections?
  14    2.2 Livepatch relocation section format
  15        2.2.1 Required flags
  16        2.2.2 Required name format
  17        2.2.3 Example livepatch relocation section names
  18        2.2.4 Example `readelf --sections` output
  19        2.2.5 Example `readelf --relocs` output
  20 3. Livepatch symbols
  21    3.1 What are livepatch symbols?
  22    3.2 A livepatch module's symbol table
  23    3.3 Livepatch symbol format
  24        3.3.1 Required flags
  25        3.3.2 Required name format
  26        3.3.3 Example livepatch symbol names
  27        3.3.4 Example `readelf --symbols` output
  28 4. Symbol table and Elf section access
  29
  30 ----------------------------
  31 0. Background and motivation
  32 ----------------------------
  33
  34 Formerly, livepatch required separate architecture-specific code to write
  35 relocations. However, arch-specific code to write relocations already
  36 exists in the module loader, so this former approach produced redundant
  37 code. So, instead of duplicating code and re-implementing what the module
  38 loader can already do, livepatch leverages existing code in the module
  39 loader to perform the all the arch-specific relocation work. Specifically,
  40 livepatch reuses the apply_relocate_add() function in the module loader to
  41 write relocations. The patch module Elf format described in this document
  42 enables livepatch to be able to do this. The hope is that this will make
  43 livepatch more easily portable to other architectures and reduce the amount
  44 of arch-specific code required to port livepatch to a particular
  45 architecture.
  46
  47 Since apply_relocate_add() requires access to a module's section header
  48 table, symbol table, and relocation section indices, Elf information is
  49 preserved for livepatch modules (see section 4). Livepatch manages its own
  50 relocation sections and symbols, which are described in this document. The
  51 Elf constants used to mark livepatch symbols and relocation sections were
  52 selected from OS-specific ranges according to the definitions from glibc.
  53
  54 0.1 Why does livepatch need to write its own relocations?
  55 ---------------------------------------------------------
  56 A typical livepatch module contains patched versions of functions that can
  57 reference non-exported global symbols and non-included local symbols.
  58 Relocations referencing these types of symbols cannot be left in as-is
  59 since the kernel module loader cannot resolve them and will therefore
  60 reject the livepatch module. Furthermore, we cannot apply relocations that
  61 affect modules not yet loaded at patch module load time (e.g. a patch to a
  62 driver that is not loaded). Formerly, livepatch solved this problem by
  63 embedding special "dynrela" (dynamic rela) sections in the resulting patch
  64 module Elf output. Using these dynrela sections, livepatch could resolve
  65 symbols while taking into account its scope and what module the symbol
  66 belongs to, and then manually apply the dynamic relocations. However this
  67 approach required livepatch to supply arch-specific code in order to write
  68 these relocations. In the new format, livepatch manages its own SHT_RELA
  69 relocation sections in place of dynrela sections, and the symbols that the
  70 relas reference are special livepatch symbols (see section 2 and 3). The
  71 arch-specific livepatch relocation code is replaced by a call to
  72 apply_relocate_add().
  73
  74 ================================
  75 PATCH MODULE FORMAT REQUIREMENTS
  76 ================================
  77
  78 --------------------------
  79 1. Livepatch modinfo field
  80 --------------------------
  81
  82 Livepatch modules are required to have the "livepatch" modinfo attribute.
  83 See the sample livepatch module in samples/livepatch/ for how this is done.
  84
  85 Livepatch modules can be identified by users by using the 'modinfo' command
  86 and looking for the presence of the "livepatch" field. This field is also
  87 used by the kernel module loader to identify livepatch modules.
  88
  89 Example modinfo output:
  90 -----------------------
  91 % modinfo livepatch-meminfo.ko
  92 filename:               livepatch-meminfo.ko
  93 livepatch:              Y
  94 license:                GPL
  95 depends:
  96 vermagic:               4.3.0+ SMP mod_unload
  97
  98 --------------------------------
  99 2. Livepatch relocation sections
 100 --------------------------------
 101
 102 -------------------------------------------
 103 2.1 What are livepatch relocation sections?
 104 -------------------------------------------
 105 A livepatch module manages its own Elf relocation sections to apply
 106 relocations to modules as well as to the kernel (vmlinux) at the
 107 appropriate time. For example, if a patch module patches a driver that is
 108 not currently loaded, livepatch will apply the corresponding livepatch
 109 relocation section(s) to the driver once it loads.
 110
 111 Each "object" (e.g. vmlinux, or a module) within a patch module may have
 112 multiple livepatch relocation sections associated with it (e.g. patches to
 113 multiple functions within the same object). There is a 1-1 correspondence
 114 between a livepatch relocation section and the target section (usually the
 115 text section of a function) to which the relocation(s) apply. It is
 116 also possible for a livepatch module to have no livepatch relocation
 117 sections, as in the case of the sample livepatch module (see
 118 samples/livepatch).
 119
 120 Since Elf information is preserved for livepatch modules (see Section 4), a
 121 livepatch relocation section can be applied simply by passing in the
 122 appropriate section index to apply_relocate_add(), which then uses it to
 123 access the relocation section and apply the relocations.
 124
 125 Every symbol referenced by a rela in a livepatch relocation section is a
 126 livepatch symbol. These must be resolved before livepatch can call
 127 apply_relocate_add(). See Section 3 for more information.
 128
 129 ---------------------------------------
 130 2.2 Livepatch relocation section format
 131 ---------------------------------------
 132
 133 2.2.1 Required flags
 134 --------------------
 135 Livepatch relocation sections must be marked with the SHF_RELA_LIVEPATCH
 136 section flag. See include/uapi/linux/elf.h for the definition. The module
 137 loader recognizes this flag and will avoid applying those relocation sections
 138 at patch module load time. These sections must also be marked with SHF_ALLOC,
 139 so that the module loader doesn't discard them on module load (i.e. they will
 140 be copied into memory along with the other SHF_ALLOC sections).
 141
 142 2.2.2 Required name format
 143 --------------------------
 144 The name of a livepatch relocation section must conform to the following format:
 145
 146 .klp.rela.objname.section_name
 147 ^        ^^     ^ ^          ^
 148 |________||_____| |__________|
 149    [A]      [B]        [C]
 150
 151 [A] The relocation section name is prefixed with the string ".klp.rela."
 152 [B] The name of the object (i.e. "vmlinux" or name of module) to
 153     which the relocation section belongs follows immediately after the prefix.
 154 [C] The actual name of the section to which this relocation section applies.
 155
 156 2.2.3 Example livepatch relocation section names:
 157 -------------------------------------------------
 158 .klp.rela.ext4.text.ext4_attr_store
 159 .klp.rela.vmlinux.text.cmdline_proc_show
 160
 161 2.2.4 Example `readelf --sections` output for a patch
 162 module that patches vmlinux and modules 9p, btrfs, ext4:
 163 --------------------------------------------------------
 164   Section Headers:
 165   [Nr] Name                          Type                    Address          Off    Size   ES Flg Lk Inf Al
 166   [ snip ]
 167   [29] .klp.rela.9p.text.caches.show RELA                    0000000000000000 002d58 0000c0 18 AIo 64   9  8
 168   [30] .klp.rela.btrfs.text.btrfs.feature.attr.show RELA     0000000000000000 002e18 000060 18 AIo 64  11  8
 169   [ snip ]
 170   [34] .klp.rela.ext4.text.ext4.attr.store RELA              0000000000000000 002fd8 0000d8 18 AIo 64  13  8
 171   [35] .klp.rela.ext4.text.ext4.attr.show RELA               0000000000000000 0030b0 000150 18 AIo 64  15  8
 172   [36] .klp.rela.vmlinux.text.cmdline.proc.show RELA         0000000000000000 003200 000018 18 AIo 64  17  8
 173   [37] .klp.rela.vmlinux.text.meminfo.proc.show RELA         0000000000000000 003218 0000f0 18 AIo 64  19  8
 174   [ snip ]                                       ^                                             ^
 175                                                  |                                             |
 176                                                 [*]                                           [*]
 177 [*] Livepatch relocation sections are SHT_RELA sections but with a few special
 178 characteristics. Notice that they are marked SHF_ALLOC ("A") so that they will
 179 not be discarded when the module is loaded into memory, as well as with the
 180 SHF_RELA_LIVEPATCH flag ("o" - for OS-specific).
 181
 182 2.2.5 Example `readelf --relocs` output for a patch module:
 183 -----------------------------------------------------------
 184 Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries:
 185     Offset             Info             Type               Symbol's Value  Symbol's Name + Addend
 186 000000000000001f  0000005e00000002 R_X86_64_PC32          0000000000000000 .klp.sym.vmlinux.printk,0 - 4
 187 0000000000000028  0000003d0000000b R_X86_64_32S           0000000000000000 .klp.sym.btrfs.btrfs_ktype,0 + 0
 188 0000000000000036  0000003b00000002 R_X86_64_PC32          0000000000000000 .klp.sym.btrfs.can_modify_feature.isra.3,0 - 4
 189 000000000000004c  0000004900000002 R_X86_64_PC32          0000000000000000 .klp.sym.vmlinux.snprintf,0 - 4
 190 [ snip ]                                                                   ^
 191                                                                            |
 192                                                                           [*]
 193 [*] Every symbol referenced by a relocation is a livepatch symbol.
 194
 195 --------------------
 196 3. Livepatch symbols
 197 --------------------
 198
 199 -------------------------------
 200 3.1 What are livepatch symbols?
 201 -------------------------------
 202 Livepatch symbols are symbols referred to by livepatch relocation sections.
 203 These are symbols accessed from new versions of functions for patched
 204 objects, whose addresses cannot be resolved by the module loader (because
 205 they are local or unexported global syms). Since the module loader only
 206 resolves exported syms, and not every symbol referenced by the new patched
 207 functions is exported, livepatch symbols were introduced. They are used
 208 also in cases where we cannot immediately know the address of a symbol when
 209 a patch module loads. For example, this is the case when livepatch patches
 210 a module that is not loaded yet. In this case, the relevant livepatch
 211 symbols are resolved simply when the target module loads. In any case, for
 212 any livepatch relocation section, all livepatch symbols referenced by that
 213 section must be resolved before livepatch can call apply_relocate_add() for
 214 that reloc section.
 215
 216 Livepatch symbols must be marked with SHN_LIVEPATCH so that the module
 217 loader can identify and ignore them. Livepatch modules keep these symbols
 218 in their symbol tables, and the symbol table is made accessible through
 219 module->symtab.
 220
 221 -------------------------------------
 222 3.2 A livepatch module's symbol table
 223 -------------------------------------
 224 Normally, a stripped down copy of a module's symbol table (containing only
 225 "core" symbols) is made available through module->symtab (See layout_symtab()
 226 in kernel/module.c). For livepatch modules, the symbol table copied into memory
 227 on module load must be exactly the same as the symbol table produced when the
 228 patch module was compiled. This is because the relocations in each livepatch
 229 relocation section refer to their respective symbols with their symbol indices,
 230 and the original symbol indices (and thus the symtab ordering) must be
 231 preserved in order for apply_relocate_add() to find the right symbol.
 232
 233 For example, take this particular rela from a livepatch module:
 234 Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries:
 235     Offset             Info             Type               Symbol's Value  Symbol's Name + Addend
 236 000000000000001f  0000005e00000002 R_X86_64_PC32          0000000000000000 .klp.sym.vmlinux.printk,0 - 4
 237
 238 This rela refers to the symbol '.klp.sym.vmlinux.printk,0', and the symbol index is encoded
 239 in 'Info'. Here its symbol index is 0x5e, which is 94 in decimal, which refers to the
 240 symbol index 94.
 241 And in this patch module's corresponding symbol table, symbol index 94 refers to that very symbol:
 242 [ snip ]
 243 94: 0000000000000000     0 NOTYPE  GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.printk,0
 244 [ snip ]
 245
 246 ---------------------------
 247 3.3 Livepatch symbol format
 248 ---------------------------
 249
 250 3.3.1 Required flags
 251 --------------------
 252 Livepatch symbols must have their section index marked as SHN_LIVEPATCH, so
 253 that the module loader can identify them and not attempt to resolve them.
 254 See include/uapi/linux/elf.h for the actual definitions.
 255
 256 3.3.2 Required name format
 257 --------------------------
 258 Livepatch symbol names must conform to the following format:
 259
 260 .klp.sym.objname.symbol_name,sympos
 261 ^       ^^     ^ ^         ^ ^
 262 |_______||_____| |_________| |
 263    [A]     [B]       [C]    [D]
 264
 265 [A] The symbol name is prefixed with the string ".klp.sym."
 266 [B] The name of the object (i.e. "vmlinux" or name of module) to
 267     which the symbol belongs follows immediately after the prefix.
 268 [C] The actual name of the symbol.
 269 [D] The position of the symbol in the object (as according to kallsyms)
 270     This is used to differentiate duplicate symbols within the same
 271     object. The symbol position is expressed numerically (0, 1, 2...).
 272     The symbol position of a unique symbol is 0.
 273
 274 3.3.3 Example livepatch symbol names:
 275 -------------------------------------
 276 .klp.sym.vmlinux.snprintf,0
 277 .klp.sym.vmlinux.printk,0
 278 .klp.sym.btrfs.btrfs_ktype,0
 279
 280 3.3.4 Example `readelf --symbols` output for a patch module:
 281 ------------------------------------------------------------
 282 Symbol table '.symtab' contains 127 entries:
 283    Num:    Value          Size Type    Bind   Vis     Ndx         Name
 284    [ snip ]
 285     73: 0000000000000000     0 NOTYPE  GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.snprintf,0
 286     74: 0000000000000000     0 NOTYPE  GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.capable,0
 287     75: 0000000000000000     0 NOTYPE  GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.find_next_bit,0
 288     76: 0000000000000000     0 NOTYPE  GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.si_swapinfo,0
 289   [ snip ]                                               ^
 290                                                          |
 291                                                         [*]
 292 [*] Note that the 'Ndx' (Section index) for these symbols is SHN_LIVEPATCH (0xff20).
 293     "OS" means OS-specific.
 294
 295 --------------------------------------
 296 4. Symbol table and Elf section access
 297 --------------------------------------
 298 A livepatch module's symbol table is accessible through module->symtab.
 299
 300 Since apply_relocate_add() requires access to a module's section headers,
 301 symbol table, and relocation section indices, Elf information is preserved for
 302 livepatch modules and is made accessible by the module loader through
 303 module->klp_info, which is a klp_modinfo struct. When a livepatch module loads,
 304 this struct is filled in by the module loader. Its fields are documented below:
 305
 306 struct klp_modinfo {
 307         Elf_Ehdr hdr; /* Elf header */
 308         Elf_Shdr *sechdrs; /* Section header table */
 309         char *secstrings; /* String table for the section headers */
 310         unsigned int symndx; /* The symbol table section index */
 311 };