Livepatch module Elf format

This document outlines the Elf format requirements that livepatch modules must follow.

1. Background and motivation

Formerly, livepatch required separate architecture-specific code to writerelocations. However, arch-specific code to write relocations alreadyexists in the module loader, so this former approach produced redundantcode. So, instead of duplicating code and re-implementing what the moduleloader can already do, livepatch leverages existing code in the moduleloader to perform the all the arch-specific relocation work. Specifically,livepatch reuses the apply_relocate_add() function in the module loader towrite relocations. The patch module Elf format described in this documentenables livepatch to be able to do this. The hope is that this will makelivepatch more easily portable to other architectures and reduce the amountof arch-specific code required to port livepatch to a particulararchitecture.

Since apply_relocate_add() requires access to a module’s section headertable, symbol table, and relocation section indices, Elf information ispreserved for livepatch modules (see section 5). Livepatch manages its ownrelocation sections and symbols, which are described in this document. TheElf constants used to mark livepatch symbols and relocation sections wereselected from OS-specific ranges according to the definitions from glibc.

Why does livepatch need to write its own relocations?

A typical livepatch module contains patched versions of functions that canreference non-exported global symbols and non-included local symbols.Relocations referencing these types of symbols cannot be left in as-issince the kernel module loader cannot resolve them and will thereforereject the livepatch module. Furthermore, we cannot apply relocations thataffect modules not yet loaded at patch module load time (e.g. a patch to adriver that is not loaded). Formerly, livepatch solved this problem byembedding special “dynrela” (dynamic rela) sections in the resulting patchmodule Elf output. Using these dynrela sections, livepatch could resolvesymbols while taking into account its scope and what module the symbolbelongs to, and then manually apply the dynamic relocations. However thisapproach required livepatch to supply arch-specific code in order to writethese relocations. In the new format, livepatch manages its own SHT_RELArelocation sections in place of dynrela sections, and the symbols that therelas reference are special livepatch symbols (see section 2 and 3). Thearch-specific livepatch relocation code is replaced by a call toapply_relocate_add().

2. Livepatch modinfo field

Livepatch modules are required to have the “livepatch” modinfo attribute.See the sample livepatch module in samples/livepatch/ for how this is done.

Livepatch modules can be identified by users by using the ‘modinfo’ commandand looking for the presence of the “livepatch” field. This field is alsoused by the kernel module loader to identify livepatch modules.

Example:

Modinfo output:

% modinfo livepatch-meminfo.kofilename:               livepatch-meminfo.kolivepatch:              Ylicense:                GPLdepends:vermagic:               4.3.0+ SMP mod_unload

3. Livepatch relocation sections

A livepatch module manages its own Elf relocation sections to applyrelocations to modules as well as to the kernel (vmlinux) at theappropriate time. For example, if a patch module patches a driver that isnot currently loaded, livepatch will apply the corresponding livepatchrelocation section(s) to the driver once it loads.

Each “object” (e.g. vmlinux, or a module) within a patch module may havemultiple livepatch relocation sections associated with it (e.g. patches tomultiple functions within the same object). There is a 1-1 correspondencebetween a livepatch relocation section and the target section (usually thetext section of a function) to which the relocation(s) apply. It isalso possible for a livepatch module to have no livepatch relocationsections, as in the case of the sample livepatch module (seesamples/livepatch).

Since Elf information is preserved for livepatch modules (see Section 5), alivepatch relocation section can be applied simply by passing in theappropriate section index to apply_relocate_add(), which then uses it toaccess the relocation section and apply the relocations.

Every symbol referenced by a rela in a livepatch relocation section is alivepatch symbol. These must be resolved before livepatch can callapply_relocate_add(). See Section 3 for more information.

3.1 Livepatch relocation section format

