lkml.org 
[lkml]   [2019]   [Apr]   [26]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH v2 20/79] docs: livepatch: convert docs to ReST and rename to *.rst
Em Fri, 26 Apr 2019 10:10:56 +0200
Petr Mladek <pmladek@suse.com> escreveu:

> On Mon 2019-04-22 10:27:09, Mauro Carvalho Chehab wrote:
> > Convert livepatch documentation to ReST format. The changes
> > are mostly trivial, as the documents are already on a good
> > shape. Just a few markup changes are needed for Sphinx to
> > properly parse the docs.
> >
> > The conversion is actually:
> > - add blank lines and identation in order to identify paragraphs;
> > - fix tables markups;
> > - add some lists markups;
> > - mark literal blocks;
> > - The in-file TOC becomes a comment, in order to skip it from the
> > output, as Sphinx already generates an index there.
> > - adjust title markups.
> >
> > At its new index.rst, let's add a :orphan: while this is not linked to
> > the main index.rst file, in order to avoid build warnings.
>
> Thanks a lot for the conversion.
>
> It made me to review style of all documents. I would like add
> the following changes to make them more consistent.
>
> I can added as extra patch or merged with your one.
> Whatewer works better for you or documentation people.

If you prefer, feel free to merge it on your tree.

I don't mind if you fold your patche with my patch or apply
as a followup patch. Whatever works best for you.

>
>
> From 4cecbde44205ba4a9f777cac33ef3469cd46e7f2 Mon Sep 17 00:00:00 2001
> From: Petr Mladek <pmladek@suse.com>
> Date: Thu, 25 Apr 2019 16:58:21 +0200
> Subject: [PATCH] docs/livepatch: Unify style of livepatch documentation in the
> ReST format
>
> Make the structure of "Livepatch module Elf format" document similar
> to the main "Livepatch" document.
>
> Also make the structure of "(Un)patching Callbacks" document similar
> to the "Shadow Variables" document.
>
> It fixes the most visible inconsistencies of the documentation
> generated from the ReST format.
>
> Signed-off-by: Petr Mladek <pmladek@suse.com>

Patch looks good to me.

Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

