projects/linux·blob master · refs

488 lines · 19.3 KiB

1Objtool
2=======
3
4The kernel CONFIG_OBJTOOL option enables a host tool named 'objtool'
5which runs at compile time. It can do various validations and
6transformations on .o files.
7
8Objtool has become an integral part of the x86-64 kernel toolchain. The
9kernel depends on it for a variety of security and performance features
10(and other types of features as well).
11
12
13Features
14--------
15
16Objtool has the following features:
17
18- Stack unwinding metadata validation -- useful for helping to ensure
19 stack traces are reliable for live patching
20
21- ORC unwinder metadata generation -- a faster and more precise
22 alternative to frame pointer based unwinding
23
24- Retpoline validation -- ensures that all indirect calls go through
25 retpoline thunks, for Spectre v2 mitigations
26
27- Retpoline call site annotation -- annotates all retpoline thunk call
28 sites, enabling the kernel to patch them inline, to prevent "thunk
29 funneling" for both security and performance reasons
30
31- Return thunk validation -- validates return thunks are used for
32 certain CPU mitigations including Retbleed and SRSO
33
34- Return thunk annotation -- annotates all return thunk sites so kernel
35 can patch them inline, depending on enabled mitigations
36
37- Return thunk untraining validation -- validate that all entry paths
38 untrain a "safe return" before the first return (or call)
39
40- Non-instrumentation validation -- validates non-instrumentable
41 ("noinstr") code rules, preventing instrumentation in low-level C
42 entry code
43
44- Static call annotation -- annotates static call sites, enabling the
45 kernel to implement inline static calls, a faster alternative to some
46 indirect branches
47
48- Uaccess validation -- validates uaccess rules for a proper
49 implementation of Supervisor Mode Access Protection (SMAP)
50
51- Straight Line Speculation validation -- validates certain SLS
52 mitigations
53
54- Indirect Branch Tracking validation -- validates Intel CET IBT rules
55 to ensure that all functions referenced by function pointers have
56 corresponding ENDBR instructions
57
58- Indirect Branch Tracking annotation -- annotates unused ENDBR
59 instruction sites, enabling the kernel to "seal" them (replace them
60 with NOPs) to further harden IBT
61
62- Function entry annotation -- annotates function entries, enabling
63 kernel function tracing
64
65- Function preamble (prefix) annotation and/or symbol generation -- used
66 for FineIBT and call depth tracking
67
68- Other toolchain hacks which will go unmentioned at this time...
69
70Each feature can be enabled individually or in combination using the
71objtool cmdline.
72
73
74Objects
75-------
76
77Typically, objtool runs on every translation unit (TU, aka ".o file") in
78the kernel. If a TU is part of a kernel module, the '--module' option
79is added.
80
81However:
82
83- If noinstr validation is enabled, it also runs on vmlinux.o, with all
84 options removed and '--noinstr' added.
85
86- If IBT or LTO is enabled, it doesn't run on TUs at all. Instead it
87 runs on vmlinux.o and linked modules, with all options.
88
89In summary:
90
91 A) Legacy mode:
92 TU: objtool [--module] <options>
93 vmlinux: N/A
94 module: N/A
95
96 B) CONFIG_NOINSTR_VALIDATION=y && !(CONFIG_X86_KERNEL_IBT=y || CONFIG_LTO=y):
97 TU: objtool [--module] <options> // no --noinstr
98 vmlinux: objtool --noinstr // other options removed
99 module: N/A
100
101 C) CONFIG_X86_KERNEL_IBT=y || CONFIG_LTO=y:
102 TU: N/A
103 vmlinux: objtool --noinstr <options>
104 module: objtool --module --noinstr <options>
105
106
107Stack validation
108----------------
109
110Objtool's stack validation feature analyzes every .o file and ensures
111the validity of its stack metadata. It enforces a set of rules on asm
112code and C inline assembly code so that stack traces can be reliable.
113
114For each function, it recursively follows all possible code paths and
115validates the correct frame pointer state at each instruction.
116
117It also follows code paths involving special sections, like
118.altinstructions, __jump_table, and __ex_table, which can add
119alternative execution paths to a given instruction (or set of
120instructions). Similarly, it knows how to follow switch statements, for
121which gcc sometimes uses jump tables.
122
123Here are some of the benefits of validating stack metadata:
124
125a) More reliable stack traces for frame pointer enabled kernels
126
127 Frame pointers are used for debugging purposes. They allow runtime
128 code and debug tools to be able to walk the stack to determine the
129 chain of function call sites that led to the currently executing
130 code.
131
132 For some architectures, frame pointers are enabled by
133 CONFIG_FRAME_POINTER. For some other architectures they may be
134 required by the ABI (sometimes referred to as "backchain pointers").
135
136 For C code, gcc automatically generates instructions for setting up
137 frame pointers when the -fno-omit-frame-pointer option is used.
138
139 But for asm code, the frame setup instructions have to be written by
140 hand, which most people don't do. So the end result is that
141 CONFIG_FRAME_POINTER is honored for C code but not for most asm code.
142
143 For stack traces based on frame pointers to be reliable, all
144 functions which call other functions must first create a stack frame
145 and update the frame pointer. If a first function doesn't properly
146 create a stack frame before calling a second function, the *caller*
147 of the first function will be skipped on the stack trace.
148
149 For example, consider the following example backtrace with frame
150 pointers enabled:
151
152 [<ffffffff81812584>] dump_stack+0x4b/0x63
153 [<ffffffff812d6dc2>] cmdline_proc_show+0x12/0x30
154 [<ffffffff8127f568>] seq_read+0x108/0x3e0
155 [<ffffffff812cce62>] proc_reg_read+0x42/0x70
156 [<ffffffff81256197>] __vfs_read+0x37/0x100
157 [<ffffffff81256b16>] vfs_read+0x86/0x130
158 [<ffffffff81257898>] SyS_read+0x58/0xd0
159 [<ffffffff8181c1f2>] entry_SYSCALL_64_fastpath+0x12/0x76
160
161 It correctly shows that the caller of cmdline_proc_show() is
162 seq_read().
163
164 If we remove the frame pointer logic from cmdline_proc_show() by
165 replacing the frame pointer related instructions with nops, here's
166 what it looks like instead:
167
168 [<ffffffff81812584>] dump_stack+0x4b/0x63
169 [<ffffffff812d6dc2>] cmdline_proc_show+0x12/0x30
170 [<ffffffff812cce62>] proc_reg_read+0x42/0x70
171 [<ffffffff81256197>] __vfs_read+0x37/0x100
172 [<ffffffff81256b16>] vfs_read+0x86/0x130
173 [<ffffffff81257898>] SyS_read+0x58/0xd0
174 [<ffffffff8181c1f2>] entry_SYSCALL_64_fastpath+0x12/0x76
175
176 Notice that cmdline_proc_show()'s caller, seq_read(), has been
177 skipped. Instead the stack trace seems to show that
178 cmdline_proc_show() was called by proc_reg_read().
179
180 The benefit of objtool here is that because it ensures that *all*
181 functions honor CONFIG_FRAME_POINTER, no functions will ever[*] be
182 skipped on a stack trace.
183
184 [*] unless an interrupt or exception has occurred at the very
185 beginning of a function before the stack frame has been created,
186 or at the very end of the function after the stack frame has been
187 destroyed. This is an inherent limitation of frame pointers.
188
189b) ORC (Oops Rewind Capability) unwind table generation
190
191 An alternative to frame pointers and DWARF, ORC unwind data can be
192 used to walk the stack. Unlike frame pointers, ORC data is out of
193 band. So it doesn't affect runtime performance and it can be
194 reliable even when interrupts or exceptions are involved.
195
196 For more details, see Documentation/arch/x86/orc-unwinder.rst.
197
198c) Higher live patching compatibility rate
199
200 Livepatch has an optional "consistency model", which is needed for
201 more complex patches. In order for the consistency model to work,
202 stack traces need to be reliable (or an unreliable condition needs to
203 be detectable). Objtool makes that possible.
204
205 For more details, see the livepatch documentation in the Linux kernel
206 source tree at Documentation/livepatch/livepatch.rst.
207
208To achieve the validation, objtool enforces the following rules:
209
2101. Each callable function must be annotated as such with the ELF
211 function type. In asm code, this is typically done using the
212 SYM_FUNC_{START,END} macros. If objtool finds a return instruction
213 outside of a function, it flags an error since that usually indicates
214 callable code which should be annotated accordingly.
215
216 This rule is needed so that objtool can properly identify each
217 callable function in order to analyze its stack metadata.
218
2192. Conversely, each section of code which is *not* callable, or is
220 otherwise doing funny things with the stack or registers, should
221 *not* be annotated as an ELF function. Rather, SYM_CODE_{START,END}
222 should be used along with unwind hints.
223
2243. Each callable function which calls another function must have the
225 correct frame pointer logic, if required by CONFIG_FRAME_POINTER or
226 the architecture's back chain rules. This can by done in asm code
227 with the FRAME_BEGIN/FRAME_END macros.
228
229 This rule ensures that frame pointer based stack traces will work as
230 designed. If function A doesn't create a stack frame before calling
231 function B, the _caller_ of function A will be skipped on the stack
232 trace.
233
2344. Indirect jumps and jumps to undefined symbols are only allowed if:
235
236 a) the jump is part of a switch statement; or
237
238 b) the jump matches sibling call semantics and the frame pointer has
239 the same value it had on function entry.
240
241 This rule is needed so that objtool can reliably analyze all of a
242 function's code paths. If a function jumps to code in another file,
243 and it's not a sibling call, objtool has no way to follow the jump
244 because it only analyzes a single file at a time.
245
2465. A callable function may not execute kernel entry/exit instructions.
247 The only code which needs such instructions is kernel entry code,
248 which shouldn't be be in callable functions anyway.
249
250 This rule is just a sanity check to ensure that callable functions
251 return normally.
252
253
254Objtool warnings
255----------------
256
257NOTE: When requesting help with an objtool warning, please recreate with
258OBJTOOL_VERBOSE=1 (e.g., "make OBJTOOL_VERBOSE=1") and send the full
259output, including any disassembly or backtrace below the warning, to the
260objtool maintainers.
261
262For asm files, if you're getting an error which doesn't make sense,
263first make sure that the affected code follows the above rules.
264
265For C files, the common culprits are inline asm statements and calls to
266"noreturn" functions. See below for more details.
267
268Another possible cause for errors in C code is if the Makefile removes
269-fno-omit-frame-pointer or adds -fomit-frame-pointer to the gcc options.
270
271Here are some examples of common warnings reported by objtool, what
272they mean, and suggestions for how to fix them. When in doubt, ping
273the objtool maintainers.
274
275
2761. file.o: warning: objtool: func()+0x128: call without frame pointer save/setup
277
278 The func() function made a function call without first saving and/or
279 updating the frame pointer, and CONFIG_FRAME_POINTER is enabled.
280
281 If the error is for an asm file, and func() is indeed a callable
282 function, add proper frame pointer logic using the FRAME_BEGIN and
283 FRAME_END macros. Otherwise, if it's not a callable function, remove
284 its ELF function annotation by using SYM_CODE_{START,END} and use the
285 manual unwind hint macros in asm/unwind_hints.h.
286
287 If it's a GCC-compiled .c file, the error may be because the function
288 uses an inline asm() statement which has a "call" instruction. An
289 asm() statement with a call instruction must declare the use of the
290 stack pointer in its output operand. On x86_64, this means adding
291 the ASM_CALL_CONSTRAINT as an output constraint:
292
293 asm volatile("call func" : ASM_CALL_CONSTRAINT);
294
295 Otherwise the stack frame may not get created before the call.
296
297 objtool can help with pinpointing the exact function where it happens:
298
299 $ OBJTOOL_ARGS="--verbose" make arch/x86/kvm/
300
301 arch/x86/kvm/kvm.o: warning: objtool: .altinstr_replacement+0xc5: call without frame pointer save/setup
302 arch/x86/kvm/kvm.o: warning: objtool: em_loop.part.0+0x29: (alt)
303 arch/x86/kvm/kvm.o: warning: objtool: em_loop.part.0+0x0: <=== (sym)
304 LD [M] arch/x86/kvm/kvm-intel.o
305 0000 0000000000028220 <em_loop.part.0>:
306 0000 28220: 0f b6 47 61 movzbl 0x61(%rdi),%eax
307 0004 28224: 3c e2 cmp $0xe2,%al
308 0006 28226: 74 2c je 28254 <em_loop.part.0+0x34>
309 0008 28228: 48 8b 57 10 mov 0x10(%rdi),%rdx
310 000c 2822c: 83 f0 05 xor $0x5,%eax
311 000f 2822f: 48 c1 e0 04 shl $0x4,%rax
312 0013 28233: 25 f0 00 00 00 and $0xf0,%eax
313 0018 28238: 81 e2 d5 08 00 00 and $0x8d5,%edx
314 001e 2823e: 80 ce 02 or $0x2,%dh
315 ...
316
317
3182. file.o: warning: objtool: .text+0x53: unreachable instruction
319
320 Objtool couldn't find a code path to reach the instruction.
321
322 If the error is for an asm file, and the instruction is inside (or
323 reachable from) a callable function, the function should be annotated
324 with the SYM_FUNC_START and SYM_FUNC_END macros.
325
326 Otherwise, SYM_CODE_START can be used. In that case the code needs
327 to be annotated with unwind hint macros.
328
329 If you're sure the code won't affect the reliability of runtime stack
330 traces and want objtool to ignore it, see "Adding exceptions" below.
331
332
3333. file.o: warning: objtool: foo+0x48c: bar() missing __noreturn in .c/.h or NORETURN() in noreturns.h
334
335 The call from foo() to bar() doesn't return, but bar() is incorrectly
336 annotated. A noreturn function must be marked __noreturn in both its
337 declaration and its definition, and must have a NORETURN() annotation
338 in tools/objtool/noreturns.h.
339
340
3414. file.o: warning: objtool: func(): can't find starting instruction
342 or
343 file.o: warning: objtool: func()+0x11dd: can't decode instruction
344
345 Does the file have data in a text section? If so, that can confuse
346 objtool's instruction decoder. Move the data to a more appropriate
347 section like .data or .rodata.
348
349
3505. file.o: warning: objtool: func()+0x6: unsupported instruction in callable function
351
352 This is a kernel entry/exit instruction like sysenter or iret. Such
353 instructions aren't allowed in a callable function, and are most
354 likely part of the kernel entry code. Such code should probably be
355 placed in a SYM_CODE_{START,END} block with unwind hints.
356
357
3586. file.o: warning: objtool: func()+0x26: sibling call from callable instruction with modified stack frame
359
360 This is a branch to an UNDEF symbol. Objtool assumed it's a
361 sibling call and detected that the stack wasn't first restored to its
362 original state.
363
364 If it's not really a sibling call, you may need to use unwind hints
365 and/or move the destination code to the local file.
366
367 If the instruction is not actually in a callable function (e.g.
368 kernel entry code), use SYM_CODE_{START,END} and unwind hints.
369
370
3717. file: warning: objtool: func()+0x5c: stack state mismatch
372
373 The instruction's frame pointer state is inconsistent, depending on
374 which execution path was taken to reach the instruction.
375
376 Make sure that, when CONFIG_FRAME_POINTER is enabled, the function
377 pushes and sets up the frame pointer (for x86_64, this means rbp) at
378 the beginning of the function and pops it at the end of the function.
379 Also make sure that no other code in the function touches the frame
380 pointer.
381
382 Another possibility is that the code has some asm or inline asm which
383 does some unusual things to the stack or the frame pointer. In such
384 cases it's probably appropriate to use SYM_CODE_{START,END} with unwind
385 hints.
386
387
3888. file.o: warning: objtool: funcA() falls through to next function funcB()
389
390 This means that funcA() doesn't end with a return instruction or an
391 unconditional jump, and that objtool has determined that the function
392 can fall through into the next function. There could be different
393 reasons for this:
394
395 a) funcA()'s last instruction is a call to a "noreturn" function like
396 panic(). In this case the noreturn function needs to be added to
397 objtool's hard-coded global_noreturns array. Feel free to bug the
398 objtool maintainer, or you can submit a patch.
399
400 b) funcA() uses the unreachable() annotation in a section of code
401 that is actually reachable.
402
403 c) Some undefined behavior like divide by zero.
404
405
4069. file.o: warning: objtool: funcA() call to funcB() with UACCESS enabled
407
408 This means that an unexpected call to a non-whitelisted function exists
409 outside of arch-specific guards.
410 X86: SMAP (stac/clac): __uaccess_begin()/__uaccess_end()
411 ARM: PAN: uaccess_enable()/uaccess_disable()
412
413 These functions should be called to denote a minimal critical section around
414 access to __user variables. See also: https://lwn.net/Articles/517475/
415
416 The intention of the warning is to prevent calls to funcB() from eventually
417 calling schedule(), potentially leaking the AC flags state, and not
418 restoring them correctly.
419
420 It also helps verify that there are no unexpected calls to funcB() which may
421 access user space pages with protections against doing so disabled.
422
423 To fix, either:
424 1) remove explicit calls to funcB() from funcA().
425 2) add the correct guards before and after calls to low level functions like
426 __get_user_size()/__put_user_size().
427 3) add funcB to uaccess_safe_builtin whitelist in tools/objtool/check.c, if
428 funcB obviously does not call schedule(), and is marked notrace (since
429 function tracing inserts additional calls, which is not obvious from the
430 sources).
431
43210. file.o: warning: func()+0x5c: stack layout conflict in alternatives
433
434 This means that in the use of the alternative() or ALTERNATIVE()
435 macro, the code paths have conflicting modifications to the stack.
436 The problem is that there is only one ORC unwind table, which means
437 that the ORC unwind entries must be consistent for all possible
438 instruction boundaries regardless of which code has been patched.
439 This limitation can be overcome by massaging the alternatives with
440 NOPs to shift the stack changes around so they no longer conflict.
441
442
44311. file.o: warning: unannotated intra-function call
444
445 This warning means that a direct call is done to a destination which
446 is not at the beginning of a function. If this is a legit call, you
447 can remove this warning by putting the ANNOTATE_INTRA_FUNCTION_CALL
448 directive right before the call.
449
450
45112. file.o: warning: func(): not an indirect call target
452
453 This means that objtool is running with --ibt and a function
454 expected to be an indirect call target is not. In particular, this
455 happens for init_module() or cleanup_module() if a module relies on
456 these special names and does not use module_init() / module_exit()
457 macros to create them.
458
459
460If the error doesn't seem to make sense, it could be a bug in objtool.
461Feel free to ask objtool maintainers for help.
462
463
464Adding exceptions
465-----------------
466
467If you _really_ need objtool to ignore something, and are 100% sure
468that it won't affect kernel stack traces, you can tell objtool to
469ignore it:
470
471- To skip validation of a function, use the STACK_FRAME_NON_STANDARD
472 macro.
473
474- To skip validation of a file, add
475
476 OBJECT_FILES_NON_STANDARD_filename.o := y
477
478 to the Makefile.
479
480- To skip validation of a directory, add
481
482 OBJECT_FILES_NON_STANDARD := y
483
484 to the Makefile.
485
486NOTE: OBJECT_FILES_NON_STANDARD doesn't work for link time validation of
487vmlinux.o or a linked module. So it should only be used for files which
488aren't linked into vmlinux or a module.