0001 ===========================
0002 Livepatch module Elf format
0003 ===========================
0004
0005 This document outlines the Elf format requirements that livepatch modules must follow.
0006
0007
0008 .. Table of Contents
0009
0010 .. contents:: :local:
0011
0012
0013 1. Background and motivation
0014 ============================
0015
0016 Formerly, livepatch required separate architecture-specific code to write
0017 relocations. However, arch-specific code to write relocations already
0018 exists in the module loader, so this former approach produced redundant
0019 code. So, instead of duplicating code and re-implementing what the module
0020 loader can already do, livepatch leverages existing code in the module
0021 loader to perform the all the arch-specific relocation work. Specifically,
0022 livepatch reuses the apply_relocate_add() function in the module loader to
0023 write relocations. The patch module Elf format described in this document
0024 enables livepatch to be able to do this. The hope is that this will make
0025 livepatch more easily portable to other architectures and reduce the amount
0026 of arch-specific code required to port livepatch to a particular
0027 architecture.
0028
0029 Since apply_relocate_add() requires access to a module's section header
0030 table, symbol table, and relocation section indices, Elf information is
0031 preserved for livepatch modules (see section 5). Livepatch manages its own
0032 relocation sections and symbols, which are described in this document. The
0033 Elf constants used to mark livepatch symbols and relocation sections were
0034 selected from OS-specific ranges according to the definitions from glibc.
0035
0036 Why does livepatch need to write its own relocations?
0037 -----------------------------------------------------
0038 A typical livepatch module contains patched versions of functions that can
0039 reference non-exported global symbols and non-included local symbols.
0040 Relocations referencing these types of symbols cannot be left in as-is
0041 since the kernel module loader cannot resolve them and will therefore
0042 reject the livepatch module. Furthermore, we cannot apply relocations that
0043 affect modules not yet loaded at patch module load time (e.g. a patch to a
0044 driver that is not loaded). Formerly, livepatch solved this problem by
0045 embedding special "dynrela" (dynamic rela) sections in the resulting patch
0046 module Elf output. Using these dynrela sections, livepatch could resolve
0047 symbols while taking into account its scope and what module the symbol
0048 belongs to, and then manually apply the dynamic relocations. However this
0049 approach required livepatch to supply arch-specific code in order to write
0050 these relocations. In the new format, livepatch manages its own SHT_RELA
0051 relocation sections in place of dynrela sections, and the symbols that the
0052 relas reference are special livepatch symbols (see section 2 and 3). The
0053 arch-specific livepatch relocation code is replaced by a call to
0054 apply_relocate_add().
0055
0056 2. Livepatch modinfo field
0057 ==========================
0058
0059 Livepatch modules are required to have the "livepatch" modinfo attribute.
0060 See the sample livepatch module in samples/livepatch/ for how this is done.
0061
0062 Livepatch modules can be identified by users by using the 'modinfo' command
0063 and looking for the presence of the "livepatch" field. This field is also
0064 used by the kernel module loader to identify livepatch modules.
0065
0066 Example:
0067 --------
0068
0069 **Modinfo output:**
0070
0071 ::
0072
0073 % modinfo livepatch-meminfo.ko
0074 filename: livepatch-meminfo.ko
0075 livepatch: Y
0076 license: GPL
0077 depends:
0078 vermagic: 4.3.0+ SMP mod_unload
0079
0080 3. Livepatch relocation sections
0081 ================================
0082
0083 A livepatch module manages its own Elf relocation sections to apply
0084 relocations to modules as well as to the kernel (vmlinux) at the
0085 appropriate time. For example, if a patch module patches a driver that is
0086 not currently loaded, livepatch will apply the corresponding livepatch
0087 relocation section(s) to the driver once it loads.
0088
0089 Each "object" (e.g. vmlinux, or a module) within a patch module may have
0090 multiple livepatch relocation sections associated with it (e.g. patches to
0091 multiple functions within the same object). There is a 1-1 correspondence
0092 between a livepatch relocation section and the target section (usually the
0093 text section of a function) to which the relocation(s) apply. It is
0094 also possible for a livepatch module to have no livepatch relocation
0095 sections, as in the case of the sample livepatch module (see
0096 samples/livepatch).
0097
0098 Since Elf information is preserved for livepatch modules (see Section 5), a
0099 livepatch relocation section can be applied simply by passing in the
0100 appropriate section index to apply_relocate_add(), which then uses it to
0101 access the relocation section and apply the relocations.
0102
0103 Every symbol referenced by a rela in a livepatch relocation section is a
0104 livepatch symbol. These must be resolved before livepatch can call
0105 apply_relocate_add(). See Section 3 for more information.
0106
0107 3.1 Livepatch relocation section format
0108 =======================================
0109
0110 Livepatch relocation sections must be marked with the SHF_RELA_LIVEPATCH
0111 section flag. See include/uapi/linux/elf.h for the definition. The module
0112 loader recognizes this flag and will avoid applying those relocation sections
0113 at patch module load time. These sections must also be marked with SHF_ALLOC,
0114 so that the module loader doesn't discard them on module load (i.e. they will
0115 be copied into memory along with the other SHF_ALLOC sections).
0116
0117 The name of a livepatch relocation section must conform to the following
0118 format::
0119
0120 .klp.rela.objname.section_name
0121 ^ ^^ ^ ^ ^
0122 |________||_____| |__________|
0123 [A] [B] [C]
0124
0125 [A]
0126 The relocation section name is prefixed with the string ".klp.rela."
0127
0128 [B]
0129 The name of the object (i.e. "vmlinux" or name of module) to
0130 which the relocation section belongs follows immediately after the prefix.
0131
0132 [C]
0133 The actual name of the section to which this relocation section applies.
0134
0135 Examples:
0136 ---------
0137
0138 **Livepatch relocation section names:**
0139
0140 ::
0141
0142 .klp.rela.ext4.text.ext4_attr_store
0143 .klp.rela.vmlinux.text.cmdline_proc_show
0144
0145 **`readelf --sections` output for a patch
0146 module that patches vmlinux and modules 9p, btrfs, ext4:**
0147
0148 ::
0149
0150 Section Headers:
0151 [Nr] Name Type Address Off Size ES Flg Lk Inf Al
0152 [ snip ]
0153 [29] .klp.rela.9p.text.caches.show RELA 0000000000000000 002d58 0000c0 18 AIo 64 9 8
0154 [30] .klp.rela.btrfs.text.btrfs.feature.attr.show RELA 0000000000000000 002e18 000060 18 AIo 64 11 8
0155 [ snip ]
0156 [34] .klp.rela.ext4.text.ext4.attr.store RELA 0000000000000000 002fd8 0000d8 18 AIo 64 13 8
0157 [35] .klp.rela.ext4.text.ext4.attr.show RELA 0000000000000000 0030b0 000150 18 AIo 64 15 8
0158 [36] .klp.rela.vmlinux.text.cmdline.proc.show RELA 0000000000000000 003200 000018 18 AIo 64 17 8
0159 [37] .klp.rela.vmlinux.text.meminfo.proc.show RELA 0000000000000000 003218 0000f0 18 AIo 64 19 8
0160 [ snip ] ^ ^
0161 | |
0162 [*] [*]
0163
0164 [*]
0165 Livepatch relocation sections are SHT_RELA sections but with a few special
0166 characteristics. Notice that they are marked SHF_ALLOC ("A") so that they will
0167 not be discarded when the module is loaded into memory, as well as with the
0168 SHF_RELA_LIVEPATCH flag ("o" - for OS-specific).
0169
0170 **`readelf --relocs` output for a patch module:**
0171
0172 ::
0173
0174 Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries:
0175 Offset Info Type Symbol's Value Symbol's Name + Addend
0176 000000000000001f 0000005e00000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.printk,0 - 4
0177 0000000000000028 0000003d0000000b R_X86_64_32S 0000000000000000 .klp.sym.btrfs.btrfs_ktype,0 + 0
0178 0000000000000036 0000003b00000002 R_X86_64_PC32 0000000000000000 .klp.sym.btrfs.can_modify_feature.isra.3,0 - 4
0179 000000000000004c 0000004900000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.snprintf,0 - 4
0180 [ snip ] ^
0181 |
0182 [*]
0183
0184 [*]
0185 Every symbol referenced by a relocation is a livepatch symbol.
0186
0187 4. Livepatch symbols
0188 ====================
0189
0190 Livepatch symbols are symbols referred to by livepatch relocation sections.
0191 These are symbols accessed from new versions of functions for patched
0192 objects, whose addresses cannot be resolved by the module loader (because
0193 they are local or unexported global syms). Since the module loader only
0194 resolves exported syms, and not every symbol referenced by the new patched
0195 functions is exported, livepatch symbols were introduced. They are used
0196 also in cases where we cannot immediately know the address of a symbol when
0197 a patch module loads. For example, this is the case when livepatch patches
0198 a module that is not loaded yet. In this case, the relevant livepatch
0199 symbols are resolved simply when the target module loads. In any case, for
0200 any livepatch relocation section, all livepatch symbols referenced by that
0201 section must be resolved before livepatch can call apply_relocate_add() for
0202 that reloc section.
0203
0204 Livepatch symbols must be marked with SHN_LIVEPATCH so that the module
0205 loader can identify and ignore them. Livepatch modules keep these symbols
0206 in their symbol tables, and the symbol table is made accessible through
0207 module->symtab.
0208
0209 4.1 A livepatch module's symbol table
0210 =====================================
0211 Normally, a stripped down copy of a module's symbol table (containing only
0212 "core" symbols) is made available through module->symtab (See layout_symtab()
0213 in kernel/module/kallsyms.c). For livepatch modules, the symbol table copied
0214 into memory on module load must be exactly the same as the symbol table produced
0215 when the patch module was compiled. This is because the relocations in each
0216 livepatch relocation section refer to their respective symbols with their symbol
0217 indices, and the original symbol indices (and thus the symtab ordering) must be
0218 preserved in order for apply_relocate_add() to find the right symbol.
0219
0220 For example, take this particular rela from a livepatch module:::
0221
0222 Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries:
0223 Offset Info Type Symbol's Value Symbol's Name + Addend
0224 000000000000001f 0000005e00000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.printk,0 - 4
0225
0226 This rela refers to the symbol '.klp.sym.vmlinux.printk,0', and the symbol index is encoded
0227 in 'Info'. Here its symbol index is 0x5e, which is 94 in decimal, which refers to the
0228 symbol index 94.
0229 And in this patch module's corresponding symbol table, symbol index 94 refers to that very symbol:
0230 [ snip ]
0231 94: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.printk,0
0232 [ snip ]
0233
0234 4.2 Livepatch symbol format
0235 ===========================
0236
0237 Livepatch symbols must have their section index marked as SHN_LIVEPATCH, so
0238 that the module loader can identify them and not attempt to resolve them.
0239 See include/uapi/linux/elf.h for the actual definitions.
0240
0241 Livepatch symbol names must conform to the following format::
0242
0243 .klp.sym.objname.symbol_name,sympos
0244 ^ ^^ ^ ^ ^ ^
0245 |_______||_____| |_________| |
0246 [A] [B] [C] [D]
0247
0248 [A]
0249 The symbol name is prefixed with the string ".klp.sym."
0250
0251 [B]
0252 The name of the object (i.e. "vmlinux" or name of module) to
0253 which the symbol belongs follows immediately after the prefix.
0254
0255 [C]
0256 The actual name of the symbol.
0257
0258 [D]
0259 The position of the symbol in the object (as according to kallsyms)
0260 This is used to differentiate duplicate symbols within the same
0261 object. The symbol position is expressed numerically (0, 1, 2...).
0262 The symbol position of a unique symbol is 0.
0263
0264 Examples:
0265 ---------
0266
0267 **Livepatch symbol names:**
0268
0269 ::
0270
0271 .klp.sym.vmlinux.snprintf,0
0272 .klp.sym.vmlinux.printk,0
0273 .klp.sym.btrfs.btrfs_ktype,0
0274
0275 **`readelf --symbols` output for a patch module:**
0276
0277 ::
0278
0279 Symbol table '.symtab' contains 127 entries:
0280 Num: Value Size Type Bind Vis Ndx Name
0281 [ snip ]
0282 73: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.snprintf,0
0283 74: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.capable,0
0284 75: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.find_next_bit,0
0285 76: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.si_swapinfo,0
0286 [ snip ] ^
0287 |
0288 [*]
0289
0290 [*]
0291 Note that the 'Ndx' (Section index) for these symbols is SHN_LIVEPATCH (0xff20).
0292 "OS" means OS-specific.
0293
0294 5. Symbol table and Elf section access
0295 ======================================
0296 A livepatch module's symbol table is accessible through module->symtab.
0297
0298 Since apply_relocate_add() requires access to a module's section headers,
0299 symbol table, and relocation section indices, Elf information is preserved for
0300 livepatch modules and is made accessible by the module loader through
0301 module->klp_info, which is a klp_modinfo struct. When a livepatch module loads,
0302 this struct is filled in by the module loader. Its fields are documented below::
0303
0304 struct klp_modinfo {
0305 Elf_Ehdr hdr; /* Elf header */
0306 Elf_Shdr *sechdrs; /* Section header table */
0307 char *secstrings; /* String table for the section headers */
0308 unsigned int symndx; /* The symbol table section index */
0309 };
