[PATCH v1] docs/arch: remove deprecated function name

[PATCH v1] docs/arch: remove deprecated function name

[Jiayuan Chen]

The dumpstack.c file has undergone many modifications, and the
print_context_stack() function was removed or rewritten a long time ago,
so it's better to remove the incorrect guidance. Additionally, no new
functions will be added to the documentation, as it may be modified again
in the future. Using 'question mark' and 'dumpstack' is sufficient to
index this document.

Signed-off-by: Jiayuan Chen <mrpre@163.com>
---
 Documentation/arch/x86/kernel-stacks.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/arch/x86/kernel-stacks.rst b/Documentation/arch/x86/kernel-stacks.rst
index 738671a4070b..2d355e78008e 100644
--- a/Documentation/arch/x86/kernel-stacks.rst
+++ b/Documentation/arch/x86/kernel-stacks.rst
@@ -113,7 +113,7 @@ 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
+stares at 'question mark' and the whole machinery in and around
 arch/x86/kernel/dumpstack.c.
 
 Adapted from Ingo's mail, Message-ID: <20150521101614.GA10889@gmail.com>:
-- 
2.43.5

Re: [PATCH v1] docs/arch: remove deprecated function name

[Jonathan Corbet]

Jiayuan Chen <mrpre@163.com> writes:

> The dumpstack.c file has undergone many modifications, and the
> print_context_stack() function was removed or rewritten a long time ago,
> so it's better to remove the incorrect guidance. Additionally, no new
> functions will be added to the documentation, as it may be modified again
> in the future. Using 'question mark' and 'dumpstack' is sufficient to
> index this document.
>
> Signed-off-by: Jiayuan Chen <mrpre@163.com>
> ---
>  Documentation/arch/x86/kernel-stacks.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/arch/x86/kernel-stacks.rst b/Documentation/arch/x86/kernel-stacks.rst
> index 738671a4070b..2d355e78008e 100644
> --- a/Documentation/arch/x86/kernel-stacks.rst
> +++ b/Documentation/arch/x86/kernel-stacks.rst
> @@ -113,7 +113,7 @@ 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
> +stares at 'question mark' and the whole machinery in and around
>  arch/x86/kernel/dumpstack.c.

Maybe - probably - I'm missing something, but I don't see how this is
going to help our readers?  If there *is* a function that will, by
virtue of being stared at, help bring enlightenment, why wouldn't we
name it?

Thanks,

jon

Re: [PATCH v1] docs/arch: remove deprecated function name

[Jiayuan Chen]

On Tue, Jan 14, 2025 at 10:11:01AM +0800, Jonathan Corbet wrote:
> Jiayuan Chen <mrpre@163.com> writes:
> 
> >  
> >  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
> > +stares at 'question mark' and the whole machinery in and around
> >  arch/x86/kernel/dumpstack.c.
> 
> Maybe - probably - I'm missing something, but I don't see how this is
> going to help our readers?  If there *is* a function that will, by
> virtue of being stared at, help bring enlightenment, why wouldn't we
> name it?
> 
> Thanks,
> 
> jon
You're right.
As Randy mentioned, printk_stack_address() can probably be used as a
drop-in replacement for the original function, and I found that it hasn't
been touched since 3.12 anyway.

Re: [PATCH v1] docs/arch: remove deprecated function name

[Randy Dunlap]

Hi--

On 1/14/25 1:48 AM, Jiayuan Chen wrote:
> The dumpstack.c file has undergone many modifications, and the
> print_context_stack() function was removed or rewritten a long time ago,
> so it's better to remove the incorrect guidance. Additionally, no new
> functions will be added to the documentation, as it may be modified again
> in the future. Using 'question mark' and 'dumpstack' is sufficient to
> index this document.
> 
> Signed-off-by: Jiayuan Chen <mrpre@163.com>
> ---
>  Documentation/arch/x86/kernel-stacks.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/arch/x86/kernel-stacks.rst b/Documentation/arch/x86/kernel-stacks.rst
> index 738671a4070b..2d355e78008e 100644
> --- a/Documentation/arch/x86/kernel-stacks.rst
> +++ b/Documentation/arch/x86/kernel-stacks.rst
> @@ -113,7 +113,7 @@ 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

  stares at printk_stack_address() and its callers
  and pay special attention to the 'reliable' parameter ('?' basically
  means that the address is unreliable)

