1=========================== 2Livepatch module Elf format 3=========================== 4 5This 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 201. Background and motivation 21============================ 22 23Formerly, livepatch required separate architecture-specific code to write 24relocations. However, arch-specific code to write relocations already 25exists in the module loader, so this former approach produced redundant 26code. So, instead of duplicating code and re-implementing what the module 27loader can already do, livepatch leverages existing code in the module 28loader to perform the all the arch-specific relocation work. Specifically, 29livepatch reuses the apply_relocate_add() function in the module loader to 30write relocations. The patch module Elf format described in this document 31enables livepatch to be able to do this. The hope is that this will make 32livepatch more easily portable to other architectures and reduce the amount 33of arch-specific code required to port livepatch to a particular 34architecture. 35 36Since apply_relocate_add() requires access to a module's section header 37table, symbol table, and relocation section indices, Elf information is 38preserved for livepatch modules (see section 5). Livepatch manages its own 39relocation sections and symbols, which are described in this document. The 40Elf constants used to mark livepatch symbols and relocation sections were 41selected from OS-specific ranges according to the definitions from glibc. 42 43Why does livepatch need to write its own relocations? 44----------------------------------------------------- 45A typical livepatch module contains patched versions of functions that can 46reference non-exported global symbols and non-included local symbols. 47Relocations referencing these types of symbols cannot be left in as-is 48since the kernel module loader cannot resolve them and will therefore 49reject the livepatch module. Furthermore, we cannot apply relocations that 50affect modules not yet loaded at patch module load time (e.g. a patch to a 51driver that is not loaded). Formerly, livepatch solved this problem by 52embedding special "dynrela" (dynamic rela) sections in the resulting patch 53module Elf output. Using these dynrela sections, livepatch could resolve 54symbols while taking into account its scope and what module the symbol 55belongs to, and then manually apply the dynamic relocations. However this 56approach required livepatch to supply arch-specific code in order to write 57these relocations. In the new format, livepatch manages its own SHT_RELA 58relocation sections in place of dynrela sections, and the symbols that the 59relas reference are special livepatch symbols (see section 2 and 3). The 60arch-specific livepatch relocation code is replaced by a call to 61apply_relocate_add(). 62 632. Livepatch modinfo field 64========================== 65 66Livepatch modules are required to have the "livepatch" modinfo attribute. 67See the sample livepatch module in samples/livepatch/ for how this is done. 68 69Livepatch modules can be identified by users by using the 'modinfo' command 70and looking for the presence of the "livepatch" field. This field is also 71used by the kernel module loader to identify livepatch modules. 72 73Example: 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 873. Livepatch relocation sections 88================================ 89 90A livepatch module manages its own Elf relocation sections to apply 91relocations to modules as well as to the kernel (vmlinux) at the 92appropriate time. For example, if a patch module patches a driver that is 93not currently loaded, livepatch will apply the corresponding livepatch 94relocation section(s) to the driver once it loads. 95 96Each "object" (e.g. vmlinux, or a module) within a patch module may have 97multiple livepatch relocation sections associated with it (e.g. patches to 98multiple functions within the same object). There is a 1-1 correspondence 99between a livepatch relocation section and the target section (usually the 100text section of a function) to which the relocation(s) apply. It is 101also possible for a livepatch module to have no livepatch relocation 102sections, as in the case of the sample livepatch module (see 103samples/livepatch). 104 105Since Elf information is preserved for livepatch modules (see Section 5), a 106livepatch relocation section can be applied simply by passing in the 107appropriate section index to apply_relocate_add(), which then uses it to 108access the relocation section and apply the relocations. 109 110Every symbol referenced by a rela in a livepatch relocation section is a 111livepatch symbol. These must be resolved before livepatch can call 112apply_relocate_add(). See Section 3 for more information. 113 1143.1 Livepatch relocation section format 115======================================= 116 117Livepatch relocation sections must be marked with the SHF_RELA_LIVEPATCH 118section flag. See include/uapi/linux/elf.h for the definition. The module 119loader recognizes this flag and will avoid applying those relocation sections 120at patch module load time. These sections must also be marked with SHF_ALLOC, 121so that the module loader doesn't discard them on module load (i.e. they will 122be copied into memory along with the other SHF_ALLOC sections). 123 124The name of a livepatch relocation section must conform to the following 125format:: 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 142Examples: 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 153module 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 1944. Livepatch symbols 195==================== 196 197Livepatch symbols are symbols referred to by livepatch relocation sections. 198These are symbols accessed from new versions of functions for patched 199objects, whose addresses cannot be resolved by the module loader (because 200they are local or unexported global syms). Since the module loader only 201resolves exported syms, and not every symbol referenced by the new patched 202functions is exported, livepatch symbols were introduced. They are used 203also in cases where we cannot immediately know the address of a symbol when 204a patch module loads. For example, this is the case when livepatch patches 205a module that is not loaded yet. In this case, the relevant livepatch 206symbols are resolved simply when the target module loads. In any case, for 207any livepatch relocation section, all livepatch symbols referenced by that 208section must be resolved before livepatch can call apply_relocate_add() for 209that reloc section. 210 211Livepatch symbols must be marked with SHN_LIVEPATCH so that the module 212loader can identify and ignore them. Livepatch modules keep these symbols 213in their symbol tables, and the symbol table is made accessible through 214module->symtab. 215 2164.1 A livepatch module's symbol table 217===================================== 218Normally, a stripped down copy of a module's symbol table (containing only 219"core" symbols) is made available through module->symtab (See layout_symtab() 220in kernel/module.c). For livepatch modules, the symbol table copied into memory 221on module load must be exactly the same as the symbol table produced when the 222patch module was compiled. This is because the relocations in each livepatch 223relocation section refer to their respective symbols with their symbol indices, 224and the original symbol indices (and thus the symtab ordering) must be 225preserved in order for apply_relocate_add() to find the right symbol. 226 227For 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 2414.2 Livepatch symbol format 242=========================== 243 244Livepatch symbols must have their section index marked as SHN_LIVEPATCH, so 245that the module loader can identify them and not attempt to resolve them. 246See include/uapi/linux/elf.h for the actual definitions. 247 248Livepatch 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 271Examples: 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 3015. Architecture-specific sections 302================================= 303Architectures may override arch_klp_init_object_loaded() to perform 304additional arch-specific tasks when a target module loads, such as applying 305arch-specific sections. On x86 for example, we must apply per-object 306.altinstructions and .parainstructions sections when a target module loads. 307These sections must be prefixed with ".klp.arch.$objname." so that they can 308be easily identified when iterating through a patch module's Elf sections 309(See arch/x86/kernel/livepatch.c for a complete example). 310 3116. Symbol table and Elf section access 312====================================== 313A livepatch module's symbol table is accessible through module->symtab. 314 315Since apply_relocate_add() requires access to a module's section headers, 316symbol table, and relocation section indices, Elf information is preserved for 317livepatch modules and is made accessible by the module loader through 318module->klp_info, which is a klp_modinfo struct. When a livepatch module loads, 319this 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 }; 327