1 .. SPDX-License-Identifier: GPL-2.0
2
3 ============
4 ORC unwinder
5 ============
6
7 Overview
8 ========
9
10 The kernel CONFIG_UNWINDER_ORC option enables
11 similar in concept to a DWARF unwinder. The d
12 format of the ORC data is much simpler than DW
13 the ORC unwinder to be much simpler and faster
14
15 The ORC data consists of unwind tables which a
16 They contain out-of-band data which is used by
17 unwinder. Objtool generates the ORC data by f
18 stack metadata validation (CONFIG_STACK_VALIDA
19 all the code paths of a .o file, it determines
20 stack state at each instruction address in the
21 information to the .orc_unwind and .orc_unwind
22
23 The per-object ORC sections are combined at li
24 post-processed at boot time. The unwinder use
25 correlate instruction addresses with their sta
26
27
28 ORC vs frame pointers
29 =====================
30
31 With frame pointers enabled, GCC adds instrume
32 function in the kernel. The kernel's .text si
33 3.2%, resulting in a broad kernel-wide slowdow
34 Gorman [1]_ have shown a slowdown of 5-10% for
35
36 In contrast, the ORC unwinder has no effect on
37 performance, because the debuginfo is out of b
38 frame pointers and enable the ORC unwinder, yo
39 improvement across the board, and still have r
40
41 Ingo Molnar says:
42
43 "Note that it's not just a performance impro
44 instruction cache locality improvement: 3.2%
45 directly transform into a similarly sized re
46 footprint. That can transform to even higher
47 whose cache locality is borderline."
48
49 Another benefit of ORC compared to frame point
50 reliably unwind across interrupts and exceptio
51 unwinds can sometimes skip the caller of the i
52 was a leaf function or if the interrupt hit be
53 saved.
54
55 The main disadvantage of the ORC unwinder comp
56 that it needs more memory to store the ORC unw
57 depending on the kernel config.
58
59
60 ORC vs DWARF
61 ============
62
63 ORC debuginfo's advantage over DWARF itself is
64 It gets rid of the complex DWARF CFI state mac
65 the tracking of unnecessary registers. This a
66 much simpler, meaning fewer bugs, which is esp
67 mission critical oops code.
68
69 The simpler debuginfo format also enables the
70 than DWARF, which is important for perf and lo
71 performance test by Jiri Slaby [2]_, the ORC u
72 faster than an out-of-tree DWARF unwinder. (N
73 taken before some performance tweaks were adde
74 performance, so the speedup over DWARF may be
75
76 The ORC data format does have a few downsides
77 unwind tables take up ~50% more RAM (+1.3MB on
78 than DWARF-based eh_frame tables.
79
80 Another potential downside is that, as GCC evo
81 that the ORC data may end up being *too* simpl
82 the stack for certain optimizations. But IMO
83 GCC saves the frame pointer for any unusual st
84 so I suspect we'll really only ever need to ke
85 pointer and the frame pointer between call fra
86 end up having to track all the registers DWARF
87 still be able to control the format, e.g. no c
88
89
90 ORC unwind table generation
91 ===========================
92
93 The ORC data is generated by objtool. With th
94 stack metadata validation feature, objtool alr
95 paths, and so it already has all the informati
96 generate ORC data from scratch. So it's an ea
97 validation to ORC data generation.
98
99 It should be possible to instead generate the
100 tool which converts DWARF to ORC data. Howeve
101 be incomplete due to the kernel's extensive us
102 special sections like exception tables.
103
104 That could be rectified by manually annotating
105 using GNU assembler .cfi annotations in .S fil
106 annotations for inline asm in .c files. But a
107 in the past and were found to be unmaintainabl
108 incorrect/incomplete and made the code harder
109 And based on looking at glibc code, annotating
110 might be even worse.
111
112 Objtool still needs a few annotations, but onl
113 unusual things to the stack like entry code.
114 annotations are needed than what DWARF would n
115 maintainable than DWARF CFI annotations.
116
117 So the advantages of using objtool to generate
118 gives more accurate debuginfo, with very few a
119 insulates the kernel from toolchain bugs which
120 deal with in the kernel since we often have to
121 older versions of the toolchain for years.
122
123 The downside is that the unwinder now becomes
124 ability to reverse engineer GCC code flow. If
125 too complicated for objtool to follow, the ORC
126 stop working or become incomplete. (It's wort
127 already has such a dependency on objtool's abi
128 flow.)
129
130 If newer versions of GCC come up with some opt
131 objtool, we may need to revisit the current im
132 possible solutions would be asking GCC to make
133 palatable, or having objtool use DWARF as an a
134 creating a GCC plugin to assist objtool with i
135 objtool follows GCC code quite well.
136
137
138 Unwinder implementation details
139 ===============================
140
141 Objtool generates the ORC data by integrating
142 stack metadata validation feature, which is de
143 tools/objtool/Documentation/objtool.txt. Afte
144 the code paths of a .o file, it creates an arr
145 and a parallel array of instruction addresses
146 structs, and writes them to the .orc_unwind an
147 respectively.
148
149 The ORC data is split into the two arrays for
150 make the searchable part of the data (.orc_unw
151 arrays are sorted in parallel at boot time.
152
153 Performance is further improved by the use of
154 is created at runtime. The fast lookup table
155 with a range of indices for the .orc_unwind ta
156 subset of the table needs to be searched.
157
158
159 Etymology
160 =========
161
162 Orcs, fearsome creatures of medieval folklore,
163 enemies. Similarly, the ORC unwinder was crea
164 complexity and slowness of DWARF.
165
166 "Although Orcs rarely consider multiple soluti
167 excel at getting things done because they are
168 thought." [3]_ Similarly, unlike the esoteric
169 veracious ORC unwinder wastes no time or siloc
170 variable-length zero-extended unsigned-integer
171 state-machine-based debug information entries.
172
173 Similar to how Orcs frequently unravel the wel
174 their adversaries, the ORC unwinder frequently
175 brutal, unyielding efficiency.
176
177 ORC stands for Oops Rewind Capability.
178
179
180 .. [1] https://lore.kernel.org/r/2017060210404
181 .. [2] https://lore.kernel.org/r/d2ca5435-6386
182 .. [3] http://dustin.wikidot.com/half-orcs-and
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.