mirror of
https://github.com/torvalds/linux.git
synced 2024-11-21 19:41:42 +00:00
docs: livepatch: convert docs to ReST and rename to *.rst
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Petr Mladek <pmladek@suse.com>
Acked-by: Miroslav Benes <mbenes@suse.cz>
Acked-by: Josh Poimboeuf <jpoimboe@redhat.com>
Acked-by: Joe Lawrence <joe.lawrence@redhat.com>
Reviewed-by: Kamalesh Babulal <kamalesh@linux.vnet.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Mauro Carvalho Chehab
Jonathan Corbet
parent
894ee5ff83
commit
89e33ea732
@ -45,7 +45,7 @@ Description:
|
||||
use this feature without a clearance from a patch
|
||||
distributor. Removal (rmmod) of patch modules is permanently
|
||||
disabled when the feature is used. See
|
||||
Documentation/livepatch/livepatch.txt for more information.
|
||||
Documentation/livepatch/livepatch.rst for more information.
|
||||
|
||||
What: /sys/kernel/livepatch/<patch>/<object>
|
||||
Date: Nov 2014
|
||||
|
||||
@ -30,16 +30,20 @@ be patched, irrespective of the target klp_object's current state.
|
||||
|
||||
Callbacks can be registered for the following livepatch actions:
|
||||
|
||||
* Pre-patch - before a klp_object is patched
|
||||
* Pre-patch
|
||||
- before a klp_object is patched
|
||||
|
||||
* Post-patch - after a klp_object has been patched and is active
|
||||
* Post-patch
|
||||
- after a klp_object has been patched and is active
|
||||
across all tasks
|
||||
|
||||
* Pre-unpatch - before a klp_object is unpatched (ie, patched code is
|
||||
* Pre-unpatch
|
||||
- before a klp_object is unpatched (ie, patched code is
|
||||
active), used to clean up post-patch callback
|
||||
resources
|
||||
|
||||
* Post-unpatch - after a klp_object has been patched, all code has
|
||||
* Post-unpatch
|
||||
- after a klp_object has been patched, all code has
|
||||
been restored and no tasks are running patched code,
|
||||
used to cleanup pre-patch callback resources
|
||||
|
||||
@ -18,7 +18,7 @@ Usage
|
||||
-----
|
||||
|
||||
The atomic replace can be enabled by setting "replace" flag in struct klp_patch,
|
||||
for example:
|
||||
for example::
|
||||
|
||||
static struct klp_patch patch = {
|
||||
.mod = THIS_MODULE,
|
||||
@ -49,19 +49,19 @@ Features
|
||||
|
||||
The atomic replace allows:
|
||||
|
||||
+ Atomically revert some functions in a previous patch while
|
||||
- Atomically revert some functions in a previous patch while
|
||||
upgrading other functions.
|
||||
|
||||
+ Remove eventual performance impact caused by core redirection
|
||||
- Remove eventual performance impact caused by core redirection
|
||||
for functions that are no longer patched.
|
||||
|
||||
+ Decrease user confusion about dependencies between livepatches.
|
||||
- Decrease user confusion about dependencies between livepatches.
|
||||
|
||||
|
||||
Limitations:
|
||||
------------
|
||||
|
||||
+ Once the operation finishes, there is no straightforward way
|
||||
- Once the operation finishes, there is no straightforward way
|
||||
to reverse it and restore the replaced patches atomically.
|
||||
|
||||
A good practice is to set .replace flag in any released livepatch.
|
||||
@ -74,7 +74,7 @@ Limitations:
|
||||
only when the transition was not forced.
|
||||
|
||||
|
||||
+ Only the (un)patching callbacks from the _new_ cumulative livepatch are
|
||||
- Only the (un)patching callbacks from the _new_ cumulative livepatch are
|
||||
executed. Any callbacks from the replaced patches are ignored.
|
||||
|
||||
In other words, the cumulative patch is responsible for doing any actions
|
||||
@ -93,7 +93,7 @@ Limitations:
|
||||
enabled patches were called.
|
||||
|
||||
|
||||
+ There is no special handling of shadow variables. Livepatch authors
|
||||
- There is no special handling of shadow variables. Livepatch authors
|
||||
must create their own rules how to pass them from one cumulative
|
||||
patch to the other. Especially that they should not blindly remove
|
||||
them in module_exit() functions.
|
||||
21
Documentation/livepatch/index.rst
Normal file
21
Documentation/livepatch/index.rst
Normal file
@ -0,0 +1,21 @@
|
||||
:orphan:
|
||||
|
||||
===================
|
||||
Kernel Livepatching
|
||||
===================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
livepatch
|
||||
callbacks
|
||||
cumulative-patches
|
||||
module-elf-format
|
||||
shadow-vars
|
||||
|
||||
.. only:: subproject and html
|
||||
|
||||
Indices
|
||||
=======
|
||||
|
||||
* :ref:`genindex`
|
||||
@ -4,7 +4,7 @@ Livepatch
|
||||
|
||||
This document outlines basic information about kernel livepatching.
|
||||
|
||||
Table of Contents:
|
||||
.. Table of Contents:
|
||||
|
||||
1. Motivation
|
||||
2. Kprobes, Ftrace, Livepatching
|
||||
@ -40,14 +40,14 @@ There are multiple mechanisms in the Linux kernel that are directly related
|
||||
to redirection of code execution; namely: kernel probes, function tracing,
|
||||
and livepatching:
|
||||
|
||||
+ The kernel probes are the most generic. The code can be redirected by
|
||||
- The kernel probes are the most generic. The code can be redirected by
|
||||
putting a breakpoint instruction instead of any instruction.
|
||||
|
||||
+ The function tracer calls the code from a predefined location that is
|
||||
- The function tracer calls the code from a predefined location that is
|
||||
close to the function entry point. This location is generated by the
|
||||
compiler using the '-pg' gcc option.
|
||||
|
||||
+ Livepatching typically needs to redirect the code at the very beginning
|
||||
- Livepatching typically needs to redirect the code at the very beginning
|
||||
of the function entry before the function parameters or the stack
|
||||
are in any way modified.
|
||||
|
||||
@ -249,7 +249,7 @@ The patch contains only functions that are really modified. But they
|
||||
might want to access functions or data from the original source file
|
||||
that may only be locally accessible. This can be solved by a special
|
||||
relocation section in the generated livepatch module, see
|
||||
Documentation/livepatch/module-elf-format.txt for more details.
|
||||
Documentation/livepatch/module-elf-format.rst for more details.
|
||||
|
||||
|
||||
4.2. Metadata
|
||||
@ -258,7 +258,7 @@ Documentation/livepatch/module-elf-format.txt for more details.
|
||||
The patch is described by several structures that split the information
|
||||
into three levels:
|
||||
|
||||
+ struct klp_func is defined for each patched function. It describes
|
||||
- struct klp_func is defined for each patched function. It describes
|
||||
the relation between the original and the new implementation of a
|
||||
particular function.
|
||||
|
||||
@ -275,7 +275,7 @@ into three levels:
|
||||
only for a particular object ( vmlinux or a kernel module ). Note that
|
||||
kallsyms allows for searching symbols according to the object name.
|
||||
|
||||
+ struct klp_object defines an array of patched functions (struct
|
||||
- struct klp_object defines an array of patched functions (struct
|
||||
klp_func) in the same object. Where the object is either vmlinux
|
||||
(NULL) or a module name.
|
||||
|
||||
@ -285,7 +285,7 @@ into three levels:
|
||||
only when they are available.
|
||||
|
||||
|
||||
+ struct klp_patch defines an array of patched objects (struct
|
||||
- struct klp_patch defines an array of patched objects (struct
|
||||
klp_object).
|
||||
|
||||
This structure handles all patched functions consistently and eventually,
|
||||
@ -337,14 +337,16 @@ operation fails.
|
||||
Second, livepatch enters into a transition state where tasks are converging
|
||||
to the patched state. If an original function is patched for the first
|
||||
time, a function specific struct klp_ops is created and an universal
|
||||
ftrace handler is registered[*]. This stage is indicated by a value of '1'
|
||||
ftrace handler is registered\ [#]_. This stage is indicated by a value of '1'
|
||||
in /sys/kernel/livepatch/<name>/transition. For more information about
|
||||
this process, see the "Consistency model" section.
|
||||
|
||||
Finally, once all tasks have been patched, the 'transition' value changes
|
||||
to '0'.
|
||||
|
||||
[*] Note that functions might be patched multiple times. The ftrace handler
|
||||
.. [#]
|
||||
|
||||
Note that functions might be patched multiple times. The ftrace handler
|
||||
is registered only once for a given function. Further patches just add
|
||||
an entry to the list (see field `func_stack`) of the struct klp_ops.
|
||||
The right implementation is selected by the ftrace handler, see
|
||||
@ -368,7 +370,7 @@ the ftrace handler is unregistered and the struct klp_ops is
|
||||
freed when the related function is not modified by the new patch
|
||||
and func_stack list becomes empty.
|
||||
|
||||
See Documentation/livepatch/cumulative-patches.txt for more details.
|
||||
See Documentation/livepatch/cumulative-patches.rst for more details.
|
||||
|
||||
|
||||
5.4. Disabling
|
||||
@ -421,7 +423,7 @@ See Documentation/ABI/testing/sysfs-kernel-livepatch for more details.
|
||||
|
||||
The current Livepatch implementation has several limitations:
|
||||
|
||||
+ Only functions that can be traced could be patched.
|
||||
- Only functions that can be traced could be patched.
|
||||
|
||||
Livepatch is based on the dynamic ftrace. In particular, functions
|
||||
implementing ftrace or the livepatch ftrace handler could not be
|
||||
@ -431,7 +433,7 @@ The current Livepatch implementation has several limitations:
|
||||
|
||||
|
||||
|
||||
+ Livepatch works reliably only when the dynamic ftrace is located at
|
||||
- Livepatch works reliably only when the dynamic ftrace is located at
|
||||
the very beginning of the function.
|
||||
|
||||
The function need to be redirected before the stack or the function
|
||||
@ -445,7 +447,7 @@ The current Livepatch implementation has several limitations:
|
||||
this is handled on the ftrace level.
|
||||
|
||||
|
||||
+ Kretprobes using the ftrace framework conflict with the patched
|
||||
- Kretprobes using the ftrace framework conflict with the patched
|
||||
functions.
|
||||
|
||||
Both kretprobes and livepatches use a ftrace handler that modifies
|
||||
@ -453,7 +455,7 @@ The current Livepatch implementation has several limitations:
|
||||
is rejected when the handler is already in use by the other.
|
||||
|
||||
|
||||
+ Kprobes in the original function are ignored when the code is
|
||||
- Kprobes in the original function are ignored when the code is
|
||||
redirected to the new implementation.
|
||||
|
||||
There is a work in progress to add warnings about this situation.
|
||||
@ -4,9 +4,9 @@ Livepatch module Elf format
|
||||
|
||||
This document outlines the Elf format requirements that livepatch modules must follow.
|
||||
|
||||
-----------------
|
||||
Table of Contents
|
||||
-----------------
|
||||
|
||||
.. Table of Contents
|
||||
|
||||
0. Background and motivation
|
||||
1. Livepatch modinfo field
|
||||
2. Livepatch relocation sections
|
||||
@ -89,6 +89,9 @@ used by the kernel module loader to identify livepatch modules.
|
||||
|
||||
Example modinfo output:
|
||||
-----------------------
|
||||
|
||||
::
|
||||
|
||||
% modinfo livepatch-meminfo.ko
|
||||
filename: livepatch-meminfo.ko
|
||||
livepatch: Y
|
||||
@ -142,7 +145,8 @@ 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:
|
||||
The name of a livepatch relocation section must conform to the following
|
||||
format::
|
||||
|
||||
.klp.rela.objname.section_name
|
||||
^ ^^ ^ ^ ^
|
||||
@ -162,6 +166,9 @@ The name of a livepatch relocation section must conform to the following format:
|
||||
2.2.4 Example `readelf --sections` output for a patch
|
||||
module that patches vmlinux and modules 9p, btrfs, ext4:
|
||||
--------------------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
Section Headers:
|
||||
[Nr] Name Type Address Off Size ES Flg Lk Inf Al
|
||||
[ snip ]
|
||||
@ -182,6 +189,9 @@ SHF_RELA_LIVEPATCH flag ("o" - for OS-specific).
|
||||
|
||||
2.2.5 Example `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 + Addend
|
||||
000000000000001f 0000005e00000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.printk,0 - 4
|
||||
@ -231,7 +241,8 @@ relocation section refer to their respective symbols with their symbol indices,
|
||||
and the original symbol indices (and thus the symtab ordering) must be
|
||||
preserved in order for apply_relocate_add() to find the right symbol.
|
||||
|
||||
For example, take this particular rela from a livepatch module:
|
||||
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 + Addend
|
||||
000000000000001f 0000005e00000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.printk,0 - 4
|
||||
@ -256,7 +267,7 @@ 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:
|
||||
Livepatch symbol names must conform to the following format::
|
||||
|
||||
.klp.sym.objname.symbol_name,sympos
|
||||
^ ^^ ^ ^ ^ ^
|
||||
@ -274,12 +285,18 @@ Livepatch symbol names must conform to the following format:
|
||||
|
||||
3.3.3 Example livepatch symbol names:
|
||||
-------------------------------------
|
||||
|
||||
::
|
||||
|
||||
.klp.sym.vmlinux.snprintf,0
|
||||
.klp.sym.vmlinux.printk,0
|
||||
.klp.sym.btrfs.btrfs_ktype,0
|
||||
|
||||
3.3.4 Example `readelf --symbols` output for a patch module:
|
||||
------------------------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
Symbol table '.symtab' contains 127 entries:
|
||||
Num: Value Size Type Bind Vis Ndx Name
|
||||
[ snip ]
|
||||
@ -313,7 +330,7 @@ Since apply_relocate_add() requires access to a module's section headers,
|
||||
symbol table, and relocation section indices, Elf information is preserved for
|
||||
livepatch modules and is made accessible by the module loader through
|
||||
module->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:
|
||||
this struct is filled in by the module loader. Its fields are documented below::
|
||||
|
||||
struct klp_modinfo {
|
||||
Elf_Ehdr hdr; /* Elf header */
|
||||
@ -28,9 +28,12 @@ stored and retrieved through a <obj, id> pair.
|
||||
|
||||
* The klp_shadow variable data structure encapsulates both tracking
|
||||
meta-data and shadow-data:
|
||||
|
||||
- meta-data
|
||||
|
||||
- obj - pointer to parent object
|
||||
- id - data identifier
|
||||
|
||||
- data[] - storage for shadow data
|
||||
|
||||
It is important to note that the klp_shadow_alloc() and
|
||||
@ -47,31 +50,43 @@ to do actions that can be done only once when a new variable is allocated.
|
||||
|
||||
* klp_shadow_alloc() - allocate and add a new shadow variable
|
||||
- search hashtable for <obj, id> pair
|
||||
|
||||
- if exists
|
||||
|
||||
- WARN and return NULL
|
||||
|
||||
- if <obj, id> doesn't already exist
|
||||
|
||||
- allocate a new shadow variable
|
||||
- initialize the variable using a custom constructor and data when provided
|
||||
- add <obj, id> to the global hashtable
|
||||
|
||||
* klp_shadow_get_or_alloc() - get existing or alloc a new shadow variable
|
||||
- search hashtable for <obj, id> pair
|
||||
|
||||
- if exists
|
||||
|
||||
- return existing shadow variable
|
||||
|
||||
- if <obj, id> doesn't already exist
|
||||
|
||||
- allocate a new shadow variable
|
||||
- initialize the variable using a custom constructor and data when provided
|
||||
- add <obj, id> pair to the global hashtable
|
||||
|
||||
* klp_shadow_free() - detach and free a <obj, id> shadow variable
|
||||
- find and remove a <obj, id> reference from global hashtable
|
||||
|
||||
- if found
|
||||
|
||||
- call destructor function if defined
|
||||
- free shadow variable
|
||||
|
||||
* klp_shadow_free_all() - detach and free all <*, id> shadow variables
|
||||
- find and remove any <*, id> references from global hashtable
|
||||
|
||||
- if found
|
||||
|
||||
- call destructor function if defined
|
||||
- free shadow variable
|
||||
|
||||
@ -102,7 +117,7 @@ parent "goes live" (ie, any shadow variable get-API requests are made
|
||||
for this <obj, id> pair.)
|
||||
|
||||
For commit 1d147bfa6429, when a parent sta_info structure is allocated,
|
||||
allocate a shadow copy of the ps_lock pointer, then initialize it:
|
||||
allocate a shadow copy of the ps_lock pointer, then initialize it::
|
||||
|
||||
#define PS_LOCK 1
|
||||
struct sta_info *sta_info_alloc(struct ieee80211_sub_if_data *sdata,
|
||||
@ -123,7 +138,7 @@ struct sta_info *sta_info_alloc(struct ieee80211_sub_if_data *sdata,
|
||||
...
|
||||
|
||||
When requiring a ps_lock, query the shadow variable API to retrieve one
|
||||
for a specific struct sta_info:
|
||||
for a specific struct sta_info:::
|
||||
|
||||
void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta)
|
||||
{
|
||||
@ -136,7 +151,7 @@ void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta)
|
||||
...
|
||||
|
||||
When the parent sta_info structure is freed, first free the shadow
|
||||
variable:
|
||||
variable::
|
||||
|
||||
void sta_info_free(struct ieee80211_local *local, struct sta_info *sta)
|
||||
{
|
||||
@ -155,7 +170,7 @@ these cases, the klp_shadow_get_or_alloc() call can be used to attach
|
||||
shadow variables to parents already in-flight.
|
||||
|
||||
For commit 1d147bfa6429, a good spot to allocate a shadow spinlock is
|
||||
inside ieee80211_sta_ps_deliver_wakeup():
|
||||
inside ieee80211_sta_ps_deliver_wakeup()::
|
||||
|
||||
int ps_lock_shadow_ctor(void *obj, void *shadow_data, void *ctor_data)
|
||||
{
|
||||
@ -200,10 +215,12 @@ suggests how to handle the parent object.
|
||||
=============
|
||||
|
||||
* https://github.com/dynup/kpatch
|
||||
|
||||
The livepatch implementation is based on the kpatch version of shadow
|
||||
variables.
|
||||
|
||||
* http://files.mkgnu.net/files/dynamos/doc/papers/dynamos_eurosys_07.pdf
|
||||
|
||||
Dynamic and Adaptive Updates of Non-Quiescent Subsystems in Commodity
|
||||
Operating System Kernels (Kritis Makris, Kyung Dong Ryu 2007) presented
|
||||
a datatype update technique called "shadow data structures".
|
||||
@ -111,7 +111,7 @@ c) Higher live patching compatibility rate
|
||||
be detectable). Objtool makes that possible.
|
||||
|
||||
For more details, see the livepatch documentation in the Linux kernel
|
||||
source tree at Documentation/livepatch/livepatch.txt.
|
||||
source tree at Documentation/livepatch/livepatch.rst.
|
||||
|
||||
Rules
|
||||
-----
|
||||
|
||||
Loading…
Reference in New Issue
Block a user