Livepatch relocation sections must be marked with the SHF_RELA_LIVEPATCHsection flag. See include/uapi/linux/elf.h for the definition. The moduleloader recognizes this flag and will avoid applying those relocation sectionsat patch module load time. These sections must also be marked with SHF_ALLOC,so that the module loader doesn’t discard them on module load (i.e. they willbe copied into memory along with the other SHF_ALLOC sections).

The name of a livepatch relocation section must conform to the followingformat:

.klp.rela.objname.section_name^        ^^     ^ ^          ^|________||_____| |__________|   [A]      [B]        [C]
[A]
The relocation section name is prefixed with the string “.klp.rela.”
[B]
The name of the object (i.e. “vmlinux” or name of module) towhich the relocation section belongs follows immediately after the prefix.
[C]
The actual name of the section to which this relocation section applies.

Examples:

Livepatch relocation section names:

.klp.rela.ext4.text.ext4_attr_store.klp.rela.vmlinux.text.cmdline_proc_show

`readelf –sections` output for a patchmodule that patches vmlinux and modules 9p, btrfs, ext4:

Section Headers:[Nr] Name                          Type                    Address          Off    Size   ES Flg Lk Inf Al[ snip ][29] .klp.rela.9p.text.caches.show RELA                    0000000000000000 002d58 0000c0 18 AIo 64   9  8[30] .klp.rela.btrfs.text.btrfs.feature.attr.show RELA     0000000000000000 002e18 000060 18 AIo 64  11  8[ snip ][34] .klp.rela.ext4.text.ext4.attr.store RELA              0000000000000000 002fd8 0000d8 18 AIo 64  13  8[35] .klp.rela.ext4.text.ext4.attr.show RELA               0000000000000000 0030b0 000150 18 AIo 64  15  8[36] .klp.rela.vmlinux.text.cmdline.proc.show RELA         0000000000000000 003200 000018 18 AIo 64  17  8[37] .klp.rela.vmlinux.text.meminfo.proc.show RELA         0000000000000000 003218 0000f0 18 AIo 64  19  8[ snip ]                                       ^                                             ^                                               |                                             |                                              [*]                                           [*]
[*]
Livepatch relocation sections are SHT_RELA sections but with a few specialcharacteristics. Notice that they are marked SHF_ALLOC (“A”) so that they willnot be discarded when the module is loaded into memory, as well as with theSHF_RELA_LIVEPATCH flag (“o” - for OS-specific).

`readelf –relocs` output for a patch module:

Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries:    Offset             Info             Type               Symbol's Value  Symbol's Name + Addend000000000000001f  0000005e00000002 R_X86_64_PC32          0000000000000000 .klp.sym.vmlinux.printk,0 - 40000000000000028  0000003d0000000b R_X86_64_32S           0000000000000000 .klp.sym.btrfs.btrfs_ktype,0 + 00000000000000036  0000003b00000002 R_X86_64_PC32          0000000000000000 .klp.sym.btrfs.can_modify_feature.isra.3,0 - 4000000000000004c  0000004900000002 R_X86_64_PC32          0000000000000000 .klp.sym.vmlinux.snprintf,0 - 4[ snip ]                                                                   ^                                                                           |                                                                          [*]
[*]
Every symbol referenced by a relocation is a livepatch symbol.

4. Livepatch symbols

Livepatch symbols are symbols referred to by livepatch relocation sections.These are symbols accessed from new versions of functions for patchedobjects, whose addresses cannot be resolved by the module loader (becausethey are local or unexported global syms). Since the module loader onlyresolves exported syms, and not every symbol referenced by the new patchedfunctions is exported, livepatch symbols were introduced. They are usedalso in cases where we cannot immediately know the address of a symbol whena patch module loads. For example, this is the case when livepatch patchesa module that is not loaded yet. In this case, the relevant livepatchsymbols are resolved simply when the target module loads. In any case, forany livepatch relocation section, all livepatch symbols referenced by thatsection must be resolved before livepatch can call apply_relocate_add() forthat reloc section.

