lkml.org 
[lkml]   [2019]   [May]   [8]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH v4 18/27] Documentation: x86: convert orc-unwinder.txt to reST
    Date
    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 6e3c887a0c3b..453557097743 100644
    --- a/Documentation/x86/index.rst
    +++ b/Documentation/x86/index.rst
    @@ -14,6 +14,7 @@ x86-specific Documentation
    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
    --
    2.20.1
    \
     
     \ /
      Last update: 2019-05-08 17:25    [W:2.553 / U:0.316 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site