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