Documentation/livepatch/reliable-stacktrace.rst

15 functions may have live state and therefore may not be safe to patch. One way
16 to identify which functions are live is to use a stacktrace.
19 functions with live state, and best-effort approaches which can be helpful for
22 functions from a trace.
28 Architectures must implement one of the reliable stacktrace functions.
35 * The trace includes all functions that the task may be returned to, and the
38 * The return code is non-zero to indicate that the trace is not reliable.
41    In some cases it is legitimate to omit specific functions from the trace,
42    but all other functions must be reported. These cases are described in
47 function should attempt to detect such cases and return a non-zero error
48 code, and should not get stuck in an infinite loop or access memory in
49 an unsafe way.  Specific cases are described in further detail below.
52 3. Compile-time analysis
55 To ensure that kernel code can be correctly unwound in all cases,
56 architectures may need to verify that code has been compiled in a manner
58 functions manipulate the stack pointer in a limited way, or that all
59 functions use specific prologue and epilogue sequences. Architectures
63 In some cases, an unwinder may require metadata to correctly unwind.
76 --------------------------------------
82 * Missing unwind support for an uncommon scenario, or a bug in the unwinder.
87 To ensure that this does not result in functions being omitted from the trace,
99 -------------------------------
103 conventions and may require special handling in the unwinder, e.g.
107 * Procedure Linkage Table (PLT) entries and veneer functions.
115 To ensure that such cases do not result in functions being omitted from a
128   any code in these sections.
133 ----------------------------------------------
136 in a consistent state suitable for reliable unwinding, but this may not be the
137 case part-way through a function. For example, during a function prologue or
139 body the return address may be held in an arbitrary general purpose register.
144 state is in an inconsistent state, it may not be possible to reliably unwind,
160 ---------------------------------
162 Some trampolines temporarily modify the return address of a function in order
171 When this happens, the original return address will not be in its usual
175 address in place of the trampoline and report this as reliable. Otherwise, an
179 information is not in a consistent location for the duration of the entry
183 .. code-block:: none
204 the start of return_to_handler, and the original return address is stored in
210 in the task's cur_ret_stack. Within ftrace_return_to_handler(), the original
212 arbitrarily by the compiler before being returned in rax. The return_to_handler
226 ---------------------------------
228 Some trampolines do not rewrite the return address in order to intercept
234 address of the probed function is not held in any register or on the stack.
237 functions with the following:
239 .. code-block:: none
246 start of the trampoline, the address of the traced function is in X9 rather
253 -------------------------------
259 the duration of a function call, the return address may be held in the link
260 register alone, on the stack alone, or in both locations.
266 .. code-block:: none
269            STP X29, X30, [SP, -16]!
286 and so a trace at this point could result in 'function' appearing twice in the
291 .. code-block:: none
294            STP X29, X30, [SP, -16]!