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 | ||
7af6fbdd MB |
10 | .. contents:: :local: |
11 | ||
d9defe44 PM |
12 | |
13 | 1. Background and motivation | |
14 | ============================ | |
3b812ecc JY |
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 | |
5ad75fcd | 31 | preserved for livepatch modules (see section 5). Livepatch manages its own |
3b812ecc JY |
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 | ||
d9defe44 PM |
36 | Why does livepatch need to write its own relocations? |
37 | ----------------------------------------------------- | |
3b812ecc JY |
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 | ||
d9defe44 PM |
56 | 2. Livepatch modinfo field |
57 | ========================== | |
3b812ecc JY |
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 | ||
d9defe44 PM |
66 | Example: |
67 | -------- | |
68 | ||
69 | **Modinfo output:** | |
89e33ea7 MCC |
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 | |
3b812ecc | 79 | |
d9defe44 PM |
80 | 3. Livepatch relocation sections |
81 | ================================ | |
3b812ecc | 82 | |
3b812ecc JY |
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 | ||
5ad75fcd | 98 | Since Elf information is preserved for livepatch modules (see Section 5), a |
3b812ecc JY |
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 | ||
d9defe44 PM |
107 | 3.1 Livepatch relocation section format |
108 | ======================================= | |
3b812ecc | 109 | |
3b812ecc JY |
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 | ||
89e33ea7 MCC |
117 | The name of a livepatch relocation section must conform to the following |
118 | format:: | |
3b812ecc | 119 | |
89e33ea7 MCC |
120 | .klp.rela.objname.section_name |
121 | ^ ^^ ^ ^ ^ | |
122 | |________||_____| |__________| | |
123 | [A] [B] [C] | |
3b812ecc | 124 | |
d9defe44 PM |
125 | [A] |
126 | The relocation section name is prefixed with the string ".klp.rela." | |
3b812ecc | 127 | |
d9defe44 PM |
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. | |
3b812ecc | 131 | |
d9defe44 PM |
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:** | |
89e33ea7 MCC |
147 | |
148 | :: | |
149 | ||
3b812ecc JY |
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 | [*] [*] | |
d9defe44 PM |
163 | |
164 | [*] | |
165 | Livepatch relocation sections are SHT_RELA sections but with a few special | |
89e33ea7 MCC |
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). | |
3b812ecc | 169 | |
d9defe44 | 170 | **`readelf --relocs` output for a patch module:** |
89e33ea7 MCC |
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 | | | |
d9defe44 PM |
182 | [*] |
183 | ||
184 | [*] | |
185 | Every symbol referenced by a relocation is a livepatch symbol. | |
3b812ecc | 186 | |
d9defe44 PM |
187 | 4. Livepatch symbols |
188 | ==================== | |
3b812ecc | 189 | |
3b812ecc JY |
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 | ||
d9defe44 PM |
209 | 4.1 A livepatch module's symbol table |
210 | ===================================== | |
3b812ecc JY |
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.c). For livepatch modules, the symbol table copied into memory | |
214 | on module load must be exactly the same as the symbol table produced when the | |
215 | patch module was compiled. This is because the relocations in each livepatch | |
216 | relocation section refer to their respective symbols with their symbol indices, | |
217 | 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 | ||
89e33ea7 | 220 | For example, take this particular rela from a livepatch module::: |
3b812ecc | 221 | |
89e33ea7 MCC |
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 index is encoded | |
227 | in 'Info'. Here its symbol index is 0x5e, which is 94 in decimal, which refers to the | |
228 | symbol index 94. | |
229 | And in this patch module's corresponding symbol table, symbol index 94 refers to that very symbol: | |
230 | [ snip ] | |
231 | 94: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.printk,0 | |
232 | [ snip ] | |
3b812ecc | 233 | |
d9defe44 PM |
234 | 4.2 Livepatch symbol format |
235 | =========================== | |
3b812ecc | 236 | |
3b812ecc JY |
237 | Livepatch symbols must have their section index marked as SHN_LIVEPATCH, so |
238 | that the module loader can identify them and not attempt to resolve them. | |
239 | See include/uapi/linux/elf.h for the actual definitions. | |
240 | ||
89e33ea7 MCC |
241 | Livepatch symbol names must conform to the following format:: |
242 | ||
243 | .klp.sym.objname.symbol_name,sympos | |
244 | ^ ^^ ^ ^ ^ ^ | |
245 | |_______||_____| |_________| | | |
246 | [A] [B] [C] [D] | |
247 | ||
d9defe44 PM |
248 | [A] |
249 | The symbol name is prefixed with the string ".klp.sym." | |
250 | ||
251 | [B] | |
252 | The name of the object (i.e. "vmlinux" or name of module) to | |
253 | which the symbol belongs follows immediately after the prefix. | |
3b812ecc | 254 | |
d9defe44 PM |
255 | [C] |
256 | The actual name of the symbol. | |
257 | ||
258 | [D] | |
259 | The position of the symbol in the object (as according to kallsyms) | |
260 | This is used to differentiate duplicate symbols within the same | |
261 | object. The symbol position is expressed numerically (0, 1, 2...). | |
262 | The symbol position of a unique symbol is 0. | |
263 | ||
264 | Examples: | |
265 | --------- | |
266 | ||
267 | **Livepatch symbol names:** | |
89e33ea7 MCC |
268 | |
269 | :: | |
270 | ||
271 | .klp.sym.vmlinux.snprintf,0 | |
272 | .klp.sym.vmlinux.printk,0 | |
273 | .klp.sym.btrfs.btrfs_ktype,0 | |
3b812ecc | 274 | |
d9defe44 | 275 | **`readelf --symbols` output for a patch module:** |
89e33ea7 MCC |
276 | |
277 | :: | |
278 | ||
279 | Symbol table '.symtab' contains 127 entries: | |
280 | Num: Value Size Type Bind Vis Ndx Name | |
281 | [ snip ] | |
282 | 73: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.snprintf,0 | |
283 | 74: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.capable,0 | |
284 | 75: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.find_next_bit,0 | |
285 | 76: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.si_swapinfo,0 | |
286 | [ snip ] ^ | |
287 | | | |
288 | [*] | |
3b812ecc | 289 | |
d9defe44 PM |
290 | [*] |
291 | Note that the 'Ndx' (Section index) for these symbols is SHN_LIVEPATCH (0xff20). | |
292 | "OS" means OS-specific. | |
293 | ||
1d05334d | 294 | 5. Symbol table and Elf section access |
d9defe44 | 295 | ====================================== |
3b812ecc JY |
296 | A livepatch module's symbol table is accessible through module->symtab. |
297 | ||
298 | Since apply_relocate_add() requires access to a module's section headers, | |
299 | symbol table, and relocation section indices, Elf information is preserved for | |
300 | livepatch modules and is made accessible by the module loader through | |
301 | module->klp_info, which is a klp_modinfo struct. When a livepatch module loads, | |
89e33ea7 MCC |
302 | this struct is filled in by the module loader. Its fields are documented below:: |
303 | ||
304 | struct klp_modinfo { | |
305 | Elf_Ehdr hdr; /* Elf header */ | |
306 | Elf_Shdr *sechdrs; /* Section header table */ | |
307 | char *secstrings; /* String table for the section headers */ | |
308 | unsigned int symndx; /* The symbol table section index */ | |
309 | }; |