print_context_stack() was removed in 2016 by commit c8fe4609827ae
("x86/dumpstack: Remove dump_trace() and related callbacks"). Remove
the now-inaccurate guide.

While at it, also link to Ingo's explanatory message.

Signed-off-by: Jiayuan Chen <mrpre@163.com>
Suggested-by: Randy Dunlap <rdunlap@infradead.org>
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Suggested-by: Bagas Sanjaya <bagasdotme@gmail.com>

---
V3 -> V4: Made changes based on Bagas's suggestion.
V1 -> V3: Made changes based on suggestions from Randy and Jonathan.
---
 Documentation/arch/x86/kernel-stacks.rst | 60 +++++++++---------------
 1 file changed, 22 insertions(+), 38 deletions(-)

diff --git a/Documentation/arch/x86/kernel-stacks.rst b/Documentation/arch/x86/kernel-stacks.rst
index 738671a4070b..4cb68433272d 100644
--- a/Documentation/arch/x86/kernel-stacks.rst
+++ b/Documentation/arch/x86/kernel-stacks.rst
@@ -112,41 +112,25 @@ Printing backtraces on x86
 ==========================
 
 The question about the '?' preceding function names in an x86 stacktrace
-keeps popping up, here's an indepth explanation. It helps if the reader
-stares at print_context_stack() and the whole machinery in and around
-arch/x86/kernel/dumpstack.c.
-
-Adapted from Ingo's mail, Message-ID: <20150521101614.GA10889@gmail.com>:
-
-We always scan the full kernel stack for return addresses stored on
-the kernel stack(s) [1]_, from stack top to stack bottom, and print out
-anything that 'looks like' a kernel text address.
-
-If it fits into the frame pointer chain, we print it without a question
-mark, knowing that it's part of the real backtrace.
-
-If the address does not fit into our expected frame pointer chain we
-still print it, but we print a '?'. It can mean two things:
-
- - either the address is not part of the call chain: it's just stale
-   values on the kernel stack, from earlier function calls. This is
-   the common case.
-
- - or it is part of the call chain, but the frame pointer was not set
-   up properly within the function, so we don't recognize it.
-
-This way we will always print out the real call chain (plus a few more
-entries), regardless of whether the frame pointer was set up correctly
-or not - but in most cases we'll get the call chain right as well. The
-entries printed are strictly in stack order, so you can deduce more
-information from that as well.
-
-The most important property of this method is that we _never_ lose
-information: we always strive to print _all_ addresses on the stack(s)
-that look like kernel text addresses, so if debug information is wrong,
-we still print out the real call chain as well - just with more question
-marks than ideal.
-
-.. [1] For things like IRQ and IST stacks, we also scan those stacks, in
-       the right order, and try to cross from one stack into another
-       reconstructing the call chain. This works most of the time.
+keeps popping up. Here's the explanation, that helps when the reader
+stares at printk_stack_addressk() and its callers and pays special
+attention to the 'reliable' parameter ('?' basically means that the
+address is unreliable).
+
+The answer can be found in the comments within show_trace_log_lvl() body
+in arch/x86/kernel/dumpstack.c::
+
+    /*
+     * Scan the stack, printing any text addresses we find.  At the
+     * same time, follow proper stack frames with the unwinder.
+     *
+     * Addresses found during the scan which are not reported by
+     * the unwinder are considered to be additional clues which are
+     * sometimes useful for debugging and are prefixed with '?'.
+     * This also serves as a failsafe option in case the unwinder
+     * goes off in the weeds.
+     */
+
+For more information, see also Ingo's email. [1]_
+
+.. [1] https://lore.kernel.org/lkml/20150521101614.GA10889@gmail.com/
-- 
2.43.5

Jiayuan Chen <mrpre@163.com> writes:

