Commit 9d12f58f authored by Changbin Du's avatar Changbin Du Committed by Jonathan Corbet
Browse files

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: default avatarChangbin Du <changbin.du@gmail.com>
Reviewed-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 1cd7af50

Documentation/x86/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -14,6 +14,7 @@ x86-specific Documentation 
   kernel-stacks

   entry_64

   earlyprintk

   orc-unwinder

   zero-page

   tlb

   mtrr

Documentation/x86/orc-unwinder.txt→Documentation/x86/orc-unwinder.rst

+15 −12
Original line number Diff line number Diff line 
.. 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