You've already forked linux-rockchip
mirror of
https://github.com/armbian/linux-rockchip.git
synced 2026-01-06 11:08:10 -08:00
Merge tag 'docs-5.2' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet: "A reasonably busy cycle for docs, including: - Lots of work on the Chinese and Italian translations - Some license-rules clarifications from Christoph - Various build-script fixes - A new document on memory models - RST conversion of the live-patching docs - The usual collection of typo fixes and corrections" * tag 'docs-5.2' of git://git.lwn.net/linux: (140 commits) docs/livepatch: Unify style of livepatch documentation in the ReST format docs: livepatch: convert docs to ReST and rename to *.rst scripts/documentation-file-ref-check: detect broken :doc:`foo` scripts/documentation-file-ref-check: don't parse Next/ dir LICENSES: Rename other to deprecated LICENSES: Clearly mark dual license only licenses docs: Don't reference the ZLib license in license-rules.rst docs/vm: Minor editorial changes in the THP and hugetlbfs docs/vm: add documentation of memory models doc:it_IT: translation alignment doc: fix typo in PGP guide dontdiff: update with Kconfig build artifacts docs/zh_CN: fix typos in 1.Intro.rst file docs/zh_CN: redirect CoC docs to Chinese version doc: mm: migration doesn't use FOLL_SPLIT anymore docs: doc-guide: remove the extension from .rst files doc: kselftest: Fix KBUILD_OUTPUT usage instructions docs: trace: fix some Sphinx warnings docs: speculation.txt: mark example blocks as such docs: ntb.txt: add blank lines to clean up some Sphinx warnings ...
This commit is contained in:
Linus Torvalds
6
.mailmap
6
.mailmap
@@ -16,6 +16,8 @@ Alan Cox <alan@lxorguk.ukuu.org.uk>
|
||||
Alan Cox <root@hraefn.swansea.linux.org.uk>
|
||||
Aleksey Gorelov <aleksey_gorelov@phoenix.com>
|
||||
Aleksandar Markovic <aleksandar.markovic@mips.com> <aleksandar.markovic@imgtec.com>
|
||||
Alex Shi <alex.shi@linux.alibaba.com> <alex.shi@intel.com>
|
||||
Alex Shi <alex.shi@linux.alibaba.com> <alex.shi@linaro.org>
|
||||
Alexei Starovoitov <ast@kernel.org> <ast@plumgrid.com>
|
||||
Alexei Starovoitov <ast@kernel.org> <alexei.starovoitov@gmail.com>
|
||||
Alexei Starovoitov <ast@kernel.org> <ast@fb.com>
|
||||
@@ -126,6 +128,8 @@ Leonid I Ananiev <leonid.i.ananiev@intel.com>
|
||||
Linas Vepstas <linas@austin.ibm.com>
|
||||
Linus Lüssing <linus.luessing@c0d3.blue> <linus.luessing@web.de>
|
||||
Linus Lüssing <linus.luessing@c0d3.blue> <linus.luessing@ascom.ch>
|
||||
Li Yang <leoyang.li@nxp.com> <leo@zh-kernel.org>
|
||||
Li Yang <leoyang.li@nxp.com> <leoli@freescale.com>
|
||||
Maciej W. Rozycki <macro@mips.com> <macro@imgtec.com>
|
||||
Marcin Nowakowski <marcin.nowakowski@mips.com> <marcin.nowakowski@imgtec.com>
|
||||
Mark Brown <broonie@sirena.org.uk>
|
||||
@@ -217,6 +221,8 @@ Tejun Heo <htejun@gmail.com>
|
||||
Thomas Graf <tgraf@suug.ch>
|
||||
Thomas Pedersen <twp@codeaurora.org>
|
||||
Tony Luck <tony.luck@intel.com>
|
||||
TripleX Chung <xxx.phy@gmail.com> <zhongyu@18mail.cn>
|
||||
TripleX Chung <xxx.phy@gmail.com> <triplex@zh-kernel.org>
|
||||
Tsuneo Yoshioka <Tsuneo.Yoshioka@f-secure.com>
|
||||
Uwe Kleine-König <ukleinek@informatik.uni-freiburg.de>
|
||||
Uwe Kleine-König <ukl@pengutronix.de>
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -147,7 +147,7 @@ networking subsystems make sure that the buffers they use are valid
|
||||
for you to DMA from/to.
|
||||
|
||||
DMA addressing capabilities
|
||||
==========================
|
||||
===========================
|
||||
|
||||
By default, the kernel assumes that your device can address 32-bits of DMA
|
||||
addressing. For a 64-bit capable device, this needs to be increased, and for
|
||||
|
||||
@@ -28,8 +28,13 @@ ifeq ($(HAVE_SPHINX),0)
|
||||
|
||||
else # HAVE_SPHINX
|
||||
|
||||
# User-friendly check for pdflatex
|
||||
# User-friendly check for pdflatex and latexmk
|
||||
HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi)
|
||||
HAVE_LATEXMK := $(shell if which latexmk >/dev/null 2>&1; then echo 1; else echo 0; fi)
|
||||
|
||||
ifeq ($(HAVE_LATEXMK),1)
|
||||
PDFLATEX := latexmk -$(PDFLATEX)
|
||||
endif #HAVE_LATEXMK
|
||||
|
||||
# Internal variables.
|
||||
PAPEROPT_a4 = -D latex_paper_size=a4
|
||||
@@ -82,7 +87,7 @@ pdfdocs:
|
||||
else # HAVE_PDFLATEX
|
||||
|
||||
pdfdocs: latexdocs
|
||||
$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
|
||||
$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
|
||||
|
||||
endif # HAVE_PDFLATEX
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
|
||||
On atomic bitops.
|
||||
|
||||
=============
|
||||
Atomic bitops
|
||||
=============
|
||||
|
||||
While our bitmap_{}() functions are non-atomic, we have a number of operations
|
||||
operating on single bits in a bitmap that are atomic.
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
Clearing WARN_ONCE
|
||||
------------------
|
||||
|
||||
WARN_ONCE / WARN_ON_ONCE / printk_once only emit a message once.
|
||||
|
||||
|
||||
@@ -22,7 +22,6 @@ Core utilities
|
||||
workqueue
|
||||
genericirq
|
||||
xarray
|
||||
flexible-arrays
|
||||
librs
|
||||
genalloc
|
||||
errseq
|
||||
|
||||
@@ -7,6 +7,11 @@ directory. These are intended to be small tests to exercise individual code
|
||||
paths in the kernel. Tests are intended to be run after building, installing
|
||||
and booting a kernel.
|
||||
|
||||
You can find additional information on Kselftest framework, how to
|
||||
write new tests using the framework on Kselftest wiki:
|
||||
|
||||
https://kselftest.wiki.kernel.org/
|
||||
|
||||
On some systems, hot-plug tests could hang forever waiting for cpu and
|
||||
memory to be ready to be offlined. A special hot-plug target is created
|
||||
to run the full range of hot-plug tests. In default mode, hot-plug tests run
|
||||
@@ -35,17 +40,32 @@ To build and run the tests with a single command, use::
|
||||
|
||||
Note that some tests will require root privileges.
|
||||
|
||||
Build and run from user specific object directory (make O=dir)::
|
||||
Kselftest supports saving output files in a separate directory and then
|
||||
running tests. To locate output files in a separate directory two syntaxes
|
||||
are supported. In both cases the working directory must be the root of the
|
||||
kernel src. This is applicable to "Running a subset of selftests" section
|
||||
below.
|
||||
|
||||
To build, save output files in a separate directory with O= ::
|
||||
|
||||
$ make O=/tmp/kselftest kselftest
|
||||
|
||||
Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
|
||||
To build, save output files in a separate directory with KBUILD_OUTPUT ::
|
||||
|
||||
$ make KBUILD_OUTPUT=/tmp/kselftest kselftest
|
||||
$ export KBUILD_OUTPUT=/tmp/kselftest; make kselftest
|
||||
|
||||
The above commands run the tests and print pass/fail summary to make it
|
||||
easier to understand the test results. Please find the detailed individual
|
||||
test results for each test in /tmp/testname file(s).
|
||||
The O= assignment takes precedence over the KBUILD_OUTPUT environment
|
||||
variable.
|
||||
|
||||
The above commands by default run the tests and print full pass/fail report.
|
||||
Kselftest supports "summary" option to make it easier to understand the test
|
||||
results. Please find the detailed individual test results for each test in
|
||||
/tmp/testname file(s) when summary option is specified. This is applicable
|
||||
to "Running a subset of selftests" section below.
|
||||
|
||||
To run kselftest with summary option enabled ::
|
||||
|
||||
$ make summary=1 kselftest
|
||||
|
||||
Running a subset of selftests
|
||||
=============================
|
||||
@@ -61,17 +81,13 @@ You can specify multiple tests to build and run::
|
||||
|
||||
$ make TARGETS="size timers" kselftest
|
||||
|
||||
Build and run from user specific object directory (make O=dir)::
|
||||
To build, save output files in a separate directory with O= ::
|
||||
|
||||
$ make O=/tmp/kselftest TARGETS="size timers" kselftest
|
||||
|
||||
Build and run KBUILD_OUTPUT directory (make KBUILD_OUTPUT=)::
|
||||
To build, save output files in a separate directory with KBUILD_OUTPUT ::
|
||||
|
||||
$ make KBUILD_OUTPUT=/tmp/kselftest TARGETS="size timers" kselftest
|
||||
|
||||
The above commands run the tests and print pass/fail summary to make it
|
||||
easier to understand the test results. Please find the detailed individual
|
||||
test results for each test in /tmp/testname file(s).
|
||||
$ export KBUILD_OUTPUT=/tmp/kselftest; make TARGETS="size timers" kselftest
|
||||
|
||||
See the top-level tools/testing/selftests/Makefile for the list of all
|
||||
possible targets.
|
||||
|
||||
@@ -7,9 +7,9 @@ How to write kernel documentation
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
sphinx.rst
|
||||
kernel-doc.rst
|
||||
parse-headers.rst
|
||||
sphinx
|
||||
kernel-doc
|
||||
parse-headers
|
||||
|
||||
.. only:: subproject and html
|
||||
|
||||
|
||||
@@ -127,7 +127,7 @@ flask.h
|
||||
fore200e_mkfirm
|
||||
fore200e_pca_fw.c*
|
||||
gconf
|
||||
gconf.glade.h
|
||||
gconf-cfg
|
||||
gen-devlist
|
||||
gen_crc32table
|
||||
gen_init_cpio
|
||||
@@ -148,24 +148,22 @@ int32.c
|
||||
int4.c
|
||||
int8.c
|
||||
kallsyms
|
||||
kconfig
|
||||
keywords.c
|
||||
ksym.c*
|
||||
ksym.h*
|
||||
kxgettext
|
||||
*lex.c
|
||||
*lex.*.c
|
||||
linux
|
||||
logo_*.c
|
||||
logo_*_clut224.c
|
||||
logo_*_mono.c
|
||||
lxdialog
|
||||
mach-types
|
||||
mach-types.h
|
||||
machtypes.h
|
||||
map
|
||||
map_hugetlb
|
||||
mconf
|
||||
mconf-cfg
|
||||
miboot*
|
||||
mk_elfconfig
|
||||
mkboot
|
||||
@@ -183,6 +181,7 @@ modules.builtin.modinfo
|
||||
modules.order
|
||||
modversions.h*
|
||||
nconf
|
||||
nconf-cfg
|
||||
ncscope.*
|
||||
offset.h
|
||||
oui.c*
|
||||
@@ -202,6 +201,7 @@ pnmtologo
|
||||
ppc_defs.h*
|
||||
pss_boot.h
|
||||
qconf
|
||||
qconf-cfg
|
||||
r100_reg_safe.h
|
||||
r200_reg_safe.h
|
||||
r300_reg_safe.h
|
||||
|
||||
@@ -201,7 +201,7 @@ Bus implements below API for allocate a stream which needs to be called once
|
||||
per stream. From ASoC DPCM framework, this stream state maybe linked to
|
||||
.startup() operation.
|
||||
|
||||
.. code-block:: c
|
||||
.. code-block:: c
|
||||
|
||||
int sdw_alloc_stream(char * stream_name);
|
||||
|
||||
@@ -228,7 +228,7 @@ the respective Master(s) and Slave(s) associated with stream. These APIs can
|
||||
only be invoked once by respective Master(s) and Slave(s). From ASoC DPCM
|
||||
framework, this stream state is linked to .hw_params() operation.
|
||||
|
||||
.. code-block:: c
|
||||
.. code-block:: c
|
||||
|
||||
int sdw_stream_add_master(struct sdw_bus * bus,
|
||||
struct sdw_stream_config * stream_config,
|
||||
@@ -274,7 +274,7 @@ Bus implements below API for PREPARE state which needs to be called once per
|
||||
stream. From ASoC DPCM framework, this stream state is linked to
|
||||
.prepare() operation.
|
||||
|
||||
.. code-block:: c
|
||||
.. code-block:: c
|
||||
|
||||
int sdw_prepare_stream(struct sdw_stream_runtime * stream);
|
||||
|
||||
@@ -304,7 +304,7 @@ Bus implements below API for ENABLE state which needs to be called once per
|
||||
stream. From ASoC DPCM framework, this stream state is linked to
|
||||
.trigger() start operation.
|
||||
|
||||
.. code-block:: c
|
||||
.. code-block:: c
|
||||
|
||||
int sdw_enable_stream(struct sdw_stream_runtime * stream);
|
||||
|
||||
@@ -332,7 +332,7 @@ Bus implements below API for DISABLED state which needs to be called once
|
||||
per stream. From ASoC DPCM framework, this stream state is linked to
|
||||
.trigger() stop operation.
|
||||
|
||||
.. code-block:: c
|
||||
.. code-block:: c
|
||||
|
||||
int sdw_disable_stream(struct sdw_stream_runtime * stream);
|
||||
|
||||
@@ -357,7 +357,7 @@ Bus implements below API for DEPREPARED state which needs to be called once
|
||||
per stream. From ASoC DPCM framework, this stream state is linked to
|
||||
.trigger() stop operation.
|
||||
|
||||
.. code-block:: c
|
||||
.. code-block:: c
|
||||
|
||||
int sdw_deprepare_stream(struct sdw_stream_runtime * stream);
|
||||
|
||||
@@ -382,7 +382,7 @@ Bus implements below APIs for RELEASE state which needs to be called by
|
||||
all the Master(s) and Slave(s) associated with stream. From ASoC DPCM
|
||||
framework, this stream state is linked to .hw_free() operation.
|
||||
|
||||
.. code-block:: c
|
||||
.. code-block:: c
|
||||
|
||||
int sdw_stream_remove_master(struct sdw_bus * bus,
|
||||
struct sdw_stream_runtime * stream);
|
||||
@@ -395,7 +395,7 @@ stream assigned as part of ALLOCATED state.
|
||||
|
||||
In .shutdown() the data structure maintaining stream state are freed up.
|
||||
|
||||
.. code-block:: c
|
||||
.. code-block:: c
|
||||
|
||||
void sdw_release_stream(struct sdw_stream_runtime * stream);
|
||||
|
||||
|
||||
@@ -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,21 +31,31 @@ 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 - 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
|
||||
|
||||
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
|
||||
@@ -86,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
|
||||
@@ -103,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.
|
||||
@@ -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,22 +4,22 @@ Livepatch
|
||||
|
||||
This document outlines basic information about kernel livepatching.
|
||||
|
||||
Table of Contents:
|
||||
.. Table of Contents:
|
||||
|
||||
1. Motivation
|
||||
2. Kprobes, Ftrace, Livepatching
|
||||
3. Consistency model
|
||||
4. Livepatch module
|
||||
4.1. New functions
|
||||
4.2. Metadata
|
||||
5. Livepatch life-cycle
|
||||
5.1. Loading
|
||||
5.2. Enabling
|
||||
5.3. Replacing
|
||||
5.4. Disabling
|
||||
5.5. Removing
|
||||
6. Sysfs
|
||||
7. Limitations
|
||||
1. Motivation
|
||||
2. Kprobes, Ftrace, Livepatching
|
||||
3. Consistency model
|
||||
4. Livepatch module
|
||||
4.1. New functions
|
||||
4.2. Metadata
|
||||
5. Livepatch life-cycle
|
||||
5.1. Loading
|
||||
5.2. Enabling
|
||||
5.3. Replacing
|
||||
5.4. Disabling
|
||||
5.5. Removing
|
||||
6. Sysfs
|
||||
7. Limitations
|
||||
|
||||
|
||||
1. Motivation
|
||||
@@ -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,33 +4,21 @@ Livepatch module Elf format
|
||||
|
||||
This document outlines the Elf format requirements that livepatch modules must follow.
|
||||
|
||||
-----------------
|
||||
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
|
||||
----------------------------
|
||||
.. Table of Contents
|
||||
|
||||
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,22 +70,23 @@ 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:
|
||||
-----------------------
|
||||
% modinfo livepatch-meminfo.ko
|
||||
filename: livepatch-meminfo.ko
|
||||
livepatch: Y
|
||||
license: GPL
|
||||
depends:
|
||||
vermagic: 4.3.0+ SMP mod_unload
|
||||
Example:
|
||||
--------
|
||||
|
||||
--------------------------------
|
||||
2. Livepatch relocation sections
|
||||
--------------------------------
|
||||
**Modinfo output:**
|
||||
|
||||
::
|
||||
|
||||
% modinfo livepatch-meminfo.ko
|
||||
filename: livepatch-meminfo.ko
|
||||
livepatch: Y
|
||||
license: GPL
|
||||
depends:
|
||||
vermagic: 4.3.0+ SMP mod_unload
|
||||
|
||||
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
|
||||
@@ -127,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
|
||||
@@ -140,28 +121,39 @@ 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:
|
||||
The name of a livepatch relocation section must conform to the following
|
||||
format::
|
||||
|
||||
.klp.rela.objname.section_name
|
||||
^ ^^ ^ ^ ^
|
||||
|________||_____| |__________|
|
||||
[A] [B] [C]
|
||||
.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) 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.
|
||||
|
||||
[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:**
|
||||
|
||||
::
|
||||
|
||||
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 ]
|
||||
@@ -175,31 +167,33 @@ module that patches vmlinux and modules 9p, btrfs, ext4:
|
||||
[ snip ] ^ ^
|
||||
| |
|
||||
[*] [*]
|
||||
[*] 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:
|
||||
-----------------------------------------------------------
|
||||
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
|
||||
0000000000000028 0000003d0000000b R_X86_64_32S 0000000000000000 .klp.sym.btrfs.btrfs_ktype,0 + 0
|
||||
0000000000000036 0000003b00000002 R_X86_64_PC32 0000000000000000 .klp.sym.btrfs.can_modify_feature.isra.3,0 - 4
|
||||
000000000000004c 0000004900000002 R_X86_64_PC32 0000000000000000 .klp.sym.vmlinux.snprintf,0 - 4
|
||||
[ snip ] ^
|
||||
|
|
||||
[*]
|
||||
[*] Every symbol referenced by a relocation is a livepatch symbol.
|
||||
[*]
|
||||
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).
|
||||
|
||||
--------------------
|
||||
3. Livepatch symbols
|
||||
--------------------
|
||||
**`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
|
||||
0000000000000028 0000003d0000000b R_X86_64_32S 0000000000000000 .klp.sym.btrfs.btrfs_ktype,0 + 0
|
||||
0000000000000036 0000003b00000002 R_X86_64_PC32 0000000000000000 .klp.sym.btrfs.can_modify_feature.isra.3,0 - 4
|
||||
000000000000004c 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
|
||||
====================
|
||||
|
||||
-------------------------------
|
||||
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
|
||||
@@ -219,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
|
||||
@@ -231,71 +224,82 @@ 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:
|
||||
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
|
||||
For example, take this particular rela from a livepatch module:::
|
||||
|
||||
This rela refers to the symbol '.klp.sym.vmlinux.printk,0', and the symbol index is encoded
|
||||
in 'Info'. Here its symbol index is 0x5e, which is 94 in decimal, which refers to the
|
||||
symbol 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 ]
|
||||
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
|
||||
|
||||
---------------------------
|
||||
3.3 Livepatch symbol format
|
||||
---------------------------
|
||||
This rela refers to the symbol '.klp.sym.vmlinux.printk,0', and the symbol index is encoded
|
||||
in 'Info'. Here its symbol index is 0x5e, which is 94 in decimal, which refers to the
|
||||
symbol 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
|
||||
===========================
|
||||
|
||||
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:
|
||||
Livepatch symbol names must conform to the following format::
|
||||
|
||||
.klp.sym.objname.symbol_name,sympos
|
||||
^ ^^ ^ ^ ^ ^
|
||||
|_______||_____| |_________| |
|
||||
[A] [B] [C] [D]
|
||||
.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) 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."
|
||||
|
||||
3.3.3 Example livepatch symbol names:
|
||||
-------------------------------------
|
||||
.klp.sym.vmlinux.snprintf,0
|
||||
.klp.sym.vmlinux.printk,0
|
||||
.klp.sym.btrfs.btrfs_ktype,0
|
||||
[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.4 Example `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.
|
||||
[C]
|
||||
The actual name of the symbol.
|
||||
|
||||
---------------------------------
|
||||
4. Architecture-specific sections
|
||||
---------------------------------
|
||||
[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:**
|
||||
|
||||
::
|
||||
|
||||
.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. 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
|
||||
@@ -304,20 +308,19 @@ 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,
|
||||
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 */
|
||||
Elf_Shdr *sechdrs; /* Section header table */
|
||||
char *secstrings; /* String table for the section headers */
|
||||
unsigned int symndx; /* The symbol table section index */
|
||||
};
|
||||
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 */
|
||||
};
|
||||
@@ -27,10 +27,13 @@ A hashtable references all shadow variables. These references are
|
||||
stored and retrieved through a <obj, id> pair.
|
||||
|
||||
* The klp_shadow variable data structure encapsulates both tracking
|
||||
meta-data and shadow-data:
|
||||
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,12 +117,12 @@ 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,
|
||||
const u8 *addr, gfp_t gfp)
|
||||
{
|
||||
#define PS_LOCK 1
|
||||
struct sta_info *sta_info_alloc(struct ieee80211_sub_if_data *sdata,
|
||||
const u8 *addr, gfp_t gfp)
|
||||
{
|
||||
struct sta_info *sta;
|
||||
spinlock_t *ps_lock;
|
||||
|
||||
@@ -123,10 +138,10 @@ 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)
|
||||
{
|
||||
void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta)
|
||||
{
|
||||
spinlock_t *ps_lock;
|
||||
|
||||
/* sync with ieee80211_tx_h_unicast_ps_buf */
|
||||
@@ -136,10 +151,10 @@ 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)
|
||||
{
|
||||
void sta_info_free(struct ieee80211_local *local, struct sta_info *sta)
|
||||
{
|
||||
klp_shadow_free(sta, PS_LOCK, NULL);
|
||||
kfree(sta);
|
||||
...
|
||||
@@ -155,19 +170,19 @@ 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)
|
||||
{
|
||||
int ps_lock_shadow_ctor(void *obj, void *shadow_data, void *ctor_data)
|
||||
{
|
||||
spinlock_t *lock = shadow_data;
|
||||
|
||||
spin_lock_init(lock);
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
|
||||
#define PS_LOCK 1
|
||||
void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta)
|
||||
{
|
||||
#define PS_LOCK 1
|
||||
void ieee80211_sta_ps_deliver_wakeup(struct sta_info *sta)
|
||||
{
|
||||
spinlock_t *ps_lock;
|
||||
|
||||
/* sync with ieee80211_tx_h_unicast_ps_buf */
|
||||
@@ -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.
|
||||
|
||||
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".
|
||||
|
||||
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".
|
||||
@@ -41,9 +41,10 @@ mainly used to perform the proper memory window initialization. Typically
|
||||
there are two types of memory window interfaces supported by the NTB API:
|
||||
inbound translation configured on the local ntb port and outbound translation
|
||||
configured by the peer, on the peer ntb port. The first type is
|
||||
depicted on the next figure
|
||||
depicted on the next figure::
|
||||
|
||||
Inbound translation:
|
||||
|
||||
Inbound translation:
|
||||
Memory: Local NTB Port: Peer NTB Port: Peer MMIO:
|
||||
____________
|
||||
| dma-mapped |-ntb_mw_set_trans(addr) |
|
||||
@@ -58,9 +59,10 @@ maps corresponding outbound memory window so to have access to the shared
|
||||
memory region.
|
||||
|
||||
The second type of interface, that implies the shared windows being
|
||||
initialized by a peer device, is depicted on the figure:
|
||||
initialized by a peer device, is depicted on the figure::
|
||||
|
||||
Outbound translation:
|
||||
|
||||
Outbound translation:
|
||||
Memory: Local NTB Port: Peer NTB Port: Peer MMIO:
|
||||
____________ ______________
|
||||
| dma-mapped | | | MW base addr |<== memory-mapped IO
|
||||
@@ -75,11 +77,13 @@ outbound memory window so to have access to the shared memory region.
|
||||
|
||||
As one can see the described scenarios can be combined in one portable
|
||||
algorithm.
|
||||
|
||||
Local device:
|
||||
1) Allocate memory for a shared window
|
||||
2) Initialize memory window by translated address of the allocated region
|
||||
(it may fail if local memory window initialization is unsupported)
|
||||
3) Send the translated address and memory window index to a peer device
|
||||
|
||||
Peer device:
|
||||
1) Initialize memory window with retrieved address of the allocated
|
||||
by another device memory region (it may fail if peer memory window
|
||||
@@ -88,6 +92,7 @@ algorithm.
|
||||
|
||||
In accordance with this scenario, the NTB Memory Window API can be used as
|
||||
follows:
|
||||
|
||||
Local device:
|
||||
1) ntb_mw_count(pidx) - retrieve number of memory ranges, which can
|
||||
be allocated for memory windows between local device and peer device
|
||||
@@ -103,6 +108,7 @@ follows:
|
||||
5) Send translated base address (usually together with memory window
|
||||
number) to the peer device using, for instance, scratchpad or message
|
||||
registers.
|
||||
|
||||
Peer device:
|
||||
1) ntb_peer_mw_set_trans(pidx, midx) - try to set received from other
|
||||
device (related to pidx) translated address for specified memory
|
||||
|
||||
@@ -216,10 +216,12 @@ The tags in common use are:
|
||||
which can be found in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
|
||||
Code without a proper signoff cannot be merged into the mainline.
|
||||
|
||||
- Co-developed-by: states that the patch was also created by another developer
|
||||
along with the original author. This is useful at times when multiple
|
||||
people work on a single patch. Note, this person also needs to have a
|
||||
Signed-off-by: line in the patch as well.
|
||||
- Co-developed-by: states that the patch was co-created by several developers;
|
||||
it is a used to give attribution to co-authors (in addition to the author
|
||||
attributed by the From: tag) when multiple people work on a single patch.
|
||||
Every Co-developed-by: must be immediately followed by a Signed-off-by: of
|
||||
the associated co-author. Details and examples can be found in
|
||||
:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
|
||||
|
||||
- Acked-by: indicates an agreement by another developer (often a
|
||||
maintainer of the relevant code) that the patch is appropriate for
|
||||
|
||||
@@ -843,7 +843,8 @@ used.
|
||||
The kernel provides the following general purpose memory allocators:
|
||||
kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
|
||||
vzalloc(). Please refer to the API documentation for further information
|
||||
about them.
|
||||
about them. :ref:`Documentation/core-api/memory-allocation.rst
|
||||
<memory_allocation>`
|
||||
|
||||
The preferred form for passing a size of a struct is the following:
|
||||
|
||||
@@ -874,6 +875,9 @@ The preferred form for allocating a zeroed array is the following:
|
||||
Both forms check for overflow on the allocation size n * sizeof(...),
|
||||
and return NULL if that occurred.
|
||||
|
||||
These generic allocation functions all emit a stack dump on failure when used
|
||||
without __GFP_NOWARN so there is no use in emitting an additional failure
|
||||
message when NULL is returned.
|
||||
|
||||
15) The inline disease
|
||||
----------------------
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user