redonkable
/
alistair23-linux
1
0
Fork 0
Code Releases Activity

Documentation: x86: convert orc-unwinder.txt to reST 

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>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
hifive-unleashed-5.2
Changbin Du 2019-05-08 23:21:32 +08:00 committed by Jonathan Corbet
parent 1cd7af509d
commit 9d12f58fe9
2 changed files with 16 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Documentation/x86/index.rst
View File

@ -14,6 +14,7 @@ x86-specific Documentation
kernel-stacks kernel-stacks
entry_64 entry_64
earlyprintk earlyprintk
orc-unwinder
zero-page zero-page
tlb tlb
mtrr mtrr

27
Documentation/x86/orc-unwinder.txt → Documentation/x86/orc-unwinder.rst
View File

@ -1,8 +1,11 @@
.. SPDX-License-Identifier: GPL-2.0
============
ORC unwinder ORC unwinder
============ ============
Overview Overview
-------- ========
The kernel CONFIG_UNWINDER_ORC option enables the ORC unwinder, which is The kernel CONFIG_UNWINDER_ORC option enables the ORC unwinder, which is
similar in concept to a DWARF unwinder. The difference is that the 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 ORC vs frame pointers
--------------------- =====================
With frame pointers enabled, GCC adds instrumentation code to every With frame pointers enabled, GCC adds instrumentation code to every
function in the kernel. The kernel's .text size increases by about function in the kernel. The kernel's .text size increases by about
3.2%, resulting in a broad kernel-wide slowdown. Measurements by Mel 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 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 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 vs DWARF
------------ ============
ORC debuginfo's advantage over DWARF itself is that it's much simpler. 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 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 The simpler debuginfo format also enables the unwinder to be much faster
than DWARF, which is important for perf and lockdep. In a basic 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 faster than an out-of-tree DWARF unwinder. (Note: That measurement was
taken before some performance tweaks were added, which doubled taken before some performance tweaks were added, which doubled
performance, so the speedup over DWARF may be closer to 40x.) 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 ORC unwind table generation
--------------------------- ===========================
The ORC data is generated by objtool. With the existing compile-time The ORC data is generated by objtool. With the existing compile-time
stack metadata validation feature, objtool already follows all code stack metadata validation feature, objtool already follows all code
@ -133,7 +136,7 @@ objtool follows GCC code quite well.
Unwinder implementation details Unwinder implementation details
------------------------------- ===============================
Objtool generates the ORC data by integrating with the compile-time Objtool generates the ORC data by integrating with the compile-time
stack metadata validation feature, which is described in detail in stack metadata validation feature, which is described in detail in
@ -154,7 +157,7 @@ subset of the table needs to be searched.
Etymology Etymology
--------- =========
Orcs, fearsome creatures of medieval folklore, are the Dwarves' natural Orcs, fearsome creatures of medieval folklore, are the Dwarves' natural
enemies. Similarly, the ORC unwinder was created in opposition to the 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 "Although Orcs rarely consider multiple solutions to a problem, they do
excel at getting things done because they are creatures of action, not 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 veracious ORC unwinder wastes no time or siloconic effort decoding
variable-length zero-extended unsigned-integer byte-coded variable-length zero-extended unsigned-integer byte-coded
state-machine-based debug information entries. state-machine-based debug information entries.
@ -174,6 +177,6 @@ brutal, unyielding efficiency.
ORC stands for Oops Rewind Capability. ORC stands for Oops Rewind Capability.
[1] https://lkml.kernel.org/r/20170602104048.jkkzssljsompjdwy@suse.de .. [1] https://lkml.kernel.org/r/20170602104048.jkkzssljsompjdwy@suse.de
[2] https://lkml.kernel.org/r/d2ca5435-6386-29b8-db87-7f227c2b713a@suse.cz .. [2] https://lkml.kernel.org/r/d2ca5435-6386-29b8-db87-7f227c2b713a@suse.cz
[3] http://dustin.wikidot.com/half-orcs-and-orcs .. [3] http://dustin.wikidot.com/half-orcs-and-orcs