| 1 | ===========================
|
| 2 | Livepatch module ELF format
|
| 3 | ===========================
|
| 4 |
|
| 5 | This document outlines the ELF format requirements that livepatch modules must follow.
|
| 6 |
|
| 7 |
|
| 8 | |
| 9 |
|
| 10 | .. contents:: :local:
|
| 11 |
|
| 12 |
|
| 13 | 1. Background and motivation
|
| 14 | ============================
|
| 15 |
|
| 16 | Formerly, livepatch required separate architecture-specific code to write
|
| 17 | relocations. However, arch-specific code to write relocations already
|
| 18 | exists in the module loader, so this former approach produced redundant
|
| 19 | code. So, instead of duplicating code and re-implementing what the module
|
| 20 | loader can already do, livepatch leverages existing code in the module
|
| 21 | loader to perform the all the arch-specific relocation work. Specifically,
|
| 22 | livepatch reuses the apply_relocate_add() function in the module loader to
|
| 23 | write relocations. The patch module ELF format described in this document
|
| 24 | enables livepatch to be able to do this. The hope is that this will make
|
| 25 | livepatch more easily portable to other architectures and reduce the amount
|
| 26 | of arch-specific code required to port livepatch to a particular
|
| 27 | architecture.
|
| 28 |
|
| 29 | Since apply_relocate_add() requires access to a module's section header
|
| 30 | table, symbol table, and relocation section indices, ELF information is
|
| 31 | preserved for livepatch modules (see section 5). Livepatch manages its own
|
| 32 | relocation sections and symbols, which are described in this document. The
|
| 33 | ELF constants used to mark livepatch symbols and relocation sections were
|
| 34 | selected from OS-specific ranges according to the definitions from glibc.
|
| 35 |
|
| 36 | Why does livepatch need to write its own relocations?
|
| 37 | -----------------------------------------------------
|
| 38 | A typical livepatch module contains patched versions of functions that can
|
| 39 | reference non-exported global symbols and non-included local symbols.
|
| 40 | Relocations referencing these types of symbols cannot be left in as-is
|
| 41 | since the kernel module loader cannot resolve them and will therefore
|
| 42 | reject the livepatch module. Furthermore, we cannot apply relocations that
|
| 43 | affect modules not yet loaded at patch module load time (e.g. a patch to a
|
| 44 | driver that is not loaded). Formerly, livepatch solved this problem by
|
| 45 | embedding special "dynrela" (dynamic rela) sections in the resulting patch
|
| 46 | module ELF output. Using these dynrela sections, livepatch could resolve
|
| 47 | symbols while taking into account its scope and what module the symbol
|
| 48 | belongs to, and then manually apply the dynamic relocations. However this
|
| 49 | approach required livepatch to supply arch-specific code in order to write
|
| 50 | these relocations. In the new format, livepatch manages its own SHT_RELA
|
| 51 | relocation sections in place of dynrela sections, and the symbols that the
|
| 52 | relas reference are special livepatch symbols (see section 2 and 3). The
|
| 53 | arch-specific livepatch relocation code is replaced by a call to
|
| 54 | apply_relocate_add().
|
| 55 |
|
| 56 | 2. Livepatch modinfo field
|
| 57 | ==========================
|
| 58 |
|
| 59 | Livepatch modules are required to have the "livepatch" modinfo attribute.
|
| 60 | See the sample livepatch module in samples/livepatch/ for how this is done.
|
| 61 |
|
| 62 | Livepatch modules can be identified by users by using the 'modinfo' command
|
| 63 | and looking for the presence of the "livepatch" field. This field is also
|
| 64 | used by the kernel module loader to identify livepatch modules.
|
| 65 |
|
| 66 | Example:
|
| 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 |
|
| 80 | 3. Livepatch relocation sections
|
| 81 | ================================
|
| 82 |
|
| 83 | A livepatch module manages its own ELF relocation sections to apply
|
| 84 | relocations to modules as well as to the kernel (vmlinux) at the
|
| 85 | appropriate time. For example, if a patch module patches a driver that is
|
| 86 | not currently loaded, livepatch will apply the corresponding livepatch
|
| 87 | relocation section(s) to the driver once it loads.
|
| 88 |
|
| 89 | Each "object" (e.g. vmlinux, or a module) within a patch module may have
|
| 90 | multiple livepatch relocation sections associated with it (e.g. patches to
|
| 91 | multiple functions within the same object). There is a 1-1 correspondence
|
| 92 | between a livepatch relocation section and the target section (usually the
|
| 93 | text section of a function) to which the relocation(s) apply. It is
|
| 94 | also possible for a livepatch module to have no livepatch relocation
|
| 95 | sections, as in the case of the sample livepatch module (see
|
| 96 | samples/livepatch).
|
| 97 |
|
| 98 | Since ELF information is preserved for livepatch modules (see Section 5), a
|
| 99 | livepatch relocation section can be applied simply by passing in the
|
| 100 | appropriate section index to apply_relocate_add(), which then uses it to
|
| 101 | access the relocation section and apply the relocations.
|
| 102 |
|
| 103 | Every symbol referenced by a rela in a livepatch relocation section is a
|
| 104 | livepatch symbol. These must be resolved before livepatch can call
|
| 105 | apply_relocate_add(). See Section 3 for more information.
|
| 106 |
|
| 107 | 3.1 Livepatch relocation section format
|
| 108 | =======================================
|
| 109 |
|
| 110 | Livepatch relocation sections must be marked with the SHF_RELA_LIVEPATCH
|
| 111 | section flag. See include/uapi/linux/elf.h for the definition. The module
|
| 112 | loader recognizes this flag and will avoid applying those relocation sections
|
| 113 | at patch module load time. These sections must also be marked with SHF_ALLOC,
|
| 114 | so that the module loader doesn't discard them on module load (i.e. they will
|
| 115 | be copied into memory along with the other SHF_ALLOC sections).
|
| 116 |
|
| 117 | The name of a livepatch relocation section must conform to the following
|
| 118 | format::
|
| 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 |
|
| 135 | Examples:
|
| 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
|
| 146 | module 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 |
|
| 187 | 4. Livepatch symbols
|
| 188 | ====================
|
| 189 |
|
| 190 | Livepatch symbols are symbols referred to by livepatch relocation sections.
|
| 191 | These are symbols accessed from new versions of functions for patched
|
| 192 | objects, whose addresses cannot be resolved by the module loader (because
|
| 193 | they are local or unexported global syms). Since the module loader only
|
| 194 | resolves exported syms, and not every symbol referenced by the new patched
|
| 195 | functions is exported, livepatch symbols were introduced. They are used
|
| 196 | also in cases where we cannot immediately know the address of a symbol when
|
| 197 | a patch module loads. For example, this is the case when livepatch patches
|
| 198 | a module that is not loaded yet. In this case, the relevant livepatch
|
| 199 | symbols are resolved simply when the target module loads. In any case, for
|
| 200 | any livepatch relocation section, all livepatch symbols referenced by that
|
| 201 | section must be resolved before livepatch can call apply_relocate_add() for
|
| 202 | that reloc section.
|
| 203 |
|
| 204 | Livepatch symbols must be marked with SHN_LIVEPATCH so that the module
|
| 205 | loader can identify and ignore them. Livepatch modules keep these symbols
|
| 206 | in their symbol tables, and the symbol table is made accessible through
|
| 207 | module->symtab.
|
| 208 |
|
| 209 | 4.1 A livepatch module's symbol table
|
| 210 | =====================================
|
| 211 | Normally, a stripped down copy of a module's symbol table (containing only
|
| 212 | "core" symbols) is made available through module->symtab (See layout_symtab()
|
| 213 | in kernel/module/kallsyms.c). For livepatch modules, the symbol table copied
|
| 214 | into memory on module load must be exactly the same as the symbol table produced
|
| 215 | when the patch module was compiled. This is because the relocations in each
|
| 216 | livepatch relocation section refer to their respective symbols with their symbol
|
| 217 | indices, and the original symbol indices (and thus the symtab ordering) must be
|
| 218 | preserved in order for apply_relocate_add() to find the right symbol.
|
| 219 |
|
| 220 | For 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
|
| 227 | index is encoded in 'Info'. Here its symbol index is 0x5e, which is 94 in
|
| 228 | decimal, which refers to the symbol index 94.
|
| 229 |
|
| 230 | And in this patch module's corresponding symbol table, symbol index 94 refers
|
| 231 | to that very symbol::
|
| 232 |
|
| 233 | [ snip ]
|
| 234 | 94: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.printk,0
|
| 235 | [ snip ]
|
| 236 |
|
| 237 | 4.2 Livepatch symbol format
|
| 238 | ===========================
|
| 239 |
|
| 240 | Livepatch symbols must have their section index marked as SHN_LIVEPATCH, so
|
| 241 | that the module loader can identify them and not attempt to resolve them.
|
| 242 | See include/uapi/linux/elf.h for the actual definitions.
|
| 243 |
|
| 244 | Livepatch symbol names must conform to the following format::
|
| 245 |
|
| 246 | .klp.sym.objname.symbol_name,sympos
|
| 247 | ^ ^^ ^ ^ ^ ^
|
| 248 | |_______||_____| |_________| |
|
| 249 | [A] [B] [C] [D]
|
| 250 |
|
| 251 | [A]
|
| 252 | The symbol name is prefixed with the string ".klp.sym."
|
| 253 |
|
| 254 | [B]
|
| 255 | The name of the object (i.e. "vmlinux" or name of module) to
|
| 256 | which the symbol belongs follows immediately after the prefix.
|
| 257 |
|
| 258 | [C]
|
| 259 | The actual name of the symbol.
|
| 260 |
|
| 261 | [D]
|
| 262 | The position of the symbol in the object (as according to kallsyms)
|
| 263 | This is used to differentiate duplicate symbols within the same
|
| 264 | object. The symbol position is expressed numerically (0, 1, 2...).
|
| 265 | The symbol position of a unique symbol is 0.
|
| 266 |
|
| 267 | Examples:
|
| 268 | ---------
|
| 269 |
|
| 270 | **Livepatch symbol names:**
|
| 271 |
|
| 272 | ::
|
| 273 |
|
| 274 | .klp.sym.vmlinux.snprintf,0
|
| 275 | .klp.sym.vmlinux.printk,0
|
| 276 | .klp.sym.btrfs.btrfs_ktype,0
|
| 277 |
|
| 278 | **`readelf --symbols` output for a patch module:**
|
| 279 |
|
| 280 | ::
|
| 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 |
|
| 293 | [*]
|
| 294 | Note that the 'Ndx' (Section index) for these symbols is SHN_LIVEPATCH (0xff20).
|
| 295 | "OS" means OS-specific.
|
| 296 |
|
| 297 | 5. Symbol table and ELF section access
|
| 298 | ======================================
|
| 299 | A livepatch module's symbol table is accessible through module->symtab.
|
| 300 |
|
| 301 | Since apply_relocate_add() requires access to a module's section headers,
|
| 302 | symbol table, and relocation section indices, ELF information is preserved for
|
| 303 | livepatch modules and is made accessible by the module loader through
|
| 304 | module->klp_info, which is a :c:type:`klp_modinfo` struct. When a livepatch module
|
| 305 | loads, this struct is filled in by the module loader.
|