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