Documentation/livepatch/module-elf-format.rst

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