On Mon, Mar 06, 2023 at 09:08:19AM -0500, Joe Lawrence wrote:
> Add a section to Documentation/livepatch/module-elf-format.rst
> describing how klp-convert works for fixing relocations.
>
> Signed-off-by: Joao Moreira <jmoreira@xxxxxxx>
> Signed-off-by: Joe Lawrence <joe.lawrence@xxxxxxxxxx>
LGTM:
Reviewed-by: Marcos Paulo de Souza <mpdesouza@xxxxxxxx>
> ---
> Documentation/livepatch/livepatch.rst | 3 ++
> Documentation/livepatch/module-elf-format.rst | 42 +++++++++++++++++--
> 2 files changed, 42 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/livepatch/livepatch.rst b/Documentation/livepatch/livepatch.rst
> index 68e3651e8af9..6b317a57c276 100644
> --- a/Documentation/livepatch/livepatch.rst
> +++ b/Documentation/livepatch/livepatch.rst
> @@ -261,6 +261,9 @@ into three levels:
> absolute position in the database, but rather the order it has been found
> only for a particular object ( vmlinux or a kernel module ). Note that
> kallsyms allows for searching symbols according to the object name.
> + Uniquely named symbols may use a symbol position of 0. Non-unique
> + symbols need to specify their object / kallsyms position, starting
> + at position 1.
>
> - struct klp_object defines an array of patched functions (struct
> klp_func) in the same object. Where the object is either vmlinux
> diff --git a/Documentation/livepatch/module-elf-format.rst b/Documentation/livepatch/module-elf-format.rst
> index 7347638895a0..72a072514581 100644
> --- a/Documentation/livepatch/module-elf-format.rst
> +++ b/Documentation/livepatch/module-elf-format.rst
> @@ -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
> @@ -259,7 +260,8 @@ Livepatch symbol names must conform to the following format::
> The position of the symbol in the object (as according to kallsyms)
> This is used to differentiate duplicate symbols within the same
> object. The symbol position is expressed numerically (0, 1, 2...).
> - The symbol position of a unique symbol is 0.
> + The symbol position of a unique symbol is 0. The symbol position of
> + the first non-unique symbol is 1, the second is 2, etc.
>
> Examples:
> ---------
> @@ -291,7 +293,41 @@ Examples:
> Note that the 'Ndx' (Section index) for these symbols is SHN_LIVEPATCH (0xff20).
> "OS" means OS-specific.
>
> -5. Symbol table and Elf section access
> +5. 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.klp, 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.
> +
> +6. Symbol table and Elf section access
> ======================================
> A livepatch module's symbol table is accessible through module->symtab.
>
> --
> 2.39.2
>
