From: Changbin Du <changbin.du@gmail.com>
To: corbet@lwn.net, tglx@linutronix.de, mingo@redhat.com, bp@alien8.de
Cc: x86@kernel.org, linux-doc@vger.kernel.org,
linux-kernel@vger.kernel.org, Changbin Du <changbin.du@gmail.com>,
Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Subject: [PATCH v2 18/27] Documentation: x86: convert orc-unwinder.txt to reST
Date: Thu, 2 May 2019 15:06:24 +0800 [thread overview]
Message-ID: <20190502070633.9809-19-changbin.du@gmail.com> (raw)
In-Reply-To: <20190502070633.9809-1-changbin.du@gmail.com>
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
next prev parent reply other threads:[~2019-05-02 7:11 UTC|newest]
Thread overview: 33+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-05-02 7:06 [PATCH v2 00/27] Include linux x86 docs into Sphinx TOC tree Changbin Du
2019-05-02 7:06 ` [PATCH v2 01/27] Documentation: add Linux x86 docs to " Changbin Du
2019-05-02 7:06 ` [PATCH v2 02/27] Documentation: x86: convert boot.txt to reST Changbin Du
2019-05-02 7:06 ` [PATCH v2 03/27] Documentation: x86: convert topology.txt " Changbin Du
2019-05-02 7:06 ` [PATCH v2 04/27] Documentation: x86: convert exception-tables.txt " Changbin Du
2019-05-02 7:06 ` [PATCH v2 05/27] Documentation: x86: convert kernel-stacks " Changbin Du
2019-05-02 7:06 ` [PATCH v2 06/27] Documentation: x86: convert entry_64.txt " Changbin Du
2019-05-02 7:06 ` [PATCH v2 07/27] Documentation: x86: convert earlyprintk.txt " Changbin Du
2019-05-02 7:06 ` [PATCH v2 08/27] Documentation: x86: convert zero-page.txt " Changbin Du
2019-05-02 7:06 ` [PATCH v2 09/27] Documentation: x86: convert tlb.txt " Changbin Du
2019-05-02 7:06 ` [PATCH v2 10/27] Documentation: x86: convert mtrr.txt " Changbin Du
2019-05-02 7:06 ` [PATCH v2 11/27] Documentation: x86: convert pat.txt " Changbin Du
2019-05-02 7:06 ` [PATCH v2 12/27] Documentation: x86: convert protection-keys.txt " Changbin Du
2019-05-02 7:06 ` [PATCH v2 13/27] Documentation: x86: convert intel_mpx.txt " Changbin Du
2019-05-02 7:06 ` [PATCH v2 14/27] Documentation: x86: convert amd-memory-encryption.txt " Changbin Du
2019-05-02 7:06 ` [PATCH v2 15/27] Documentation: x86: convert pti.txt " Changbin Du
2019-05-02 7:06 ` [PATCH v2 16/27] Documentation: x86: convert microcode.txt " Changbin Du
2019-05-02 7:06 ` [PATCH v2 17/27] Documentation: x86: convert resctrl_ui.txt " Changbin Du
2019-05-02 7:06 ` Changbin Du [this message]
2019-05-02 7:06 ` [PATCH v2 19/27] Documentation: x86: convert usb-legacy-support.txt " Changbin Du
2019-05-02 7:06 ` [PATCH v2 20/27] Documentation: x86: convert i386/IO-APIC.txt " Changbin Du
2019-05-02 7:06 ` [PATCH v2 21/27] Documentation: x86: convert x86_64/boot-options.txt " Changbin Du
2019-05-02 7:06 ` [PATCH v2 22/27] Documentation: x86: convert x86_64/uefi.txt " Changbin Du
2019-05-02 7:06 ` [PATCH v2 23/27] Documentation: x86: convert x86_64/mm.txt " Changbin Du
2019-05-02 7:06 ` [PATCH v2 24/27] Documentation: x86: convert x86_64/5level-paging.txt " Changbin Du
2019-05-02 7:06 ` [PATCH v2 25/27] Documentation: x86: convert x86_64/fake-numa-for-cpusets " Changbin Du
2019-05-02 7:06 ` [PATCH v2 26/27] Documentation: x86: convert x86_64/cpu-hotplug-spec " Changbin Du
2019-05-02 7:06 ` [PATCH v2 27/27] Documentation: x86: convert x86_64/machinecheck " Changbin Du
2019-05-03 12:43 ` [PATCH v2 00/27] Include linux x86 docs into Sphinx TOC tree Jonathan Corbet
2019-05-03 13:09 ` Borislav Petkov
2019-05-03 17:44 ` Ingo Molnar
2019-05-05 19:02 ` Jonathan Corbet
2019-05-06 0:06 ` Changbin Du
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=20190502070633.9809-19-changbin.du@gmail.com \
--to=changbin.du@gmail.com \
--cc=bp@alien8.de \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mchehab+samsung@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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.