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 | ||
14 | Currently it only checks frame pointer usage, but there are plans to add | |
15 | CFI validation for C files and CFI generation for asm files. | |
16 | ||
17 | For each function, it recursively follows all possible code paths and | |
18 | validates the correct frame pointer state at each instruction. | |
19 | ||
20 | It also follows code paths involving special sections, like | |
21 | .altinstructions, __jump_table, and __ex_table, which can add | |
22 | alternative execution paths to a given instruction (or set of | |
23 | instructions). Similarly, it knows how to follow switch statements, for | |
24 | which gcc sometimes uses jump tables. | |
25 | ||
26 | ||
27 | Why do we need stack metadata validation? | |
28 | ----------------------------------------- | |
29 | ||
30 | Here are some of the benefits of validating stack metadata: | |
31 | ||
32 | a) More reliable stack traces for frame pointer enabled kernels | |
33 | ||
34 | Frame pointers are used for debugging purposes. They allow runtime | |
35 | code and debug tools to be able to walk the stack to determine the | |
36 | chain of function call sites that led to the currently executing | |
37 | code. | |
38 | ||
39 | For some architectures, frame pointers are enabled by | |
40 | CONFIG_FRAME_POINTER. For some other architectures they may be | |
41 | required by the ABI (sometimes referred to as "backchain pointers"). | |
42 | ||
43 | For C code, gcc automatically generates instructions for setting up | |
44 | frame pointers when the -fno-omit-frame-pointer option is used. | |
45 | ||
46 | But for asm code, the frame setup instructions have to be written by | |
47 | hand, which most people don't do. So the end result is that | |
48 | CONFIG_FRAME_POINTER is honored for C code but not for most asm code. | |
49 | ||
50 | For stack traces based on frame pointers to be reliable, all | |
51 | functions which call other functions must first create a stack frame | |
52 | and update the frame pointer. If a first function doesn't properly | |
53 | create a stack frame before calling a second function, the *caller* | |
54 | of the first function will be skipped on the stack trace. | |
55 | ||
56 | For example, consider the following example backtrace with frame | |
57 | pointers enabled: | |
58 | ||
59 | [<ffffffff81812584>] dump_stack+0x4b/0x63 | |
60 | [<ffffffff812d6dc2>] cmdline_proc_show+0x12/0x30 | |
61 | [<ffffffff8127f568>] seq_read+0x108/0x3e0 | |
62 | [<ffffffff812cce62>] proc_reg_read+0x42/0x70 | |
63 | [<ffffffff81256197>] __vfs_read+0x37/0x100 | |
64 | [<ffffffff81256b16>] vfs_read+0x86/0x130 | |
65 | [<ffffffff81257898>] SyS_read+0x58/0xd0 | |
66 | [<ffffffff8181c1f2>] entry_SYSCALL_64_fastpath+0x12/0x76 | |
67 | ||
68 | It correctly shows that the caller of cmdline_proc_show() is | |
69 | seq_read(). | |
70 | ||
71 | If we remove the frame pointer logic from cmdline_proc_show() by | |
72 | replacing the frame pointer related instructions with nops, here's | |
73 | what it looks like instead: | |
74 | ||
75 | [<ffffffff81812584>] dump_stack+0x4b/0x63 | |
76 | [<ffffffff812d6dc2>] cmdline_proc_show+0x12/0x30 | |
77 | [<ffffffff812cce62>] proc_reg_read+0x42/0x70 | |
78 | [<ffffffff81256197>] __vfs_read+0x37/0x100 | |
79 | [<ffffffff81256b16>] vfs_read+0x86/0x130 | |
80 | [<ffffffff81257898>] SyS_read+0x58/0xd0 | |
81 | [<ffffffff8181c1f2>] entry_SYSCALL_64_fastpath+0x12/0x76 | |
82 | ||
83 | Notice that cmdline_proc_show()'s caller, seq_read(), has been | |
84 | skipped. Instead the stack trace seems to show that | |
85 | cmdline_proc_show() was called by proc_reg_read(). | |
86 | ||
87 | The benefit of objtool here is that because it ensures that *all* | |
88 | functions honor CONFIG_FRAME_POINTER, no functions will ever[*] be | |
89 | skipped on a stack trace. | |
90 | ||
91 | [*] unless an interrupt or exception has occurred at the very | |
92 | beginning of a function before the stack frame has been created, | |
93 | or at the very end of the function after the stack frame has been | |
94 | destroyed. This is an inherent limitation of frame pointers. | |
95 | ||
96 | b) 100% reliable stack traces for DWARF enabled kernels | |
97 | ||
98 | (NOTE: This is not yet implemented) | |
99 | ||
100 | As an alternative to frame pointers, DWARF Call Frame Information | |
101 | (CFI) metadata can be used to walk the stack. Unlike frame pointers, | |
102 | CFI metadata is out of band. So it doesn't affect runtime | |
103 | performance and it can be reliable even when interrupts or exceptions | |
104 | are involved. | |
105 | ||
106 | For C code, gcc automatically generates DWARF CFI metadata. But for | |
107 | asm code, generating CFI is a tedious manual approach which requires | |
108 | manually placed .cfi assembler macros to be scattered throughout the | |
109 | code. It's clumsy and very easy to get wrong, and it makes the real | |
110 | code harder to read. | |
111 | ||
112 | Stacktool will improve this situation in several ways. For code | |
113 | which already has CFI annotations, it will validate them. For code | |
114 | which doesn't have CFI annotations, it will generate them. So an | |
115 | architecture can opt to strip out all the manual .cfi annotations | |
116 | from their asm code and have objtool generate them instead. | |
117 | ||
118 | We might also add a runtime stack validation debug option where we | |
119 | periodically walk the stack from schedule() and/or an NMI to ensure | |
120 | that the stack metadata is sane and that we reach the bottom of the | |
121 | stack. | |
122 | ||
123 | So the benefit of objtool here will be that external tooling should | |
124 | always show perfect stack traces. And the same will be true for | |
125 | kernel warning/oops traces if the architecture has a runtime DWARF | |
126 | unwinder. | |
127 | ||
128 | c) Higher live patching compatibility rate | |
129 | ||
130 | (NOTE: This is not yet implemented) | |
131 | ||
132 | Currently with CONFIG_LIVEPATCH there's a basic live patching | |
133 | framework which is safe for roughly 85-90% of "security" fixes. But | |
134 | patches can't have complex features like function dependency or | |
135 | prototype changes, or data structure changes. | |
136 | ||
137 | There's a strong need to support patches which have the more complex | |
138 | features so that the patch compatibility rate for security fixes can | |
139 | eventually approach something resembling 100%. To achieve that, a | |
140 | "consistency model" is needed, which allows tasks to be safely | |
141 | transitioned from an unpatched state to a patched state. | |
142 | ||
143 | One of the key requirements of the currently proposed livepatch | |
144 | consistency model [*] is that it needs to walk the stack of each | |
145 | sleeping task to determine if it can be transitioned to the patched | |
146 | state. If objtool can ensure that stack traces are reliable, this | |
147 | consistency model can be used and the live patching compatibility | |
148 | rate can be improved significantly. | |
149 | ||
150 | [*] https://lkml.kernel.org/r/cover.1423499826.git.jpoimboe@redhat.com | |
151 | ||
152 | ||
153 | Rules | |
154 | ----- | |
155 | ||
156 | To achieve the validation, objtool enforces the following rules: | |
157 | ||
158 | 1. Each callable function must be annotated as such with the ELF | |
159 | function type. In asm code, this is typically done using the | |
160 | ENTRY/ENDPROC macros. If objtool finds a return instruction | |
161 | outside of a function, it flags an error since that usually indicates | |
162 | callable code which should be annotated accordingly. | |
163 | ||
164 | This rule is needed so that objtool can properly identify each | |
165 | callable function in order to analyze its stack metadata. | |
166 | ||
167 | 2. Conversely, each section of code which is *not* callable should *not* | |
168 | be annotated as an ELF function. The ENDPROC macro shouldn't be used | |
169 | in this case. | |
170 | ||
171 | This rule is needed so that objtool can ignore non-callable code. | |
172 | Such code doesn't have to follow any of the other rules. | |
173 | ||
174 | 3. Each callable function which calls another function must have the | |
175 | correct frame pointer logic, if required by CONFIG_FRAME_POINTER or | |
176 | the architecture's back chain rules. This can by done in asm code | |
177 | with the FRAME_BEGIN/FRAME_END macros. | |
178 | ||
179 | This rule ensures that frame pointer based stack traces will work as | |
180 | designed. If function A doesn't create a stack frame before calling | |
181 | function B, the _caller_ of function A will be skipped on the stack | |
182 | trace. | |
183 | ||
184 | 4. Dynamic jumps and jumps to undefined symbols are only allowed if: | |
185 | ||
186 | a) the jump is part of a switch statement; or | |
187 | ||
188 | b) the jump matches sibling call semantics and the frame pointer has | |
189 | the same value it had on function entry. | |
190 | ||
191 | This rule is needed so that objtool can reliably analyze all of a | |
192 | function's code paths. If a function jumps to code in another file, | |
193 | and it's not a sibling call, objtool has no way to follow the jump | |
194 | because it only analyzes a single file at a time. | |
195 | ||
196 | 5. A callable function may not execute kernel entry/exit instructions. | |
197 | The only code which needs such instructions is kernel entry code, | |
198 | which shouldn't be be in callable functions anyway. | |
199 | ||
200 | This rule is just a sanity check to ensure that callable functions | |
201 | return normally. | |
202 | ||
203 | ||
204 | Errors in .S files | |
205 | ------------------ | |
206 | ||
207 | If you're getting an error in a compiled .S file which you don't | |
208 | understand, first make sure that the affected code follows the above | |
209 | rules. | |
210 | ||
211 | Here are some examples of common warnings reported by objtool, what | |
212 | they mean, and suggestions for how to fix them. | |
213 | ||
214 | ||
215 | 1. asm_file.o: warning: objtool: func()+0x128: call without frame pointer save/setup | |
216 | ||
217 | The func() function made a function call without first saving and/or | |
218 | updating the frame pointer. | |
219 | ||
220 | If func() is indeed a callable function, add proper frame pointer | |
221 | logic using the FRAME_BEGIN and FRAME_END macros. Otherwise, remove | |
222 | its ELF function annotation by changing ENDPROC to END. | |
223 | ||
224 | If you're getting this error in a .c file, see the "Errors in .c | |
225 | files" section. | |
226 | ||
227 | ||
228 | 2. asm_file.o: warning: objtool: .text+0x53: return instruction outside of a callable function | |
229 | ||
230 | A return instruction was detected, but objtool couldn't find a way | |
231 | for a callable function to reach the instruction. | |
232 | ||
233 | If the return instruction is inside (or reachable from) a callable | |
234 | function, the function needs to be annotated with the ENTRY/ENDPROC | |
235 | macros. | |
236 | ||
237 | If you _really_ need a return instruction outside of a function, and | |
238 | are 100% sure that it won't affect stack traces, you can tell | |
239 | objtool to ignore it. See the "Adding exceptions" section below. | |
240 | ||
241 | ||
242 | 3. asm_file.o: warning: objtool: func()+0x9: function has unreachable instruction | |
243 | ||
244 | The instruction lives inside of a callable function, but there's no | |
245 | possible control flow path from the beginning of the function to the | |
246 | instruction. | |
247 | ||
248 | If the instruction is actually needed, and it's actually in a | |
249 | callable function, ensure that its function is properly annotated | |
250 | with ENTRY/ENDPROC. | |
251 | ||
252 | If it's not actually in a callable function (e.g. kernel entry code), | |
253 | change ENDPROC to END. | |
254 | ||
255 | ||
256 | 4. asm_file.o: warning: objtool: func(): can't find starting instruction | |
257 | or | |
258 | asm_file.o: warning: objtool: func()+0x11dd: can't decode instruction | |
259 | ||
260 | Did you put data in a text section? If so, that can confuse | |
261 | objtool's instruction decoder. Move the data to a more appropriate | |
262 | section like .data or .rodata. | |
263 | ||
264 | ||
265 | 5. asm_file.o: warning: objtool: func()+0x6: kernel entry/exit from callable instruction | |
266 | ||
267 | This is a kernel entry/exit instruction like sysenter or sysret. | |
268 | Such instructions aren't allowed in a callable function, and are most | |
269 | likely part of the kernel entry code. | |
270 | ||
271 | If the instruction isn't actually in a callable function, change | |
272 | ENDPROC to END. | |
273 | ||
274 | ||
275 | 6. asm_file.o: warning: objtool: func()+0x26: sibling call from callable instruction with changed frame pointer | |
276 | ||
277 | This is a dynamic jump or a jump to an undefined symbol. Stacktool | |
278 | assumed it's a sibling call and detected that the frame pointer | |
279 | wasn't first restored to its original state. | |
280 | ||
281 | If it's not really a sibling call, you may need to move the | |
282 | destination code to the local file. | |
283 | ||
284 | If the instruction is not actually in a callable function (e.g. | |
285 | kernel entry code), change ENDPROC to END. | |
286 | ||
287 | ||
288 | 7. asm_file: warning: objtool: func()+0x5c: frame pointer state mismatch | |
289 | ||
290 | The instruction's frame pointer state is inconsistent, depending on | |
291 | which execution path was taken to reach the instruction. | |
292 | ||
293 | Make sure the function pushes and sets up the frame pointer (for | |
294 | x86_64, this means rbp) at the beginning of the function and pops it | |
295 | at the end of the function. Also make sure that no other code in the | |
296 | function touches the frame pointer. | |
297 | ||
298 | ||
299 | Errors in .c files | |
300 | ------------------ | |
301 | ||
b1547d31 | 302 | 1. c_file.o: warning: objtool: funcA() falls through to next function funcB() |
442f04c3 | 303 | |
b1547d31 JP |
304 | This means that funcA() doesn't end with a return instruction or an |
305 | unconditional jump, and that objtool has determined that the function | |
306 | can fall through into the next function. There could be different | |
307 | reasons for this: | |
442f04c3 | 308 | |
b1547d31 JP |
309 | 1) funcA()'s last instruction is a call to a "noreturn" function like |
310 | panic(). In this case the noreturn function needs to be added to | |
311 | objtool's hard-coded global_noreturns array. Feel free to bug the | |
312 | objtool maintainer, or you can submit a patch. | |
442f04c3 | 313 | |
b1547d31 JP |
314 | 2) funcA() uses the unreachable() annotation in a section of code |
315 | that is actually reachable. | |
316 | ||
317 | 3) If funcA() calls an inline function, the object code for funcA() | |
318 | might be corrupt due to a gcc bug. For more details, see: | |
319 | https://gcc.gnu.org/bugzilla/show_bug.cgi?id=70646 | |
320 | ||
321 | 2. If you're getting any other objtool error in a compiled .c file, it | |
322 | may be because the file uses an asm() statement which has a "call" | |
323 | instruction. An asm() statement with a call instruction must declare | |
324 | the use of the stack pointer in its output operand. For example, on | |
325 | x86_64: | |
326 | ||
327 | register void *__sp asm("rsp"); | |
328 | asm volatile("call func" : "+r" (__sp)); | |
329 | ||
330 | Otherwise the stack frame may not get created before the call. | |
331 | ||
332 | 3. Another possible cause for errors in C code is if the Makefile removes | |
333 | -fno-omit-frame-pointer or adds -fomit-frame-pointer to the gcc options. | |
442f04c3 JP |
334 | |
335 | Also see the above section for .S file errors for more information what | |
336 | the individual error messages mean. | |
337 | ||
338 | If the error doesn't seem to make sense, it could be a bug in objtool. | |
339 | Feel free to ask the objtool maintainer for help. | |
340 | ||
341 | ||
342 | Adding exceptions | |
343 | ----------------- | |
344 | ||
345 | If you _really_ need objtool to ignore something, and are 100% sure | |
346 | that it won't affect kernel stack traces, you can tell objtool to | |
347 | ignore it: | |
348 | ||
349 | - To skip validation of a function, use the STACK_FRAME_NON_STANDARD | |
350 | macro. | |
351 | ||
352 | - To skip validation of a file, add | |
353 | ||
354 | OBJECT_FILES_NON_STANDARD_filename.o := n | |
355 | ||
356 | to the Makefile. | |
357 | ||
358 | - To skip validation of a directory, add | |
359 | ||
360 | OBJECT_FILES_NON_STANDARD := y | |
361 | ||
362 | to the Makefile. |