]>
Commit | Line | Data |
---|---|---|
442f04c3 JP |
1 | Compile-time stack metadata validation |
2 | ====================================== | |
3 | ||
4 | ||
5 | Overview | |
6 | -------- | |
7 | ||
8 | The kernel CONFIG_STACK_VALIDATION option enables a host tool named | |
9 | objtool which runs at compile time. It has a "check" subcommand which | |
10 | analyzes every .o file and ensures the validity of its stack metadata. | |
11 | It enforces a set of rules on asm code and C inline assembly code so | |
12 | that stack traces can be reliable. | |
13 | ||
442f04c3 JP |
14 | For each function, it recursively follows all possible code paths and |
15 | validates the correct frame pointer state at each instruction. | |
16 | ||
17 | It also follows code paths involving special sections, like | |
18 | .altinstructions, __jump_table, and __ex_table, which can add | |
19 | alternative execution paths to a given instruction (or set of | |
20 | instructions). Similarly, it knows how to follow switch statements, for | |
21 | which gcc sometimes uses jump tables. | |
22 | ||
627fce14 JP |
23 | (Objtool also has an 'orc generate' subcommand which generates debuginfo |
24 | for the ORC unwinder. See Documentation/x86/orc-unwinder.txt in the | |
25 | kernel tree for more details.) | |
26 | ||
442f04c3 JP |
27 | |
28 | Why do we need stack metadata validation? | |
29 | ----------------------------------------- | |
30 | ||
31 | Here are some of the benefits of validating stack metadata: | |
32 | ||
33 | a) More reliable stack traces for frame pointer enabled kernels | |
34 | ||
35 | Frame pointers are used for debugging purposes. They allow runtime | |
36 | code and debug tools to be able to walk the stack to determine the | |
37 | chain of function call sites that led to the currently executing | |
38 | code. | |
39 | ||
40 | For some architectures, frame pointers are enabled by | |
41 | CONFIG_FRAME_POINTER. For some other architectures they may be | |
42 | required by the ABI (sometimes referred to as "backchain pointers"). | |
43 | ||
44 | For C code, gcc automatically generates instructions for setting up | |
45 | frame pointers when the -fno-omit-frame-pointer option is used. | |
46 | ||
47 | But for asm code, the frame setup instructions have to be written by | |
48 | hand, which most people don't do. So the end result is that | |
49 | CONFIG_FRAME_POINTER is honored for C code but not for most asm code. | |
50 | ||
51 | For stack traces based on frame pointers to be reliable, all | |
52 | functions which call other functions must first create a stack frame | |
53 | and update the frame pointer. If a first function doesn't properly | |
54 | create a stack frame before calling a second function, the *caller* | |
55 | of the first function will be skipped on the stack trace. | |
56 | ||
57 | For example, consider the following example backtrace with frame | |
58 | pointers enabled: | |
59 | ||
60 | [<ffffffff81812584>] dump_stack+0x4b/0x63 | |
61 | [<ffffffff812d6dc2>] cmdline_proc_show+0x12/0x30 | |
62 | [<ffffffff8127f568>] seq_read+0x108/0x3e0 | |
63 | [<ffffffff812cce62>] proc_reg_read+0x42/0x70 | |
64 | [<ffffffff81256197>] __vfs_read+0x37/0x100 | |
65 | [<ffffffff81256b16>] vfs_read+0x86/0x130 | |
66 | [<ffffffff81257898>] SyS_read+0x58/0xd0 | |
67 | [<ffffffff8181c1f2>] entry_SYSCALL_64_fastpath+0x12/0x76 | |
68 | ||
69 | It correctly shows that the caller of cmdline_proc_show() is | |
70 | seq_read(). | |
71 | ||
72 | If we remove the frame pointer logic from cmdline_proc_show() by | |
73 | replacing the frame pointer related instructions with nops, here's | |
74 | what it looks like instead: | |
75 | ||
76 | [<ffffffff81812584>] dump_stack+0x4b/0x63 | |
77 | [<ffffffff812d6dc2>] cmdline_proc_show+0x12/0x30 | |
78 | [<ffffffff812cce62>] proc_reg_read+0x42/0x70 | |
79 | [<ffffffff81256197>] __vfs_read+0x37/0x100 | |
80 | [<ffffffff81256b16>] vfs_read+0x86/0x130 | |
81 | [<ffffffff81257898>] SyS_read+0x58/0xd0 | |
82 | [<ffffffff8181c1f2>] entry_SYSCALL_64_fastpath+0x12/0x76 | |
83 | ||
84 | Notice that cmdline_proc_show()'s caller, seq_read(), has been | |
85 | skipped. Instead the stack trace seems to show that | |
86 | cmdline_proc_show() was called by proc_reg_read(). | |
87 | ||
88 | The benefit of objtool here is that because it ensures that *all* | |
89 | functions honor CONFIG_FRAME_POINTER, no functions will ever[*] be | |
90 | skipped on a stack trace. | |
91 | ||
92 | [*] unless an interrupt or exception has occurred at the very | |
93 | beginning of a function before the stack frame has been created, | |
94 | or at the very end of the function after the stack frame has been | |
95 | destroyed. This is an inherent limitation of frame pointers. | |
96 | ||
627fce14 | 97 | b) ORC (Oops Rewind Capability) unwind table generation |
442f04c3 | 98 | |
627fce14 JP |
99 | An alternative to frame pointers and DWARF, ORC unwind data can be |
100 | used to walk the stack. Unlike frame pointers, ORC data is out of | |
101 | band. So it doesn't affect runtime performance and it can be | |
102 | reliable even when interrupts or exceptions are involved. | |
442f04c3 | 103 | |
627fce14 | 104 | For more details, see Documentation/x86/orc-unwinder.txt. |
442f04c3 JP |
105 | |
106 | c) Higher live patching compatibility rate | |
107 | ||
baa41469 JP |
108 | Livepatch has an optional "consistency model", which is needed for |
109 | more complex patches. In order for the consistency model to work, | |
110 | stack traces need to be reliable (or an unreliable condition needs to | |
111 | be detectable). Objtool makes that possible. | |
442f04c3 | 112 | |
baa41469 JP |
113 | For more details, see the livepatch documentation in the Linux kernel |
114 | source tree at Documentation/livepatch/livepatch.txt. | |
442f04c3 JP |
115 | |
116 | Rules | |
117 | ----- | |
118 | ||
119 | To achieve the validation, objtool enforces the following rules: | |
120 | ||
121 | 1. Each callable function must be annotated as such with the ELF | |
122 | function type. In asm code, this is typically done using the | |
123 | ENTRY/ENDPROC macros. If objtool finds a return instruction | |
124 | outside of a function, it flags an error since that usually indicates | |
125 | callable code which should be annotated accordingly. | |
126 | ||
127 | This rule is needed so that objtool can properly identify each | |
128 | callable function in order to analyze its stack metadata. | |
129 | ||
130 | 2. Conversely, each section of code which is *not* callable should *not* | |
131 | be annotated as an ELF function. The ENDPROC macro shouldn't be used | |
132 | in this case. | |
133 | ||
134 | This rule is needed so that objtool can ignore non-callable code. | |
135 | Such code doesn't have to follow any of the other rules. | |
136 | ||
137 | 3. Each callable function which calls another function must have the | |
138 | correct frame pointer logic, if required by CONFIG_FRAME_POINTER or | |
139 | the architecture's back chain rules. This can by done in asm code | |
140 | with the FRAME_BEGIN/FRAME_END macros. | |
141 | ||
142 | This rule ensures that frame pointer based stack traces will work as | |
143 | designed. If function A doesn't create a stack frame before calling | |
144 | function B, the _caller_ of function A will be skipped on the stack | |
145 | trace. | |
146 | ||
147 | 4. Dynamic jumps and jumps to undefined symbols are only allowed if: | |
148 | ||
149 | a) the jump is part of a switch statement; or | |
150 | ||
151 | b) the jump matches sibling call semantics and the frame pointer has | |
152 | the same value it had on function entry. | |
153 | ||
154 | This rule is needed so that objtool can reliably analyze all of a | |
155 | function's code paths. If a function jumps to code in another file, | |
156 | and it's not a sibling call, objtool has no way to follow the jump | |
157 | because it only analyzes a single file at a time. | |
158 | ||
159 | 5. A callable function may not execute kernel entry/exit instructions. | |
160 | The only code which needs such instructions is kernel entry code, | |
161 | which shouldn't be be in callable functions anyway. | |
162 | ||
163 | This rule is just a sanity check to ensure that callable functions | |
164 | return normally. | |
165 | ||
166 | ||
baa41469 JP |
167 | Objtool warnings |
168 | ---------------- | |
442f04c3 | 169 | |
baa41469 JP |
170 | For asm files, if you're getting an error which doesn't make sense, |
171 | first make sure that the affected code follows the above rules. | |
172 | ||
173 | For C files, the common culprits are inline asm statements and calls to | |
174 | "noreturn" functions. See below for more details. | |
175 | ||
176 | Another possible cause for errors in C code is if the Makefile removes | |
177 | -fno-omit-frame-pointer or adds -fomit-frame-pointer to the gcc options. | |
442f04c3 JP |
178 | |
179 | Here are some examples of common warnings reported by objtool, what | |
180 | they mean, and suggestions for how to fix them. | |
181 | ||
182 | ||
baa41469 | 183 | 1. file.o: warning: objtool: func()+0x128: call without frame pointer save/setup |
442f04c3 JP |
184 | |
185 | The func() function made a function call without first saving and/or | |
baa41469 | 186 | updating the frame pointer, and CONFIG_FRAME_POINTER is enabled. |
442f04c3 | 187 | |
baa41469 JP |
188 | If the error is for an asm file, and func() is indeed a callable |
189 | function, add proper frame pointer logic using the FRAME_BEGIN and | |
190 | FRAME_END macros. Otherwise, if it's not a callable function, remove | |
191 | its ELF function annotation by changing ENDPROC to END, and instead | |
627fce14 | 192 | use the manual unwind hint macros in asm/unwind_hints.h. |
442f04c3 | 193 | |
baa41469 JP |
194 | If it's a GCC-compiled .c file, the error may be because the function |
195 | uses an inline asm() statement which has a "call" instruction. An | |
196 | asm() statement with a call instruction must declare the use of the | |
197 | stack pointer in its output operand. For example, on x86_64: | |
442f04c3 | 198 | |
baa41469 JP |
199 | register void *__sp asm("rsp"); |
200 | asm volatile("call func" : "+r" (__sp)); | |
442f04c3 | 201 | |
baa41469 | 202 | Otherwise the stack frame may not get created before the call. |
442f04c3 | 203 | |
442f04c3 | 204 | |
baa41469 | 205 | 2. file.o: warning: objtool: .text+0x53: unreachable instruction |
442f04c3 | 206 | |
baa41469 | 207 | Objtool couldn't find a code path to reach the instruction. |
442f04c3 | 208 | |
baa41469 JP |
209 | If the error is for an asm file, and the instruction is inside (or |
210 | reachable from) a callable function, the function should be annotated | |
211 | with the ENTRY/ENDPROC macros (ENDPROC is the important one). | |
627fce14 JP |
212 | Otherwise, the code should probably be annotated with the unwind hint |
213 | macros in asm/unwind_hints.h so objtool and the unwinder can know the | |
baa41469 | 214 | stack state associated with the code. |
442f04c3 | 215 | |
baa41469 JP |
216 | If you're 100% sure the code won't affect stack traces, or if you're |
217 | a just a bad person, you can tell objtool to ignore it. See the | |
218 | "Adding exceptions" section below. | |
442f04c3 JP |
219 | |
220 | If it's not actually in a callable function (e.g. kernel entry code), | |
221 | change ENDPROC to END. | |
222 | ||
223 | ||
baa41469 | 224 | 4. file.o: warning: objtool: func(): can't find starting instruction |
442f04c3 | 225 | or |
baa41469 | 226 | file.o: warning: objtool: func()+0x11dd: can't decode instruction |
442f04c3 | 227 | |
baa41469 | 228 | Does the file have data in a text section? If so, that can confuse |
442f04c3 JP |
229 | objtool's instruction decoder. Move the data to a more appropriate |
230 | section like .data or .rodata. | |
231 | ||
232 | ||
baa41469 | 233 | 5. file.o: warning: objtool: func()+0x6: unsupported instruction in callable function |
442f04c3 | 234 | |
baa41469 JP |
235 | This is a kernel entry/exit instruction like sysenter or iret. Such |
236 | instructions aren't allowed in a callable function, and are most | |
237 | likely part of the kernel entry code. They should usually not have | |
238 | the callable function annotation (ENDPROC) and should always be | |
627fce14 | 239 | annotated with the unwind hint macros in asm/unwind_hints.h. |
442f04c3 JP |
240 | |
241 | ||
baa41469 | 242 | 6. file.o: warning: objtool: func()+0x26: sibling call from callable instruction with modified stack frame |
442f04c3 | 243 | |
baa41469 | 244 | This is a dynamic jump or a jump to an undefined symbol. Objtool |
442f04c3 JP |
245 | assumed it's a sibling call and detected that the frame pointer |
246 | wasn't first restored to its original state. | |
247 | ||
248 | If it's not really a sibling call, you may need to move the | |
249 | destination code to the local file. | |
250 | ||
251 | If the instruction is not actually in a callable function (e.g. | |
baa41469 | 252 | kernel entry code), change ENDPROC to END and annotate manually with |
627fce14 | 253 | the unwind hint macros in asm/unwind_hints.h. |
442f04c3 JP |
254 | |
255 | ||
baa41469 | 256 | 7. file: warning: objtool: func()+0x5c: stack state mismatch |
442f04c3 JP |
257 | |
258 | The instruction's frame pointer state is inconsistent, depending on | |
259 | which execution path was taken to reach the instruction. | |
260 | ||
baa41469 JP |
261 | Make sure that, when CONFIG_FRAME_POINTER is enabled, the function |
262 | pushes and sets up the frame pointer (for x86_64, this means rbp) at | |
263 | the beginning of the function and pops it at the end of the function. | |
264 | Also make sure that no other code in the function touches the frame | |
265 | pointer. | |
442f04c3 | 266 | |
baa41469 JP |
267 | Another possibility is that the code has some asm or inline asm which |
268 | does some unusual things to the stack or the frame pointer. In such | |
627fce14 JP |
269 | cases it's probably appropriate to use the unwind hint macros in |
270 | asm/unwind_hints.h. | |
442f04c3 | 271 | |
442f04c3 | 272 | |
baa41469 | 273 | 8. file.o: warning: objtool: funcA() falls through to next function funcB() |
442f04c3 | 274 | |
b1547d31 JP |
275 | This means that funcA() doesn't end with a return instruction or an |
276 | unconditional jump, and that objtool has determined that the function | |
277 | can fall through into the next function. There could be different | |
278 | reasons for this: | |
442f04c3 | 279 | |
b1547d31 JP |
280 | 1) funcA()'s last instruction is a call to a "noreturn" function like |
281 | panic(). In this case the noreturn function needs to be added to | |
282 | objtool's hard-coded global_noreturns array. Feel free to bug the | |
283 | objtool maintainer, or you can submit a patch. | |
442f04c3 | 284 | |
b1547d31 JP |
285 | 2) funcA() uses the unreachable() annotation in a section of code |
286 | that is actually reachable. | |
287 | ||
288 | 3) If funcA() calls an inline function, the object code for funcA() | |
289 | might be corrupt due to a gcc bug. For more details, see: | |
290 | https://gcc.gnu.org/bugzilla/show_bug.cgi?id=70646 | |
291 | ||
442f04c3 JP |
292 | |
293 | If the error doesn't seem to make sense, it could be a bug in objtool. | |
294 | Feel free to ask the objtool maintainer for help. | |
295 | ||
296 | ||
297 | Adding exceptions | |
298 | ----------------- | |
299 | ||
300 | If you _really_ need objtool to ignore something, and are 100% sure | |
301 | that it won't affect kernel stack traces, you can tell objtool to | |
302 | ignore it: | |
303 | ||
304 | - To skip validation of a function, use the STACK_FRAME_NON_STANDARD | |
305 | macro. | |
306 | ||
307 | - To skip validation of a file, add | |
308 | ||
309 | OBJECT_FILES_NON_STANDARD_filename.o := n | |
310 | ||
311 | to the Makefile. | |
312 | ||
313 | - To skip validation of a directory, add | |
314 | ||
315 | OBJECT_FILES_NON_STANDARD := y | |
316 | ||
317 | to the Makefile. |