Also see the comment from 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.
		 */

> +stares at 'question mark' and the whole machinery in and around
>  arch/x86/kernel/dumpstack.c.
>  
>  Adapted from Ingo's mail, Message-ID: <20150521101614.GA10889@gmail.com>:

-- 
~Randy

[PATCH v2] docs/arch: remove deprecated function name

[Jiayuan Chen]

The dumpstack.c file has undergone many modifications, and the
print_context_stack() function was removed or rewritten a long time ago,
so it's better to remove the incorrect guidance.

I also want to preserve the original contributor info by keeping email
adress and name.

Signed-off-by: Jiayuan Chen <mrpre@163.com>
---
 Documentation/arch/x86/kernel-stacks.rst | 51 +++++++++---------------
 1 file changed, 18 insertions(+), 33 deletions(-)

diff --git a/Documentation/arch/x86/kernel-stacks.rst b/Documentation/arch/x86/kernel-stacks.rst
index 738671a4070b..f780f4b09761 100644
--- a/Documentation/arch/x86/kernel-stacks.rst
+++ b/Documentation/arch/x86/kernel-stacks.rst
@@ -112,41 +112,26 @@ 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.
+keeps popping up, here provides guidance about it. It helps if the reader
+stares at printk_stack_addressk() and its callers and pay special
+attention to the 'reliable' parameter ('?' basically means that the
+address is unreliable).
 
-Adapted from Ingo's mail, Message-ID: <20150521101614.GA10889@gmail.com>:
+The detail about '?' can be found in the comments within dumpstack.c:
+::
 
-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.
+    /*
+     * 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.
+     */
 
-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:
+You can also get more info from Ingo's original emal [1]_
 
- - 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.
+.. [1] https://lore.kernel.org/lkml/20150521101614.GA10889@gmail.com/
-- 
2.43.5

Re: [PATCH v2] docs/arch: remove deprecated function name

[Randy Dunlap]

Hi:

On 1/16/25 8:20 AM, Jiayuan Chen wrote:
> The dumpstack.c file has undergone many modifications, and the
> print_context_stack() function was removed or rewritten a long time ago,
> so it's better to remove the incorrect guidance.
> 
> I also want to preserve the original contributor info by keeping email
> adress and name.
> 
> Signed-off-by: Jiayuan Chen <mrpre@163.com>
> ---
>  Documentation/arch/x86/kernel-stacks.rst | 51 +++++++++---------------
>  1 file changed, 18 insertions(+), 33 deletions(-)
> 
> diff --git a/Documentation/arch/x86/kernel-stacks.rst b/Documentation/arch/x86/kernel-stacks.rst
> index 738671a4070b..f780f4b09761 100644
> --- a/Documentation/arch/x86/kernel-stacks.rst
> +++ b/Documentation/arch/x86/kernel-stacks.rst
> @@ -112,41 +112,26 @@ 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.
> +keeps popping up, here provides guidance about it. It helps if the reader

         popping up. This provides

> +stares at printk_stack_addressk() and its callers and pay special

                                                         pays

> +attention to the 'reliable' parameter ('?' basically means that the
> +address is unreliable).
>  
> -Adapted from Ingo's mail, Message-ID: <20150521101614.GA10889@gmail.com>:
> +The detail about '?' can be found in the comments within dumpstack.c:
> +::
>  
> -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.
> +    /*
> +     * 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.
> +     */
>  
> -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:
> +You can also get more info from Ingo's original emal [1]_

                                                   email
and end that sentence with a period ('.').

>  
> - - 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.
> +.. [1] https://lore.kernel.org/lkml/20150521101614.GA10889@gmail.com/

-- 
~Randy