> ---
> Documentation/livepatch/callbacks.rst | 33 ++---
> Documentation/livepatch/module-elf-format.rst | 186 ++++++++++++--------------
> 2 files changed, 104 insertions(+), 115 deletions(-)
>
> diff --git a/Documentation/livepatch/callbacks.rst b/Documentation/livepatch/callbacks.rst
> index d76d1f0d9fcf..470944aa8658 100644
> --- a/Documentation/livepatch/callbacks.rst
> +++ b/Documentation/livepatch/callbacks.rst
> @@ -4,7 +4,7 @@
>
> Livepatch (un)patch-callbacks provide a mechanism for livepatch modules
> to execute callback functions when a kernel object is (un)patched. They
> -can be considered a "power feature" that extends livepatching abilities
> +can be considered a **power feature** that **extends livepatching abilities**
> to include:
>
> - Safe updates to global data
> @@ -17,6 +17,9 @@ In most cases, (un)patch callbacks will need to be used in conjunction
> with memory barriers and kernel synchronization primitives, like
> mutexes/spinlocks, or even stop_machine(), to avoid concurrency issues.
>
> +1. Motivation
> +=============
> +
> Callbacks differ from existing kernel facilities:
>
> - Module init/exit code doesn't run when disabling and re-enabling a
> @@ -28,6 +31,9 @@ Callbacks are part of the klp_object structure and their implementation
> is specific to that klp_object. Other livepatch objects may or may not
> be patched, irrespective of the target klp_object's current state.
>
> +2. Callback types
> +=================
> +
> Callbacks can be registered for the following livepatch actions:
>
> * Pre-patch
> @@ -47,6 +53,9 @@ be patched, irrespective of the target klp_object's current state.
> been restored and no tasks are running patched code,
> used to cleanup pre-patch callback resources
>
> +3. How it works
> +===============
> +
> Each callback is optional, omitting one does not preclude specifying any
> other. However, the livepatching core executes the handlers in
> symmetry: pre-patch callbacks have a post-unpatch counterpart and
> @@ -90,11 +99,14 @@ If the object did successfully patch, but the patch transition never
> started for some reason (e.g., if another object failed to patch),
> only the post-unpatch callback will be called.
>
> +4. Use cases
> +============
>
> -Example Use-cases
> -=================
> +Sample livepatch modules demonstrating the callback API can be found in
> +samples/livepatch/ directory. These samples were modified for use in
> +kselftests and can be found in the lib/livepatch directory.
>
> -Update global data
> +Global data update
> ------------------
>
> A pre-patch callback can be useful to update a global variable. For
> @@ -107,24 +119,15 @@ patch the data *after* patching is complete with a post-patch callback,
> so that tcp_send_challenge_ack() could first be changed to read
> sysctl_tcp_challenge_ack_limit with READ_ONCE.
>
> -
> -Support __init and probe function patches
> +__init and probe function patches support
> -----------------------------------------
>
> Although __init and probe functions are not directly livepatch-able, it
> may be possible to implement similar updates via pre/post-patch
> callbacks.
>
> -48900cb6af42 ("virtio-net: drop NETIF_F_FRAGLIST") change the way that
> +The commit ``48900cb6af42 ("virtio-net: drop NETIF_F_FRAGLIST")`` change the way that
> virtnet_probe() initialized its driver's net_device features. A
> pre/post-patch callback could iterate over all such devices, making a
> similar change to their hw_features value. (Client functions of the
> value may need to be updated accordingly.)
> -
> -
> -Other Examples
> -==============
> -
> -Sample livepatch modules demonstrating the callback API can be found in
> -samples/livepatch/ directory. These samples were modified for use in
> -kselftests and can be found in the lib/livepatch directory.
> diff --git a/Documentation/livepatch/module-elf-format.rst b/Documentation/livepatch/module-elf-format.rst
> index 7f557c6f6deb..2a591e6f8e6c 100644
> --- a/Documentation/livepatch/module-elf-format.rst
> +++ b/Documentation/livepatch/module-elf-format.rst
> @@ -7,30 +7,18 @@ This document outlines the Elf format requirements that livepatch modules must f
>
> .. Table of Contents
>
> - 0. Background and motivation
> - 1. Livepatch modinfo field
> - 2. Livepatch relocation sections
> - 2.1 What are livepatch relocation sections?
> - 2.2 Livepatch relocation section format
> - 2.2.1 Required flags
> - 2.2.2 Required name format
> - 2.2.3 Example livepatch relocation section names
> - 2.2.4 Example `readelf --sections` output
> - 2.2.5 Example `readelf --relocs` output
> - 3. Livepatch symbols
> - 3.1 What are livepatch symbols?
> - 3.2 A livepatch module's symbol table
> - 3.3 Livepatch symbol format
> - 3.3.1 Required flags
> - 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
> -
> -----------------------------
> -0. Background and motivation
> -----------------------------
> + 1. Background and motivation
> + 2. Livepatch modinfo field
> + 3. Livepatch relocation sections
> + 3.1 Livepatch relocation section format
> + 4. Livepatch symbols
> + 4.1 A livepatch module's symbol table
> + 4.2 Livepatch symbol format
> + 5. Architecture-specific sections
> + 6. Symbol table and Elf section access
> +
> +1. Background and motivation
> +============================
>
> Formerly, livepatch required separate architecture-specific code to write
> relocations. However, arch-specific code to write relocations already
> @@ -52,8 +40,8 @@ relocation sections and symbols, which are described in this document. The
> Elf constants used to mark livepatch symbols and relocation sections were
> selected from OS-specific ranges according to the definitions from glibc.
>
> -0.1 Why does livepatch need to write its own relocations?
> ----------------------------------------------------------
> +Why does livepatch need to write its own relocations?
> +-----------------------------------------------------
> A typical livepatch module contains patched versions of functions that can
> reference non-exported global symbols and non-included local symbols.
> Relocations referencing these types of symbols cannot be left in as-is
> @@ -72,13 +60,8 @@ relas reference are special livepatch symbols (see section 2 and 3). The
> arch-specific livepatch relocation code is replaced by a call to
> apply_relocate_add().
>
> -================================
> -PATCH MODULE FORMAT REQUIREMENTS
> -================================
> -
> ---------------------------
> -1. Livepatch modinfo field
> ---------------------------
> +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.
> @@ -87,8 +70,10 @@ Livepatch modules can be identified by users by using the 'modinfo' command
> and looking for the presence of the "livepatch" field. This field is also
> used by the kernel module loader to identify livepatch modules.
>
> -Example modinfo output:
> ------------------------
> +Example:
> +--------
> +
> +**Modinfo output:**
>
> ::
>
> @@ -99,13 +84,9 @@ used by the kernel module loader to identify livepatch modules.
> depends:
> vermagic: 4.3.0+ SMP mod_unload
>
> ---------------------------------
> -2. Livepatch relocation sections
> ---------------------------------
> +3. Livepatch relocation sections
> +================================
>
> --------------------------------------------
> -2.1 What are livepatch relocation sections?
> --------------------------------------------
> A livepatch module manages its own Elf relocation sections to apply
> relocations to modules as well as to the kernel (vmlinux) at the
> appropriate time. For example, if a patch module patches a driver that is
> @@ -130,12 +111,9 @@ Every symbol referenced by a rela in a livepatch relocation section is a
> livepatch symbol. These must be resolved before livepatch can call
> apply_relocate_add(). See Section 3 for more information.
>
> ----------------------------------------
> -2.2 Livepatch relocation section format
> ----------------------------------------
> +3.1 Livepatch relocation section format
> +=======================================
>
> -2.2.1 Required flags
> ---------------------
> Livepatch relocation sections must be marked with the SHF_RELA_LIVEPATCH
> section flag. See include/uapi/linux/elf.h for the definition. The module
> loader recognizes this flag and will avoid applying those relocation sections
> @@ -143,8 +121,6 @@ at 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 will
> be copied into memory along with the other SHF_ALLOC sections).
>
> -2.2.2 Required name format
> ---------------------------
> The name of a livepatch relocation section must conform to the following
> format::
>
> @@ -153,19 +129,28 @@ The name of a livepatch relocation section must conform to the following
> |________||_____| |__________|
> [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) to
> - which the relocation section belongs follows immediately after the prefix.
> - [C] The actual name of the section to which this relocation section applies.
> +[A]
> + The relocation section name is prefixed with the string ".klp.rela."
>
> -2.2.3 Example livepatch relocation section names:
> --------------------------------------------------
> -.klp.rela.ext4.text.ext4_attr_store
> -.klp.rela.vmlinux.text.cmdline_proc_show
> +[B]
> + The name of the object (i.e. "vmlinux" or name of module) to
> + which the relocation section belongs follows immediately after the prefix.
>
> -2.2.4 Example `readelf --sections` output for a patch
> -module that patches vmlinux and modules 9p, btrfs, ext4:
> ---------------------------------------------------------
> +[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 patch
> +module that patches vmlinux and modules 9p, btrfs, ext4:**
>
> ::
>
> @@ -182,13 +167,14 @@ The name of a livepatch relocation section must conform to the following
> [ snip ] ^ ^
> | |
> [*] [*]
> - [*] Livepatch relocation sections are SHT_RELA sections but with a few special
> +
> +[*]
> + Livepatch relocation sections are SHT_RELA sections but with a few special
> characteristics. Notice that they are marked SHF_ALLOC ("A") so that they will
> not be discarded when the module is loaded into memory, as well as with the
> SHF_RELA_LIVEPATCH flag ("o" - for OS-specific).
>
> -2.2.5 Example `readelf --relocs` output for a patch module:
> ------------------------------------------------------------
> +**`readelf --relocs` output for a patch module:**
>
> ::
>
> @@ -200,16 +186,14 @@ The name of a livepatch relocation section must conform to the following
> 000000000000004c 0000004900000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.snprintf,0 - 4
> [ snip ] ^
> |
> - [*]
> - [*] Every symbol referenced by a relocation is a livepatch symbol.
> + [*]
> +
> +[*]
> + Every symbol referenced by a relocation is a livepatch symbol.
>
> ---------------------
> -3. Livepatch symbols
> ---------------------
> +4. Livepatch symbols
> +====================
>
> --------------------------------
> -3.1 What are livepatch symbols?
> --------------------------------
> Livepatch symbols are symbols referred to by livepatch relocation sections.
> These are symbols accessed from new versions of functions for patched
> objects, whose addresses cannot be resolved by the module loader (because
> @@ -229,9 +213,8 @@ loader can identify and ignore them. Livepatch modules keep these symbols
> in their symbol tables, and the symbol table is made accessible through
> module->symtab.
>
> --------------------------------------
> -3.2 A livepatch module's symbol table
> --------------------------------------
> +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 memory
> @@ -255,18 +238,13 @@ preserved in order for apply_relocate_add() to find the right symbol.
> 94: 0000000000000000 0 NOTYPE GLOBAL DEFAULT OS [0xff20] .klp.sym.vmlinux.printk,0
> [ snip ]
>
> ----------------------------
> -3.3 Livepatch symbol format
> ----------------------------
> +4.2 Livepatch symbol format
> +===========================
>
> -3.3.1 Required flags
> ---------------------
> Livepatch symbols must have their section index marked as SHN_LIVEPATCH, so
> that the module loader can identify them and not attempt to resolve them.
> See include/uapi/linux/elf.h for the actual definitions.
>
> -3.3.2 Required name format
> ---------------------------
> Livepatch symbol names must conform to the following format::
>
> .klp.sym.objname.symbol_name,sympos
> @@ -274,17 +252,26 @@ See include/uapi/linux/elf.h for the actual definitions.
> |_______||_____| |_________| |
> [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) to
> - which 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 same
> - object. The symbol position is expressed numerically (0, 1, 2...).
> - The symbol position of a unique symbol is 0.
> +[A]
> + The symbol name is prefixed with the string ".klp.sym."
> +
> +[B]
> + The name of the object (i.e. "vmlinux" or name of module) to
> + which the symbol belongs follows immediately after the prefix.
>
> -3.3.3 Example livepatch symbol names:
> --------------------------------------
> +[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 same
> + object. The symbol position is expressed numerically (0, 1, 2...).
> + The symbol position of a unique symbol is 0.
> +
> +Examples:
> +---------
> +
> +**Livepatch symbol names:**
>
> ::
>
> @@ -292,8 +279,7 @@ See include/uapi/linux/elf.h for the actual definitions.
> .klp.sym.vmlinux.printk,0
> .klp.sym.btrfs.btrfs_ktype,0
>
> -3.3.4 Example `readelf --symbols` output for a patch module:
> -------------------------------------------------------------
> +**`readelf --symbols` output for a patch module:**
>
> ::
>
> @@ -307,12 +293,13 @@ See include/uapi/linux/elf.h for the actual definitions.
> [ snip ] ^
> |
> [*]
> - [*] Note that the 'Ndx' (Section index) for these symbols is SHN_LIVEPATCH (0xff20).
> - "OS" means OS-specific.
>
> ----------------------------------
> -4. Architecture-specific sections
> ----------------------------------
> +[*]
> + Note that the 'Ndx' (Section index) for these symbols is SHN_LIVEPATCH (0xff20).
> + "OS" means OS-specific.
> +
> +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
> arch-specific sections. On x86 for example, we must apply per-object
> @@ -321,9 +308,8 @@ These sections must be prefixed with ".klp.arch.$objname." so that they can
> 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.
>
> Since apply_relocate_add() requires access to a module's section headers,



Thanks,
Mauro

\
 
 \ /
  Last update: 2019-04-26 11:04    [W:0.146 / U:0.440 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site