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