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