Re: [PATCH 05/27] Documentation: x86: convert kernel-stacks to reST

[Mauro Carvalho Chehab <mchehab+samsung@kernel.org>]

Em Fri, 26 Apr 2019 23:31:28 +0800
Changbin Du <changbin.du@gmail.com> escreveu:

> This converts the plain text documentation to reStructuredText format and
> add it to Sphinx TOC tree. No essential content change.
> 
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
> ---
>  Documentation/x86/index.rst                   |  1 +
>  .../x86/{kernel-stacks => kernel-stacks.rst}  | 20 ++++++++++++-------
>  2 files changed, 14 insertions(+), 7 deletions(-)
>  rename Documentation/x86/{kernel-stacks => kernel-stacks.rst} (92%)
> 
> diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
> index c0bfd0bd6000..489f4f4179c4 100644
> --- a/Documentation/x86/index.rst
> +++ b/Documentation/x86/index.rst
> @@ -11,3 +11,4 @@ Linux x86 Support
>     boot
>     topology
>     exception-tables
> +   kernel-stacks
> diff --git a/Documentation/x86/kernel-stacks b/Documentation/x86/kernel-stacks.rst
> similarity index 92%
> rename from Documentation/x86/kernel-stacks
> rename to Documentation/x86/kernel-stacks.rst
> index 9a0aa4d3a866..3e6bf5940db0 100644
> --- a/Documentation/x86/kernel-stacks
> +++ b/Documentation/x86/kernel-stacks.rst
> @@ -1,5 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=============
> +Kernel Stacks
> +=============
> +
>  Kernel stacks on x86-64 bit
> ----------------------------
> +===========================
>  
>  Most of the text from Keith Owens, hacked by AK
>  
> @@ -57,7 +63,7 @@ IST events with the same code to be nested.  However in most cases, the
>  stack size allocated to an IST assumes no nesting for the same code.
>  If that assumption is ever broken then the stacks will become corrupt.
>  
> -The currently assigned IST stacks are :-
> +The currently assigned IST stacks are :

This is a matter of style, but I would remove the space before ':', as this
is a much more common pattern.

In any case:

Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

>  
>  * DOUBLEFAULT_STACK.  EXCEPTION_STKSZ (PAGE_SIZE).
>  
> @@ -98,7 +104,7 @@ For more details see the Intel IA32 or AMD AMD64 architecture manuals.
>  
>  
>  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
> @@ -108,7 +114,7 @@ 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) [*], from stack top to stack bottom, and print out
> +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
> @@ -136,6 +142,6 @@ 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.
>  
> -[*] 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] 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.



Thanks,
Mauro