Add a section to Documentation/livepatch/module-elf-format.txt
describing how klp-convert works for fixing relocations.
Signed-off-by: Joao Moreira <jmore...@suse.de>
---
Documentation/livepatch/module-elf-format.txt | 47 ++++++++++++++++++++++++---
1 file changed, 42 insertions(+), 5 deletions(-)
diff --git a/Documentation/livepatch/module-elf-format.txt
b/Documentation/livepatch/module-elf-format.txt
index f21a5289a09c..6b0259dfab49 100644
--- a/Documentation/livepatch/module-elf-format.txt
+++ b/Documentation/livepatch/module-elf-format.txt
@@ -2,7 +2,8 @@
Livepatch module Elf format
===========================
-This document outlines the Elf format requirements that livepatch modules must
follow.
+This document outlines the Elf format requirements that livepatch modules must
+follow.
-----------------
Table of Contents
@@ -25,8 +26,9 @@ Table of Contents
3.3.2 Required name format
3.3.3 Example livepatch symbol names
3.3.4 Example `readelf --symbols` output
-4. Architecture-specific sections
-5. Symbol table and Elf section access
+4. Automatic conversion of unresolved relocations
+5. Architecture-specific sections
+6. Symbol table and Elf section access
----------------------------
0. Background and motivation
@@ -293,8 +295,43 @@ Symbol table '.symtab' contains 127 entries:
[*] Note that the 'Ndx' (Section index) for these symbols is SHN_LIVEPATCH
(0xff20).
"OS" means OS-specific.
+--------------------------------------------------
+4. Automatic conversion of unresolved relocations
+--------------------------------------------------
+Sometimes livepatches may operate on symbols which are not self-contained nor
+exported. When this happens, these symbols remain unresolved in the elf object
+and will trigger an error during the livepatch instantiation.
+
+Whenever possible, the kernel building infrastructure solves this problem
+automatically. First, a symbol database containing information on all compiled
+objects is built. Second, this database - a file named Symbols.list, placed in
+the kernel source root directory - is used to identify targets for unresolved
+relocations, converting them in the livepatch elf accordingly to the
+specifications above-described. While the first stage is fully handled by the
+building system, the second is done by a tool called klp-convert, which can be
+found in "scripts/livepatch".
+
+When an unresolved relocation has as target a symbol whose name is also used by
+different symbols throughout the kernel, the relocation cannot be resolved
+automatically. In these cases, the livepatch developer must add annotations to
+the livepatch, making it possible for the system to identify which is the
+correct target amongst multiple homonymous symbols. Such annotations must be
+done through a data structure as follows:
+
+struct KLP_MODULE_RELOC(object) data_structure_name[] = {
+ KLP_SYMPOS(symbol, pos)
+};
+
+In the above example, object refers to the object file which contains the
+symbol, being vmlinux or a module; symbol refers to the symbol name that will
+be relocated and pos is its position in the object.
+
+When a data structure like this is added to the livepatch, the resulting elf
+will hold symbols that will be identified by klp-convert and used to solve name
+ambiguities.
+
---------------------------------
-4. Architecture-specific sections
+5. Architecture-specific sections
---------------------------------
Architectures may override arch_klp_init_object_loaded() to perform
additional arch-specific tasks when a target module loads, such as applying
@@ -305,7 +342,7 @@ be easily identified when iterating through a patch
module's Elf sections
(See arch/x86/kernel/livepatch.c for a complete example).
--------------------------------------
-5. Symbol table and Elf section access
+6. Symbol table and Elf section access
--------------------------------------
A livepatch module's symbol table is accessible through module->symtab.
--
2.12.0