> print_context_stack() was removed in 2016 by commit c8fe4609827ae
> ("x86/dumpstack: Remove dump_trace() and related callbacks"). Remove
> the now-inaccurate guide.
>
> While at it, also link to Ingo's explanatory message.
>
> Signed-off-by: Jiayuan Chen <mrpre@163.com>
> Suggested-by: Randy Dunlap <rdunlap@infradead.org>
> Suggested-by: Jonathan Corbet <corbet@lwn.net>
> Suggested-by: Bagas Sanjaya <bagasdotme@gmail.com>
>
> ---
> V3 -> V4: Made changes based on Bagas's suggestion.
> V1 -> V3: Made changes based on suggestions from Randy and Jonathan.
> ---
>  Documentation/arch/x86/kernel-stacks.rst | 60 +++++++++---------------
>  1 file changed, 22 insertions(+), 38 deletions(-)

You didn't add Randy's Reviewed-by

This change is more than just removing a function name, though, so the
subject line is a bit off.  There's enough changing here that I would
really rather have an ack from the x86 folks before applying it.

Thanks,

jon

> diff --git a/Documentation/arch/x86/kernel-stacks.rst b/Documentation/arch/x86/kernel-stacks.rst
> index 738671a4070b..4cb68433272d 100644
> --- a/Documentation/arch/x86/kernel-stacks.rst
> +++ b/Documentation/arch/x86/kernel-stacks.rst
> @@ -112,41 +112,25 @@ Printing backtraces on x86
>  ==========================
>  
>  The question about the '?' preceding function names in an x86 stacktrace
> -keeps popping up, here's an indepth explanation. It helps if the reader
> -stares at print_context_stack() and the whole machinery in and around
> -arch/x86/kernel/dumpstack.c.
> -
> -Adapted from Ingo's mail, Message-ID: <20150521101614.GA10889@gmail.com>:
> -
> -We always scan the full kernel stack for return addresses stored on
> -the kernel stack(s) [1]_, from stack top to stack bottom, and print out
> -anything that 'looks like' a kernel text address.
> -
> -If it fits into the frame pointer chain, we print it without a question
> -mark, knowing that it's part of the real backtrace.
> -
> -If the address does not fit into our expected frame pointer chain we
> -still print it, but we print a '?'. It can mean two things:
> -
> - - either the address is not part of the call chain: it's just stale
> -   values on the kernel stack, from earlier function calls. This is
> -   the common case.
> -
> - - or it is part of the call chain, but the frame pointer was not set
> -   up properly within the function, so we don't recognize it.
> -
> -This way we will always print out the real call chain (plus a few more
> -entries), regardless of whether the frame pointer was set up correctly
> -or not - but in most cases we'll get the call chain right as well. The
> -entries printed are strictly in stack order, so you can deduce more
> -information from that as well.
> -
> -The most important property of this method is that we _never_ lose
> -information: we always strive to print _all_ addresses on the stack(s)
> -that look like kernel text addresses, so if debug information is wrong,
> -we still print out the real call chain as well - just with more question
> -marks than ideal.
> -
> -.. [1] For things like IRQ and IST stacks, we also scan those stacks, in
> -       the right order, and try to cross from one stack into another
> -       reconstructing the call chain. This works most of the time.
> +keeps popping up. Here's the explanation, that helps when the reader
> +stares at printk_stack_addressk() and its callers and pays special
> +attention to the 'reliable' parameter ('?' basically means that the
> +address is unreliable).
> +
> +The answer can be found in the comments within show_trace_log_lvl() body
> +in arch/x86/kernel/dumpstack.c::
> +
> +    /*
> +     * Scan the stack, printing any text addresses we find.  At the
> +     * same time, follow proper stack frames with the unwinder.
> +     *
> +     * Addresses found during the scan which are not reported by
> +     * the unwinder are considered to be additional clues which are
> +     * sometimes useful for debugging and are prefixed with '?'.
> +     * This also serves as a failsafe option in case the unwinder
> +     * goes off in the weeds.
> +     */
> +
> +For more information, see also Ingo's email. [1]_
> +
> +.. [1] https://lore.kernel.org/lkml/20150521101614.GA10889@gmail.com/
> -- 
> 2.43.5