From: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
To: Changbin Du <changbin.du@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>,
tglx@linutronix.de, mingo@redhat.com, bp@alien8.de,
x86@kernel.org, linux-doc@vger.kernel.org,
linux-kernel@vger.kernel.org
Subject: Re: [PATCH 18/27] Documentation: x86: convert orc-unwinder.txt to reST
Date: Sat, 27 Apr 2019 15:16:28 -0300 [thread overview]
Message-ID: <20190427151628.219bdf08@coco.lan> (raw)
In-Reply-To: <20190426153150.21228-19-changbin.du@gmail.com>
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
next prev parent reply other threads:[~2019-04-27 18:16 UTC|newest]
Thread overview: 68+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-04-26 15:31 [PATCH 00/27] Include linux x86 docs into Sphinx TOC tree Changbin Du
2019-04-26 15:31 ` [PATCH 01/27] Documentation: add Linux x86 docs to " Changbin Du
2019-04-26 16:16 ` Borislav Petkov
2019-04-27 2:43 ` Changbin Du
2019-04-26 15:31 ` [PATCH 02/27] Documentation: x86: convert boot.txt to reST Changbin Du
2019-04-27 14:31 ` Mauro Carvalho Chehab
2019-05-02 6:59 ` Changbin Du
2019-04-26 15:31 ` [PATCH 03/27] Documentation: x86: convert topology.txt " Changbin Du
2019-04-27 14:41 ` Mauro Carvalho Chehab
2019-04-26 15:31 ` [PATCH 04/27] Documentation: x86: convert exception-tables.txt " Changbin Du
2019-04-27 14:48 ` Mauro Carvalho Chehab
2019-05-02 3:19 ` Changbin Du
2019-04-26 15:31 ` [PATCH 05/27] Documentation: x86: convert kernel-stacks " Changbin Du
2019-04-27 14:50 ` Mauro Carvalho Chehab
2019-04-26 15:31 ` [PATCH 06/27] Documentation: x86: convert entry_64.txt " Changbin Du
2019-04-27 14:52 ` Mauro Carvalho Chehab
2019-04-26 15:31 ` [PATCH 07/27] Documentation: x86: convert earlyprintk.txt " Changbin Du
2019-04-27 17:17 ` Mauro Carvalho Chehab
2019-05-02 3:27 ` Changbin Du
2019-04-26 15:31 ` [PATCH 08/27] Documentation: x86: convert zero-page.txt " Changbin Du
2019-04-27 17:19 ` Mauro Carvalho Chehab
2019-04-26 15:31 ` [PATCH 09/27] Documentation: x86: convert tlb.txt " Changbin Du
2019-04-27 17:21 ` Mauro Carvalho Chehab
2019-04-26 15:31 ` [PATCH 10/27] Documentation: x86: convert mtrr.txt " Changbin Du
2019-04-27 17:32 ` Mauro Carvalho Chehab
2019-04-27 18:10 ` Mauro Carvalho Chehab
2019-05-02 5:03 ` Changbin Du
2019-04-26 15:31 ` [PATCH 11/27] Documentation: x86: convert pat.txt " Changbin Du
2019-04-27 17:51 ` Mauro Carvalho Chehab
2019-05-02 5:25 ` Changbin Du
2019-04-26 15:31 ` [PATCH 12/27] Documentation: x86: convert protection-keys.txt " Changbin Du
2019-04-27 17:53 ` Mauro Carvalho Chehab
2019-04-26 15:31 ` [PATCH 13/27] Documentation: x86: convert intel_mpx.txt " Changbin Du
2019-04-27 17:54 ` Mauro Carvalho Chehab
2019-04-26 15:31 ` [PATCH 14/27] Documentation: x86: convert amd-memory-encryption.txt " Changbin Du
2019-04-27 17:55 ` Mauro Carvalho Chehab
2019-04-26 15:31 ` [PATCH 15/27] Documentation: x86: convert pti.txt " Changbin Du
2019-04-27 17:57 ` Mauro Carvalho Chehab
2019-04-26 15:31 ` [PATCH 16/27] Documentation: x86: convert microcode.txt " Changbin Du
2019-04-27 17:58 ` Mauro Carvalho Chehab
2019-04-26 15:31 ` [PATCH 17/27] Documentation: x86: convert resctrl_ui.txt " Changbin Du
2019-04-27 18:09 ` Mauro Carvalho Chehab
2019-05-02 5:37 ` Changbin Du
2019-04-26 15:31 ` [PATCH 18/27] Documentation: x86: convert orc-unwinder.txt " Changbin Du
2019-04-27 18:16 ` Mauro Carvalho Chehab [this message]
2019-04-26 15:31 ` [PATCH 19/27] Documentation: x86: convert usb-legacy-support.txt " Changbin Du
2019-04-27 18:20 ` Mauro Carvalho Chehab
2019-04-26 15:31 ` [PATCH 20/27] Documentation: x86: convert i386/IO-APIC.txt " Changbin Du
2019-04-27 18:24 ` Mauro Carvalho Chehab
2019-05-02 5:42 ` Changbin Du
2019-04-26 15:31 ` [PATCH 21/27] Documentation: x86: convert x86_64/boot-options.txt " Changbin Du
2019-04-27 18:30 ` Mauro Carvalho Chehab
2019-05-02 5:49 ` Changbin Du
2019-04-26 15:31 ` [PATCH 22/27] Documentation: x86: convert x86_64/uefi.txt " Changbin Du
2019-04-27 18:31 ` Mauro Carvalho Chehab
2019-04-26 15:31 ` [PATCH 23/27] Documentation: x86: convert x86_64/mm.txt " Changbin Du
2019-04-27 18:35 ` Mauro Carvalho Chehab
2019-04-26 15:31 ` [PATCH 24/27] Documentation: x86: convert x86_64/5level-paging.txt " Changbin Du
2019-04-27 18:36 ` Mauro Carvalho Chehab
2019-04-26 15:31 ` [PATCH 25/27] Documentation: x86: convert x86_64/fake-numa-for-cpusets " Changbin Du
2019-04-27 18:38 ` Mauro Carvalho Chehab
2019-04-26 15:31 ` [PATCH 26/27] Documentation: x86: convert x86_64/cpu-hotplug-spec " Changbin Du
2019-04-27 18:40 ` Mauro Carvalho Chehab
2019-04-26 15:31 ` [PATCH 27/27] Documentation: x86: convert x86_64/machinecheck " Changbin Du
2019-04-27 18:42 ` Mauro Carvalho Chehab
2019-04-26 15:39 ` [PATCH 00/27] Include linux x86 docs into Sphinx TOC tree Mauro Carvalho Chehab
2019-04-27 2:47 ` Changbin Du
2019-04-27 9:54 ` Mauro Carvalho Chehab
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190427151628.219bdf08@coco.lan \
--to=mchehab+samsung@kernel.org \
--cc=bp@alien8.de \
--cc=changbin.du@gmail.com \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mingo@redhat.com \
--cc=tglx@linutronix.de \
--cc=x86@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).