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>
Acked-by: Joe Lawrence <joe.lawrence@redhat.com>
Acked-by: Josh Poimboeuf <jpoimboe@redhat.com>
Acked-by: Miroslav Benes <mbenes@suse.cz>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Reviewed-by: Kamalesh Babulal <kamalesh@linux.vnet.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

1 files changed, 18 insertions, 15 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 @@ Callbacks can be registered for the following livepatch actions:
                    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.