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 | ||
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 | |
5ad75fcd JY |
28 | 4. Architecture-specific sections |
29 | 5. Symbol table and Elf section access | |
3b812ecc JY |
30 | |
31 | ---------------------------- | |
32 | 0. Background and motivation | |
33 | ---------------------------- | |
34 | ||
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. | |
47 | ||
48 | Since apply_relocate_add() requires access to a module's section header | |
49 | table, symbol table, and relocation section indices, Elf information is | |
5ad75fcd | 50 | preserved for livepatch modules (see section 5). Livepatch manages its own |
3b812ecc JY |
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. | |
54 | ||
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(). | |
74 | ||
75 | ================================ | |
76 | PATCH MODULE FORMAT REQUIREMENTS | |
77 | ================================ | |
78 | ||
79 | -------------------------- | |
80 | 1. Livepatch modinfo field | |
81 | -------------------------- | |
82 | ||
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. | |
85 | ||
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. | |
89 | ||
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 | |
98 | ||
99 | -------------------------------- | |
100 | 2. Livepatch relocation sections | |
101 | -------------------------------- | |
102 | ||
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. | |
111 | ||
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). | |
120 | ||
5ad75fcd | 121 | Since Elf information is preserved for livepatch modules (see Section 5), a |
3b812ecc JY |
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. | |
125 | ||
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. | |
129 | ||
130 | --------------------------------------- | |
131 | 2.2 Livepatch relocation section format | |
132 | --------------------------------------- | |
133 | ||
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). | |
142 | ||
143 | 2.2.2 Required name format | |
144 | -------------------------- | |
145 | The name of a livepatch relocation section must conform to the following format: | |
146 | ||
147 | .klp.rela.objname.section_name | |
148 | ^ ^^ ^ ^ ^ | |
149 | |________||_____| |__________| | |
150 | [A] [B] [C] | |
151 | ||
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. | |
156 | ||
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 | |
161 | ||
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). | |
182 | ||
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. | |
195 | ||
196 | -------------------- | |
197 | 3. Livepatch symbols | |
198 | -------------------- | |
199 | ||
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. | |
216 | ||
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. | |
221 | ||
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. | |
233 | ||
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 | |
238 | ||
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 ] | |
246 | ||
247 | --------------------------- | |
248 | 3.3 Livepatch symbol format | |
249 | --------------------------- | |
250 | ||
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. | |
256 | ||
257 | 3.3.2 Required name format | |
258 | -------------------------- | |
259 | Livepatch symbol names must conform to the following format: | |
260 | ||
261 | .klp.sym.objname.symbol_name,sympos | |
262 | ^ ^^ ^ ^ ^ ^ | |
263 | |_______||_____| |_________| | | |
264 | [A] [B] [C] [D] | |
265 | ||
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. | |
274 | ||
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 | |
280 | ||
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. | |
295 | ||
5ad75fcd JY |
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). | |
306 | ||
3b812ecc | 307 | -------------------------------------- |
5ad75fcd | 308 | 5. Symbol table and Elf section access |
3b812ecc JY |
309 | -------------------------------------- |
310 | A livepatch module's symbol table is accessible through module->symtab. | |
311 | ||
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: | |
317 | ||
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 | }; |