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