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