480 lines · plain
1Objtool2=======3 4The kernel CONFIG_OBJTOOL option enables a host tool named 'objtool'5which runs at compile time. It can do various validations and6transformations on .o files.7 8Objtool has become an integral part of the x86-64 kernel toolchain. The9kernel depends on it for a variety of security and performance features10(and other types of features as well).11 12 13Features14--------15 16Objtool has the following features:17 18- Stack unwinding metadata validation -- useful for helping to ensure19 stack traces are reliable for live patching20 21- ORC unwinder metadata generation -- a faster and more precise22 alternative to frame pointer based unwinding23 24- Retpoline validation -- ensures that all indirect calls go through25 retpoline thunks, for Spectre v2 mitigations26 27- Retpoline call site annotation -- annotates all retpoline thunk call28 sites, enabling the kernel to patch them inline, to prevent "thunk29 funneling" for both security and performance reasons30 31- Non-instrumentation validation -- validates non-instrumentable32 ("noinstr") code rules, preventing instrumentation in low-level C33 entry code34 35- Static call annotation -- annotates static call sites, enabling the36 kernel to implement inline static calls, a faster alternative to some37 indirect branches38 39- Uaccess validation -- validates uaccess rules for a proper40 implementation of Supervisor Mode Access Protection (SMAP)41 42- Straight Line Speculation validation -- validates certain SLS43 mitigations44 45- Indirect Branch Tracking validation -- validates Intel CET IBT rules46 to ensure that all functions referenced by function pointers have47 corresponding ENDBR instructions48 49- Indirect Branch Tracking annotation -- annotates unused ENDBR50 instruction sites, enabling the kernel to "seal" them (replace them51 with NOPs) to further harden IBT52 53- Function entry annotation -- annotates function entries, enabling54 kernel function tracing55 56- Other toolchain hacks which will go unmentioned at this time...57 58Each feature can be enabled individually or in combination using the59objtool cmdline.60 61 62Objects63-------64 65Typically, objtool runs on every translation unit (TU, aka ".o file") in66the kernel. If a TU is part of a kernel module, the '--module' option67is added.68 69However:70 71- If noinstr validation is enabled, it also runs on vmlinux.o, with all72 options removed and '--noinstr' added.73 74- If IBT or LTO is enabled, it doesn't run on TUs at all. Instead it75 runs on vmlinux.o and linked modules, with all options.76 77In summary:78 79 A) Legacy mode:80 TU: objtool [--module] <options>81 vmlinux: N/A82 module: N/A83 84 B) CONFIG_NOINSTR_VALIDATION=y && !(CONFIG_X86_KERNEL_IBT=y || CONFIG_LTO=y):85 TU: objtool [--module] <options> // no --noinstr86 vmlinux: objtool --noinstr // other options removed87 module: N/A88 89 C) CONFIG_X86_KERNEL_IBT=y || CONFIG_LTO=y:90 TU: N/A91 vmlinux: objtool --noinstr <options>92 module: objtool --module --noinstr <options>93 94 95Stack validation96----------------97 98Objtool's stack validation feature analyzes every .o file and ensures99the validity of its stack metadata. It enforces a set of rules on asm100code and C inline assembly code so that stack traces can be reliable.101 102For each function, it recursively follows all possible code paths and103validates the correct frame pointer state at each instruction.104 105It also follows code paths involving special sections, like106.altinstructions, __jump_table, and __ex_table, which can add107alternative execution paths to a given instruction (or set of108instructions). Similarly, it knows how to follow switch statements, for109which gcc sometimes uses jump tables.110 111Here are some of the benefits of validating stack metadata:112 113a) More reliable stack traces for frame pointer enabled kernels114 115 Frame pointers are used for debugging purposes. They allow runtime116 code and debug tools to be able to walk the stack to determine the117 chain of function call sites that led to the currently executing118 code.119 120 For some architectures, frame pointers are enabled by121 CONFIG_FRAME_POINTER. For some other architectures they may be122 required by the ABI (sometimes referred to as "backchain pointers").123 124 For C code, gcc automatically generates instructions for setting up125 frame pointers when the -fno-omit-frame-pointer option is used.126 127 But for asm code, the frame setup instructions have to be written by128 hand, which most people don't do. So the end result is that129 CONFIG_FRAME_POINTER is honored for C code but not for most asm code.130 131 For stack traces based on frame pointers to be reliable, all132 functions which call other functions must first create a stack frame133 and update the frame pointer. If a first function doesn't properly134 create a stack frame before calling a second function, the *caller*135 of the first function will be skipped on the stack trace.136 137 For example, consider the following example backtrace with frame138 pointers enabled:139 140 [<ffffffff81812584>] dump_stack+0x4b/0x63141 [<ffffffff812d6dc2>] cmdline_proc_show+0x12/0x30142 [<ffffffff8127f568>] seq_read+0x108/0x3e0143 [<ffffffff812cce62>] proc_reg_read+0x42/0x70144 [<ffffffff81256197>] __vfs_read+0x37/0x100145 [<ffffffff81256b16>] vfs_read+0x86/0x130146 [<ffffffff81257898>] SyS_read+0x58/0xd0147 [<ffffffff8181c1f2>] entry_SYSCALL_64_fastpath+0x12/0x76148 149 It correctly shows that the caller of cmdline_proc_show() is150 seq_read().151 152 If we remove the frame pointer logic from cmdline_proc_show() by153 replacing the frame pointer related instructions with nops, here's154 what it looks like instead:155 156 [<ffffffff81812584>] dump_stack+0x4b/0x63157 [<ffffffff812d6dc2>] cmdline_proc_show+0x12/0x30158 [<ffffffff812cce62>] proc_reg_read+0x42/0x70159 [<ffffffff81256197>] __vfs_read+0x37/0x100160 [<ffffffff81256b16>] vfs_read+0x86/0x130161 [<ffffffff81257898>] SyS_read+0x58/0xd0162 [<ffffffff8181c1f2>] entry_SYSCALL_64_fastpath+0x12/0x76163 164 Notice that cmdline_proc_show()'s caller, seq_read(), has been165 skipped. Instead the stack trace seems to show that166 cmdline_proc_show() was called by proc_reg_read().167 168 The benefit of objtool here is that because it ensures that *all*169 functions honor CONFIG_FRAME_POINTER, no functions will ever[*] be170 skipped on a stack trace.171 172 [*] unless an interrupt or exception has occurred at the very173 beginning of a function before the stack frame has been created,174 or at the very end of the function after the stack frame has been175 destroyed. This is an inherent limitation of frame pointers.176 177b) ORC (Oops Rewind Capability) unwind table generation178 179 An alternative to frame pointers and DWARF, ORC unwind data can be180 used to walk the stack. Unlike frame pointers, ORC data is out of181 band. So it doesn't affect runtime performance and it can be182 reliable even when interrupts or exceptions are involved.183 184 For more details, see Documentation/arch/x86/orc-unwinder.rst.185 186c) Higher live patching compatibility rate187 188 Livepatch has an optional "consistency model", which is needed for189 more complex patches. In order for the consistency model to work,190 stack traces need to be reliable (or an unreliable condition needs to191 be detectable). Objtool makes that possible.192 193 For more details, see the livepatch documentation in the Linux kernel194 source tree at Documentation/livepatch/livepatch.rst.195 196To achieve the validation, objtool enforces the following rules:197 1981. Each callable function must be annotated as such with the ELF199 function type. In asm code, this is typically done using the200 ENTRY/ENDPROC macros. If objtool finds a return instruction201 outside of a function, it flags an error since that usually indicates202 callable code which should be annotated accordingly.203 204 This rule is needed so that objtool can properly identify each205 callable function in order to analyze its stack metadata.206 2072. Conversely, each section of code which is *not* callable should *not*208 be annotated as an ELF function. The ENDPROC macro shouldn't be used209 in this case.210 211 This rule is needed so that objtool can ignore non-callable code.212 Such code doesn't have to follow any of the other rules.213 2143. Each callable function which calls another function must have the215 correct frame pointer logic, if required by CONFIG_FRAME_POINTER or216 the architecture's back chain rules. This can by done in asm code217 with the FRAME_BEGIN/FRAME_END macros.218 219 This rule ensures that frame pointer based stack traces will work as220 designed. If function A doesn't create a stack frame before calling221 function B, the _caller_ of function A will be skipped on the stack222 trace.223 2244. Dynamic jumps and jumps to undefined symbols are only allowed if:225 226 a) the jump is part of a switch statement; or227 228 b) the jump matches sibling call semantics and the frame pointer has229 the same value it had on function entry.230 231 This rule is needed so that objtool can reliably analyze all of a232 function's code paths. If a function jumps to code in another file,233 and it's not a sibling call, objtool has no way to follow the jump234 because it only analyzes a single file at a time.235 2365. A callable function may not execute kernel entry/exit instructions.237 The only code which needs such instructions is kernel entry code,238 which shouldn't be be in callable functions anyway.239 240 This rule is just a sanity check to ensure that callable functions241 return normally.242 243 244Objtool warnings245----------------246 247NOTE: When requesting help with an objtool warning, please recreate with248OBJTOOL_VERBOSE=1 (e.g., "make OBJTOOL_VERBOSE=1") and send the full249output, including any disassembly or backtrace below the warning, to the250objtool maintainers.251 252For asm files, if you're getting an error which doesn't make sense,253first make sure that the affected code follows the above rules.254 255For C files, the common culprits are inline asm statements and calls to256"noreturn" functions. See below for more details.257 258Another possible cause for errors in C code is if the Makefile removes259-fno-omit-frame-pointer or adds -fomit-frame-pointer to the gcc options.260 261Here are some examples of common warnings reported by objtool, what262they mean, and suggestions for how to fix them. When in doubt, ping263the objtool maintainers.264 265 2661. file.o: warning: objtool: func()+0x128: call without frame pointer save/setup267 268 The func() function made a function call without first saving and/or269 updating the frame pointer, and CONFIG_FRAME_POINTER is enabled.270 271 If the error is for an asm file, and func() is indeed a callable272 function, add proper frame pointer logic using the FRAME_BEGIN and273 FRAME_END macros. Otherwise, if it's not a callable function, remove274 its ELF function annotation by changing ENDPROC to END, and instead275 use the manual unwind hint macros in asm/unwind_hints.h.276 277 If it's a GCC-compiled .c file, the error may be because the function278 uses an inline asm() statement which has a "call" instruction. An279 asm() statement with a call instruction must declare the use of the280 stack pointer in its output operand. On x86_64, this means adding281 the ASM_CALL_CONSTRAINT as an output constraint:282 283 asm volatile("call func" : ASM_CALL_CONSTRAINT);284 285 Otherwise the stack frame may not get created before the call.286 287 objtool can help with pinpointing the exact function where it happens:288 289 $ OBJTOOL_ARGS="--verbose" make arch/x86/kvm/290 291 arch/x86/kvm/kvm.o: warning: objtool: .altinstr_replacement+0xc5: call without frame pointer save/setup292 arch/x86/kvm/kvm.o: warning: objtool: em_loop.part.0+0x29: (alt)293 arch/x86/kvm/kvm.o: warning: objtool: em_loop.part.0+0x0: <=== (sym)294 LD [M] arch/x86/kvm/kvm-intel.o295 0000 0000000000028220 <em_loop.part.0>:296 0000 28220: 0f b6 47 61 movzbl 0x61(%rdi),%eax297 0004 28224: 3c e2 cmp $0xe2,%al298 0006 28226: 74 2c je 28254 <em_loop.part.0+0x34>299 0008 28228: 48 8b 57 10 mov 0x10(%rdi),%rdx300 000c 2822c: 83 f0 05 xor $0x5,%eax301 000f 2822f: 48 c1 e0 04 shl $0x4,%rax302 0013 28233: 25 f0 00 00 00 and $0xf0,%eax303 0018 28238: 81 e2 d5 08 00 00 and $0x8d5,%edx304 001e 2823e: 80 ce 02 or $0x2,%dh305 ...306 3072. file.o: warning: objtool: .text+0x53: unreachable instruction308 309 Objtool couldn't find a code path to reach the instruction.310 311 If the error is for an asm file, and the instruction is inside (or312 reachable from) a callable function, the function should be annotated313 with the ENTRY/ENDPROC macros (ENDPROC is the important one).314 Otherwise, the code should probably be annotated with the unwind hint315 macros in asm/unwind_hints.h so objtool and the unwinder can know the316 stack state associated with the code.317 318 If you're 100% sure the code won't affect stack traces, or if you're319 a just a bad person, you can tell objtool to ignore it. See the320 "Adding exceptions" section below.321 322 If it's not actually in a callable function (e.g. kernel entry code),323 change ENDPROC to END.324 3253. file.o: warning: objtool: foo+0x48c: bar() is missing a __noreturn annotation326 327 The call from foo() to bar() doesn't return, but bar() is missing the328 __noreturn annotation. NOTE: In addition to annotating the function329 with __noreturn, please also add it to tools/objtool/noreturns.h.330 3314. file.o: warning: objtool: func(): can't find starting instruction332 or333 file.o: warning: objtool: func()+0x11dd: can't decode instruction334 335 Does the file have data in a text section? If so, that can confuse336 objtool's instruction decoder. Move the data to a more appropriate337 section like .data or .rodata.338 339 3405. file.o: warning: objtool: func()+0x6: unsupported instruction in callable function341 342 This is a kernel entry/exit instruction like sysenter or iret. Such343 instructions aren't allowed in a callable function, and are most344 likely part of the kernel entry code. They should usually not have345 the callable function annotation (ENDPROC) and should always be346 annotated with the unwind hint macros in asm/unwind_hints.h.347 348 3496. file.o: warning: objtool: func()+0x26: sibling call from callable instruction with modified stack frame350 351 This is a dynamic jump or a jump to an undefined symbol. Objtool352 assumed it's a sibling call and detected that the frame pointer353 wasn't first restored to its original state.354 355 If it's not really a sibling call, you may need to move the356 destination code to the local file.357 358 If the instruction is not actually in a callable function (e.g.359 kernel entry code), change ENDPROC to END and annotate manually with360 the unwind hint macros in asm/unwind_hints.h.361 362 3637. file: warning: objtool: func()+0x5c: stack state mismatch364 365 The instruction's frame pointer state is inconsistent, depending on366 which execution path was taken to reach the instruction.367 368 Make sure that, when CONFIG_FRAME_POINTER is enabled, the function369 pushes and sets up the frame pointer (for x86_64, this means rbp) at370 the beginning of the function and pops it at the end of the function.371 Also make sure that no other code in the function touches the frame372 pointer.373 374 Another possibility is that the code has some asm or inline asm which375 does some unusual things to the stack or the frame pointer. In such376 cases it's probably appropriate to use the unwind hint macros in377 asm/unwind_hints.h.378 379 3808. file.o: warning: objtool: funcA() falls through to next function funcB()381 382 This means that funcA() doesn't end with a return instruction or an383 unconditional jump, and that objtool has determined that the function384 can fall through into the next function. There could be different385 reasons for this:386 387 1) funcA()'s last instruction is a call to a "noreturn" function like388 panic(). In this case the noreturn function needs to be added to389 objtool's hard-coded global_noreturns array. Feel free to bug the390 objtool maintainer, or you can submit a patch.391 392 2) funcA() uses the unreachable() annotation in a section of code393 that is actually reachable.394 395 3) If funcA() calls an inline function, the object code for funcA()396 might be corrupt due to a gcc bug. For more details, see:397 https://gcc.gnu.org/bugzilla/show_bug.cgi?id=70646398 3999. file.o: warning: objtool: funcA() call to funcB() with UACCESS enabled400 401 This means that an unexpected call to a non-whitelisted function exists402 outside of arch-specific guards.403 X86: SMAP (stac/clac): __uaccess_begin()/__uaccess_end()404 ARM: PAN: uaccess_enable()/uaccess_disable()405 406 These functions should be called to denote a minimal critical section around407 access to __user variables. See also: https://lwn.net/Articles/517475/408 409 The intention of the warning is to prevent calls to funcB() from eventually410 calling schedule(), potentially leaking the AC flags state, and not411 restoring them correctly.412 413 It also helps verify that there are no unexpected calls to funcB() which may414 access user space pages with protections against doing so disabled.415 416 To fix, either:417 1) remove explicit calls to funcB() from funcA().418 2) add the correct guards before and after calls to low level functions like419 __get_user_size()/__put_user_size().420 3) add funcB to uaccess_safe_builtin whitelist in tools/objtool/check.c, if421 funcB obviously does not call schedule(), and is marked notrace (since422 function tracing inserts additional calls, which is not obvious from the423 sources).424 42510. file.o: warning: func()+0x5c: stack layout conflict in alternatives426 427 This means that in the use of the alternative() or ALTERNATIVE()428 macro, the code paths have conflicting modifications to the stack.429 The problem is that there is only one ORC unwind table, which means430 that the ORC unwind entries must be consistent for all possible431 instruction boundaries regardless of which code has been patched.432 This limitation can be overcome by massaging the alternatives with433 NOPs to shift the stack changes around so they no longer conflict.434 43511. file.o: warning: unannotated intra-function call436 437 This warning means that a direct call is done to a destination which438 is not at the beginning of a function. If this is a legit call, you439 can remove this warning by putting the ANNOTATE_INTRA_FUNCTION_CALL440 directive right before the call.441 44212. file.o: warning: func(): not an indirect call target443 444 This means that objtool is running with --ibt and a function expected445 to be an indirect call target is not. In particular, this happens for446 init_module() or cleanup_module() if a module relies on these special447 names and does not use module_init() / module_exit() macros to create448 them.449 450 451If the error doesn't seem to make sense, it could be a bug in objtool.452Feel free to ask the objtool maintainer for help.453 454 455Adding exceptions456-----------------457 458If you _really_ need objtool to ignore something, and are 100% sure459that it won't affect kernel stack traces, you can tell objtool to460ignore it:461 462- To skip validation of a function, use the STACK_FRAME_NON_STANDARD463 macro.464 465- To skip validation of a file, add466 467 OBJECT_FILES_NON_STANDARD_filename.o := y468 469 to the Makefile.470 471- To skip validation of a directory, add472 473 OBJECT_FILES_NON_STANDARD := y474 475 to the Makefile.476 477NOTE: OBJECT_FILES_NON_STANDARD doesn't work for link time validation of478vmlinux.o or a linked module. So it should only be used for files which479aren't linked into vmlinux or a module.480