Livepatch symbols must be marked with SHN_LIVEPATCH so that the moduleloader can identify and ignore them. Livepatch modules keep these symbolsin their symbol tables, and the symbol table is made accessible throughmodule->symtab.

4.1 A livepatch module’s symbol table

Normally, a stripped down copy of a module’s symbol table (containing only“core” symbols) is made available through module->symtab (See layout_symtab()in kernel/module.c). For livepatch modules, the symbol table copied into memoryon module load must be exactly the same as the symbol table produced when thepatch module was compiled. This is because the relocations in each livepatchrelocation section refer to their respective symbols with their symbol indices,and the original symbol indices (and thus the symtab ordering) must bepreserved in order for apply_relocate_add() to find the right symbol.

For example, take this particular rela from a livepatch module::

Relocation section '.klp.rela.btrfs.text.btrfs_feature_attr_show' at offset 0x2ba0 contains 4 entries:    Offset             Info             Type               Symbol's Value  Symbol's Name + Addend000000000000001f  0000005e00000002 R_X86_64_PC32          0000000000000000 .klp.sym.vmlinux.printk,0 - 4This rela refers to the symbol '.klp.sym.vmlinux.printk,0', and the symbol index is encodedin 'Info'. Here its symbol index is 0x5e, which is 94 in decimal, which refers to thesymbol index 94.And in this patch module's corresponding symbol table, symbol index 94 refers to that very symbol:[ snip ]94: 0000000000000000     0 NOTYPE  GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.printk,0[ snip ]

4.2 Livepatch symbol format

Livepatch symbols must have their section index marked as SHN_LIVEPATCH, sothat the module loader can identify them and not attempt to resolve them.See include/uapi/linux/elf.h for the actual definitions.

Livepatch symbol names must conform to the following format:

.klp.sym.objname.symbol_name,sympos^       ^^     ^ ^         ^ ^|_______||_____| |_________| |   [A]     [B]       [C]    [D]
[A]
The symbol name is prefixed with the string “.klp.sym.”
[B]
The name of the object (i.e. “vmlinux” or name of module) towhich the symbol belongs follows immediately after the prefix.
[C]
The actual name of the symbol.
[D]
The position of the symbol in the object (as according to kallsyms)This is used to differentiate duplicate symbols within the sameobject. The symbol position is expressed numerically (0, 1, 2…).The symbol position of a unique symbol is 0.

Examples:

Livepatch symbol names:

.klp.sym.vmlinux.snprintf,0.klp.sym.vmlinux.printk,0.klp.sym.btrfs.btrfs_ktype,0

`readelf –symbols` output for a patch module:

Symbol table '.symtab' contains 127 entries:   Num:    Value          Size Type    Bind   Vis     Ndx         Name   [ snip ]    73: 0000000000000000     0 NOTYPE  GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.snprintf,0    74: 0000000000000000     0 NOTYPE  GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.capable,0    75: 0000000000000000     0 NOTYPE  GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.find_next_bit,0    76: 0000000000000000     0 NOTYPE  GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.si_swapinfo,0  [ snip ]                                               ^                                                         |                                                        [*]
[*]
Note that the ‘Ndx’ (Section index) for these symbols is SHN_LIVEPATCH (0xff20).“OS” means OS-specific.

5. Symbol table and Elf section access

A livepatch module’s symbol table is accessible through module->symtab.

Since apply_relocate_add() requires access to a module’s section headers,symbol table, and relocation section indices, Elf information is preserved forlivepatch modules and is made accessible by the module loader throughmodule->klp_info, which is a klp_modinfo struct. When a livepatch module loads,this struct is filled in by the module loader. Its fields are documented below:

struct klp_modinfo {        Elf_Ehdr hdr; /* Elf header */        Elf_Shdr *sechdrs; /* Section header table */        char *secstrings; /* String table for the section headers */        unsigned int symndx; /* The symbol table section index */};