Re: [PATCH 18/27] Documentation: x86: convert orc-unwinder.txt to reST

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

Em Fri, 26 Apr 2019 23:31:41 +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>

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

> ---
>  Documentation/x86/index.rst                   |  1 +
>  .../{orc-unwinder.txt => orc-unwinder.rst}    | 27 ++++++++++---------
>  2 files changed, 16 insertions(+), 12 deletions(-)
>  rename Documentation/x86/{orc-unwinder.txt => orc-unwinder.rst} (93%)
> 
> diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
> index 4e9fa2b046df..c41c17906b6d 100644
> --- a/Documentation/x86/index.rst
> +++ b/Documentation/x86/index.rst
> @@ -14,6 +14,7 @@ Linux x86 Support
>     kernel-stacks
>     entry_64
>     earlyprintk
> +   orc-unwinder
>     zero-page
>     tlb
>     mtrr
> diff --git a/Documentation/x86/orc-unwinder.txt b/Documentation/x86/orc-unwinder.rst
> similarity index 93%
> rename from Documentation/x86/orc-unwinder.txt
> rename to Documentation/x86/orc-unwinder.rst
> index cd4b29be29af..d811576c1f3e 100644
> --- a/Documentation/x86/orc-unwinder.txt
> +++ b/Documentation/x86/orc-unwinder.rst
> @@ -1,8 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +============
>  ORC unwinder
>  ============
>  
>  Overview
> ---------
> +========
>  
>  The kernel CONFIG_UNWINDER_ORC option enables the ORC unwinder, which is
>  similar in concept to a DWARF unwinder.  The difference is that the
> @@ -23,12 +26,12 @@ correlate instruction addresses with their stack states at run time.
>  
>  
>  ORC vs frame pointers
> ----------------------
> +=====================
>  
>  With frame pointers enabled, GCC adds instrumentation code to every
>  function in the kernel.  The kernel's .text size increases by about
>  3.2%, resulting in a broad kernel-wide slowdown.  Measurements by Mel
> -Gorman [1] have shown a slowdown of 5-10% for some workloads.
> +Gorman [1]_ have shown a slowdown of 5-10% for some workloads.
>  
>  In contrast, the ORC unwinder has no effect on text size or runtime
>  performance, because the debuginfo is out of band.  So if you disable
> @@ -55,7 +58,7 @@ depending on the kernel config.
>  
>  
>  ORC vs DWARF
> -------------
> +============
>  
>  ORC debuginfo's advantage over DWARF itself is that it's much simpler.
>  It gets rid of the complex DWARF CFI state machine and also gets rid of
> @@ -65,7 +68,7 @@ mission critical oops code.
>  
>  The simpler debuginfo format also enables the unwinder to be much faster
>  than DWARF, which is important for perf and lockdep.  In a basic
> -performance test by Jiri Slaby [2], the ORC unwinder was about 20x
> +performance test by Jiri Slaby [2]_, the ORC unwinder was about 20x
>  faster than an out-of-tree DWARF unwinder.  (Note: That measurement was
>  taken before some performance tweaks were added, which doubled
>  performance, so the speedup over DWARF may be closer to 40x.)
> @@ -85,7 +88,7 @@ still be able to control the format, e.g. no complex state machines.
>  
>  
>  ORC unwind table generation
> ----------------------------
> +===========================
>  
>  The ORC data is generated by objtool.  With the existing compile-time
>  stack metadata validation feature, objtool already follows all code
> @@ -133,7 +136,7 @@ objtool follows GCC code quite well.
>  
>  
>  Unwinder implementation details
> --------------------------------
> +===============================
>  
>  Objtool generates the ORC data by integrating with the compile-time
>  stack metadata validation feature, which is described in detail in
> @@ -154,7 +157,7 @@ subset of the table needs to be searched.
>  
>  
>  Etymology
> ----------
> +=========
>  
>  Orcs, fearsome creatures of medieval folklore, are the Dwarves' natural
>  enemies.  Similarly, the ORC unwinder was created in opposition to the
> @@ -162,7 +165,7 @@ complexity and slowness of DWARF.
>  
>  "Although Orcs rarely consider multiple solutions to a problem, they do
>  excel at getting things done because they are creatures of action, not
> -thought." [3]  Similarly, unlike the esoteric DWARF unwinder, the
> +thought." [3]_  Similarly, unlike the esoteric DWARF unwinder, the
>  veracious ORC unwinder wastes no time or siloconic effort decoding
>  variable-length zero-extended unsigned-integer byte-coded
>  state-machine-based debug information entries.
> @@ -174,6 +177,6 @@ brutal, unyielding efficiency.
>  ORC stands for Oops Rewind Capability.
>  
>  
> -[1] https://lkml.kernel.org/r/20170602104048.jkkzssljsompjdwy@suse.de
> -[2] https://lkml.kernel.org/r/d2ca5435-6386-29b8-db87-7f227c2b713a@suse.cz
> -[3] http://dustin.wikidot.com/half-orcs-and-orcs
> +.. [1] https://lkml.kernel.org/r/20170602104048.jkkzssljsompjdwy@suse.de
> +.. [2] https://lkml.kernel.org/r/d2ca5435-6386-29b8-db87-7f227c2b713a@suse.cz
> +.. [3] http://dustin.wikidot.com/half-orcs-and-orcs



Thanks,
Mauro