Skip to contentSkip to conversation

Documentation: livepatch: document reliable stacktrace

PATCH Superseded Mark Brown 4 participants 6 messages Jan 15, 2021 – Jan 18, 2021

Subsystems (2)

v3 of 6 Superseded Latest is v6 →

lore
Share & tools
lore

Mark Brown

author
#0 lore raw

PATCH v3 1/1 Documentation: livepatch: document reliable stacktrace

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.

I've tried to give rationale for all the recommendations/requirements, since that makes it easier to spot nearby issues, or when a check happens to catch a few things at once. I believe what I have written is sound, but as some of this was reverse-engineered I may have missed things worth noting.

I've made a few assumptions about preferred behaviour, notably:

* If you can reliably unwind through exceptions, you should (as x86_64 does).

* It's fine to omit ftrace_return_to_handler and other return trampolines so long as these are not subject to patching and the original return address is reported. Most architectures do this for ftrace_return_handler, but not other return trampolines.

* For cases where link register unreliability could result in duplicate entries in the trace or an inverted trace, I've assumed this should be treated as unreliable. This specific case shouldn't matter to livepatching, but I assume that that we want a reliable trace to have the correct order.

Cc Jiri Kosina <[email protected]>
Cc Joe Lawrence <[email protected]>
Cc Jonathan Corbet <[email protected]>
Cc Josh Poimboeuf <[email protected]>
Cc Mark Brown <[email protected]>
Cc Miroslav Benes <[email protected]>
Cc Petr Mladek <[email protected]>
[Updates following review -- broonie]

---

v3:
- Incorporated objtool section from Mark.
- Deleted confusing notes about using annotations.

 Documentation/livepatch/index.rst             |   1 +
 .../livepatch/reliable-stacktrace.rst         | 317 ++++++++++++++++++
 2 files changed, 318 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 +317 -0

317 lines not on this page · raw message

Signature · 1 line
2.20.1
Acked-by on v3 1/1
#1 lore raw
Quoted 47 lines · 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.

I've tried to give rationale for all the recommendations/requirements, since that makes it easier to spot nearby issues, or when a check happens to catch a few things at once. I believe what I have written is sound, but as some of this was reverse-engineered I may have missed things worth noting.

I've made a few assumptions about preferred behaviour, notably:

* If you can reliably unwind through exceptions, you should (as x86_64 does).

* It's fine to omit ftrace_return_to_handler and other return trampolines so long as these are not subject to patching and the original return address is reported. Most architectures do this for ftrace_return_handler, but not other return trampolines.

* For cases where link register unreliability could result in duplicate entries in the trace or an inverted trace, I've assumed this should be treated as unreliable. This specific case shouldn't matter to livepatching, but I assume that that we want a reliable trace to have the correct order.

Cc Jiri Kosina <[email protected]>
Cc Joe Lawrence <[email protected]>
Cc Jonathan Corbet <[email protected]>
Cc Josh Poimboeuf <[email protected]>
Cc Mark Brown <[email protected]>
Cc Miroslav Benes <[email protected]>
Cc Petr Mladek <[email protected]>
[Updates following review -- broonie]
Quoted 5 lines

---

v3:
- Incorporated objtool section from Mark.
- Deleted confusing notes about using annotations.

Signature · 1 line
Josh
#2 lore raw
In reply to Mark Brown

Hi Mark,

Documentation/livepatch/reliable-stacktrace.rst line 17

Quoted 12 lines · Mark Brown

+.. Table of Contents:

Documentation/livepatch/reliable-stacktrace.rst new file +10 -0
+
+    1. Introduction
+    2. Requirements
+    3. Considerations
+       3.1 Identifying successful termination
+       3.2 Identifying unwindable code
+       3.3 Unwinding across interrupts and exceptions
+       3.4 Rewriting of return addresses
+       3.5 Obscuring of return addresses
+       3.6 Link register unreliability

It looks like we forgot to update this with the addition of the new section 3, so this needs a trivial update to add that and fix the numbering.

Otherwise this looks good; thanks for taking this off my hands! :)

Mark.

author
#3 lore raw
Quoted 8 lines · Mark Rutland

Documentation/livepatch/reliable-stacktrace.rst line 12

Quoted 2 lines · Mark Brown
Documentation/livepatch/reliable-stacktrace.rst new file +2 -0
+    3. Considerations
+       3.1 Identifying successful termination

It looks like we forgot to update this with the addition of the new section 3, so this needs a trivial update to add that and fix the numbering.

Bah, I thought the point with structured documentation formats was that tooling would handle stuff like this :/

Quoted 1 line

Otherwise this looks good; thanks for taking this off my hands! :)

Thanks for doing almost all the work!

maintainer
#4 lore raw
Quoted 6 lines · On Fri, 15 Jan 2021 17:12:51 +0000 Mark Brown <[email protected]> wrote:
Quoted 4 lines · Mark Rutland
Quoted 2 lines · Mark Brown
Documentation/livepatch/reliable-stacktrace.rst new file +2 -0
+    3. Considerations
+       3.1 Identifying successful termination  
Quoted 6 lines
Quoted 3 lines

It looks like we forgot to update this with the addition of the new section 3, so this needs a trivial update to add that and fix the numbering.

Bah, I thought the point with structured documentation formats was that tooling would handle stuff like this :/

The tooling *will* handle it if you let it, it's a simple matter of replacing the hand-generated table of contents with a Sphinx directive. I think that's generally the right thing to do, but it does have the downside of only putting the TOC in the generated docs.

Thanks,

jon

#5 lore raw
Quoted 13 lines · Jonathan Corbet
Quoted 10 lines · On Fri, 15 Jan 2021 17:12:51 +0000 Mark Brown <[email protected]> wrote:
Quoted 8 lines · Mark Rutland

Documentation/livepatch/reliable-stacktrace.rst line 12

Quoted 2 lines · Mark Brown
Documentation/livepatch/reliable-stacktrace.rst new file +2 -0
+    3. Considerations
+       3.1 Identifying successful termination  

It looks like we forgot to update this with the addition of the new section 3, so this needs a trivial update to add that and fix the numbering.

Quoted 7 lines
Quoted 2 lines

Bah, I thought the point with structured documentation formats was that tooling would handle stuff like this :/

The tooling *will* handle it if you let it, it's a simple matter of replacing the hand-generated table of contents with a Sphinx directive. I think that's generally the right thing to do, but it does have the downside of only putting the TOC in the generated docs.

Ah, I was not aware of that, and I had copied the TOC style from Documentation/livepatch/livepatch.rst.

That does sound like the right thing to do generally, and I have no problem doing that here, but I guess we be consistent and either do that for all or none of the Documentation/livepatch/*.rst documents. I guess we could do that as a followup?

Thanks,
Mark.