Skip to contentSkip to conversation

Documentation: livepatch: Document reliable stacktrace and minor cleanup

PATCH In review Mark Brown 4 participants 7 messages Jan 20, 2021 – Jan 27, 2021

Subsystems (2)
lore
Share & tools
lore
author
#2 lore raw

PATCH v6 2/2 Documentation: livepatch: document reliable stacktrace

In reply to Mark Brown

From: Mark Rutland <[email protected]>

Add documentation for reliable stacktrace. This is intended to describe the semantics and to be an aid for implementing architecture support for HAVE_RELIABLE_STACKTRACE.

Unwinding is a subtle area, and architectures vary greatly in both implementation and the set of concerns that affect them, so I've tried to avoid making this too specific to any given architecture. I've used examples from both x86_64 and arm64 to explain corner cases in more detail, but I've tried to keep the descriptions sufficient for those who are unfamiliar with the particular architecture.

This document aims to give rationale for all the recommendations and requirements, since that makes it easier to spot nearby issues, or when a check happens to catch a few things at once.

---
 Documentation/livepatch/index.rst             |   1 +
 .../livepatch/reliable-stacktrace.rst         | 309 ++++++++++++++++++
 2 files changed, 310 insertions(+)
 create mode 100644 Documentation/livepatch/reliable-stacktrace.rst
Documentation/livepatch/index.rst +1 -0
index 525944063be7..43cce5fad705 100644
@@ -13,6 +13,7 @@ Kernel Livepatching
     module-elf-format
     shadow-vars
     system-state
+    reliable-stacktrace
 
 .. only::  subproject and html
 
Documentation/livepatch/reliable-stacktrace.rst new file +309 -0

309 lines not on this page · raw message

Signature · 1 line
2.20.1

Mark Brown

author
#0 lore raw

v6 cover Documentation: livepatch: Document reliable stacktrace and minor cleanup

This series adds a document, mainly written by Mark Rutland, which makes explicit the requirements for implementing reliable stacktrace in order to aid architectures adding this feature. It also updates the other livepatching documents to use automatically generated tables of contents following review comments on Mark's document.

v6:
- Remove a duplicated "points".
v5:
- Tweaks to the commit message for the new document.
- Convert new and existing documents to autogenerated tables of contents.
v4:
- Renumber table of contents
v3:
- Incorporated objtool section from Mark.
- Deleted confusing notes about using annotations.

Mark Brown (1):
Documentation: livepatch: Convert to automatically generated contents

Mark Rutland (1):
Documentation: livepatch: document reliable stacktrace

 Documentation/livepatch/index.rst             |   1 +
 Documentation/livepatch/livepatch.rst         |  15 +-
 Documentation/livepatch/module-elf-format.rst |  10 +-
 .../livepatch/reliable-stacktrace.rst         | 309 ++++++++++++++++++
 4 files changed, 313 insertions(+), 22 deletions(-)
 create mode 100644 Documentation/livepatch/reliable-stacktrace.rst

base-commit: 7c53f6b671f4aba70ff15e1b05148b10d58c2837

Signature · 1 line
2.20.1
author
#1 lore raw

PATCH v6 1/2 Documentation: livepatch: Convert to automatically generated contents

Automatically generate the tables of contents for livepatch documentation files that have tables of contents rather than open coding them so things are a little easier to maintain.

---
 Documentation/livepatch/livepatch.rst         | 15 +--------------
 Documentation/livepatch/module-elf-format.rst | 10 ++--------
 2 files changed, 3 insertions(+), 22 deletions(-)
Documentation/livepatch/livepatch.rst +1 -14
index c2c598c4ead8..68e3651e8af9 100644
@@ -6,20 +6,7 @@ This document outlines basic information about kernel livepatching.
 
 .. 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
+.. contents:: :local:
 
 
 1. Motivation
Documentation/livepatch/module-elf-format.rst +2 -8
index 8c6b894c4661..dbe9b400e39f 100644
@@ -7,14 +7,8 @@ This document outlines the Elf format requirements that livepatch modules must f
 
 .. 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. Symbol table and Elf section access
+.. contents:: :local:
+
 
 1. Background and motivation
 ============================
Signature · 1 line
2.20.1
maintainer
#3 lore raw
In reply to Mark Brown
Quoted 5 lines · On Wed, 20 Jan 2021 16:47:12 +0000 Mark Brown <[email protected]> wrote:

This series adds a document, mainly written by Mark Rutland, which makes explicit the requirements for implementing reliable stacktrace in order to aid architectures adding this feature. It also updates the other livepatching documents to use automatically generated tables of contents following review comments on Mark's document.

So...is this deemed ready and, if so, do you want it to go through the docs tree or via some other path?

Thanks,

jon

#4 lore raw
Quoted 8 lines · Jonathan Corbet
Quoted 5 lines

This series adds a document, mainly written by Mark Rutland, which makes explicit the requirements for implementing reliable stacktrace in order to aid architectures adding this feature. It also updates the other livepatching documents to use automatically generated tables of contents following review comments on Mark's document.

So...is this deemed ready and, if so, do you want it to go through the docs tree or via some other path?

I am planning to take it through livepatching tree unless there are any additional last-minutes comments.

Thanks,

Signature · 2 lines
Jiri Kosina
SUSE Labs
#5 lore raw
Quoted 11 lines · Jiri Kosina
Quoted 8 lines
Quoted 5 lines

This series adds a document, mainly written by Mark Rutland, which makes explicit the requirements for implementing reliable stacktrace in order to aid architectures adding this feature. It also updates the other livepatching documents to use automatically generated tables of contents following review comments on Mark's document.

So...is this deemed ready and, if so, do you want it to go through the docs tree or via some other path?

I am planning to take it through livepatching tree unless there are any additional last-minutes comments.

Now applied to for-5.12/doc branch. Thanks,

Signature · 2 lines
Jiri Kosina
SUSE Labs
maintainer Acked-by on the v6 series
#6 lore raw
In reply to Mark Brown

Hi,

Quoted 24 lines · Mark Brown

This series adds a document, mainly written by Mark Rutland, which makes explicit the requirements for implementing reliable stacktrace in order to aid architectures adding this feature. It also updates the other livepatching documents to use automatically generated tables of contents following review comments on Mark's document.

v6:
- Remove a duplicated "points".
v5:
- Tweaks to the commit message for the new document.
- Convert new and existing documents to autogenerated tables of contents.
v4:
- Renumber table of contents
v3:
- Incorporated objtool section from Mark.
- Deleted confusing notes about using annotations.

Mark Brown (1):
Documentation: livepatch: Convert to automatically generated contents

Mark Rutland (1):
Documentation: livepatch: document reliable stacktrace

Quoted 6 lines
 Documentation/livepatch/index.rst             |   1 +
 Documentation/livepatch/livepatch.rst         |  15 +-
 Documentation/livepatch/module-elf-format.rst |  10 +-
 .../livepatch/reliable-stacktrace.rst         | 309 ++++++++++++++++++
 4 files changed, 313 insertions(+), 22 deletions(-)
 create mode 100644 Documentation/livepatch/reliable-stacktrace.rst

sorry for the late reply (slowly crawling through my email backlog). Thanks a lot for putting this together!

FWIW (so it is at least archived in the thread)

M