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