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