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- Non-instrumentation validation -- validates non-instrumentable 32 ("noinstr") code rules, preventing instrumentation in low-level C 33 entry code 34 35- Static call annotation -- annotates static call sites, enabling the 36 kernel to implement inline static calls, a faster alternative to some 37 indirect branches 38 39- Uaccess validation -- validates uaccess rules for a proper 40 implementation of Supervisor Mode Access Protection (SMAP) 41 42- Straight Line Speculation validation -- validates certain SLS 43 mitigations 44 45- Indirect Branch Tracking validation -- validates Intel CET IBT rules 46 to ensure that all functions referenced by function pointers have 47 corresponding ENDBR instructions 48 49- Indirect Branch Tracking annotation -- annotates unused ENDBR 50 instruction sites, enabling the kernel to "seal" them (replace them 51 with NOPs) to further harden IBT 52 53- Function entry annotation -- annotates function entries, enabling 54 kernel function tracing 55 56- Other toolchain hacks which will go unmentioned at this time... 57 58Each feature can be enabled individually or in combination using the 59objtool cmdline. 60 61 62Objects 63------- 64 65Typically, objtool runs on every translation unit (TU, aka ".o file") in 66the kernel. If a TU is part of a kernel module, the '--module' option 67is added. 68 69However: 70 71- If noinstr validation is enabled, it also runs on vmlinux.o, with all 72 options removed and '--noinstr' added. 73 74- If IBT or LTO is enabled, it doesn't run on TUs at all. Instead it 75 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/A 82 module: N/A 83 84 B) CONFIG_NOINSTR_VALIDATION=y && !(CONFIG_X86_KERNEL_IBT=y || CONFIG_LTO=y): 85 TU: objtool [--module] <options> // no --noinstr 86 vmlinux: objtool --noinstr // other options removed 87 module: N/A 88 89 C) CONFIG_X86_KERNEL_IBT=y || CONFIG_LTO=y: 90 TU: N/A 91 vmlinux: objtool --noinstr <options> 92 module: objtool --module --noinstr <options> 93 94 95Stack validation 96---------------- 97 98Objtool's stack validation feature analyzes every .o file and ensures 99the validity of its stack metadata. It enforces a set of rules on asm 100code and C inline assembly code so that stack traces can be reliable. 101 102For each function, it recursively follows all possible code paths and 103validates the correct frame pointer state at each instruction. 104 105It also follows code paths involving special sections, like 106.altinstructions, __jump_table, and __ex_table, which can add 107alternative execution paths to a given instruction (or set of 108instructions). Similarly, it knows how to follow switch statements, for 109which 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 kernels 114 115 Frame pointers are used for debugging purposes. They allow runtime 116 code and debug tools to be able to walk the stack to determine the 117 chain of function call sites that led to the currently executing 118 code. 119 120 For some architectures, frame pointers are enabled by 121 CONFIG_FRAME_POINTER. For some other architectures they may be 122 required by the ABI (sometimes referred to as "backchain pointers"). 123 124 For C code, gcc automatically generates instructions for setting up 125 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 by 128 hand, which most people don't do. So the end result is that 129 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, all 132 functions which call other functions must first create a stack frame 133 and update the frame pointer. If a first function doesn't properly 134 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 frame 138 pointers enabled: 139 140 [<ffffffff81812584>] dump_stack+0x4b/0x63 141 [<ffffffff812d6dc2>] cmdline_proc_show+0x12/0x30 142 [<ffffffff8127f568>] seq_read+0x108/0x3e0 143 [<ffffffff812cce62>] proc_reg_read+0x42/0x70 144 [<ffffffff81256197>] __vfs_read+0x37/0x100 145 [<ffffffff81256b16>] vfs_read+0x86/0x130 146 [<ffffffff81257898>] SyS_read+0x58/0xd0 147 [<ffffffff8181c1f2>] entry_SYSCALL_64_fastpath+0x12/0x76 148 149 It correctly shows that the caller of cmdline_proc_show() is 150 seq_read(). 151 152 If we remove the frame pointer logic from cmdline_proc_show() by 153 replacing the frame pointer related instructions with nops, here's 154 what it looks like instead: 155 156 [<ffffffff81812584>] dump_stack+0x4b/0x63 157 [<ffffffff812d6dc2>] cmdline_proc_show+0x12/0x30 158 [<ffffffff812cce62>] proc_reg_read+0x42/0x70 159 [<ffffffff81256197>] __vfs_read+0x37/0x100 160 [<ffffffff81256b16>] vfs_read+0x86/0x130 161 [<ffffffff81257898>] SyS_read+0x58/0xd0 162 [<ffffffff8181c1f2>] entry_SYSCALL_64_fastpath+0x12/0x76 163 164 Notice that cmdline_proc_show()'s caller, seq_read(), has been 165 skipped. Instead the stack trace seems to show that 166 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[*] be 170 skipped on a stack trace. 171 172 [*] unless an interrupt or exception has occurred at the very 173 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 been 175 destroyed. This is an inherent limitation of frame pointers. 176 177b) ORC (Oops Rewind Capability) unwind table generation 178 179 An alternative to frame pointers and DWARF, ORC unwind data can be 180 used to walk the stack. Unlike frame pointers, ORC data is out of 181 band. So it doesn't affect runtime performance and it can be 182 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 rate 187 188 Livepatch has an optional "consistency model", which is needed for 189 more complex patches. In order for the consistency model to work, 190 stack traces need to be reliable (or an unreliable condition needs to 191 be detectable). Objtool makes that possible. 192 193 For more details, see the livepatch documentation in the Linux kernel 194 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 ELF 199 function type. In asm code, this is typically done using the 200 ENTRY/ENDPROC macros. If objtool finds a return instruction 201 outside of a function, it flags an error since that usually indicates 202 callable code which should be annotated accordingly. 203 204 This rule is needed so that objtool can properly identify each 205 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 used 209 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 the 215 correct frame pointer logic, if required by CONFIG_FRAME_POINTER or 216 the architecture's back chain rules. This can by done in asm code 217 with the FRAME_BEGIN/FRAME_END macros. 218 219 This rule ensures that frame pointer based stack traces will work as 220 designed. If function A doesn't create a stack frame before calling 221 function B, the _caller_ of function A will be skipped on the stack 222 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; or 227 228 b) the jump matches sibling call semantics and the frame pointer has 229 the same value it had on function entry. 230 231 This rule is needed so that objtool can reliably analyze all of a 232 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 jump 234 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 functions 241 return normally. 242 243 244Objtool warnings 245---------------- 246 247NOTE: When requesting help with an objtool warning, please recreate with 248OBJTOOL_VERBOSE=1 (e.g., "make OBJTOOL_VERBOSE=1") and send the full 249output, including any disassembly or backtrace below the warning, to the 250objtool 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 to 256"noreturn" functions. See below for more details. 257 258Another possible cause for errors in C code is if the Makefile removes 259-fno-omit-frame-pointer or adds -fomit-frame-pointer to the gcc options. 260 261Here are some examples of common warnings reported by objtool, what 262they mean, and suggestions for how to fix them. When in doubt, ping 263the objtool maintainers. 264 265 2661. file.o: warning: objtool: func()+0x128: call without frame pointer save/setup 267 268 The func() function made a function call without first saving and/or 269 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 callable 272 function, add proper frame pointer logic using the FRAME_BEGIN and 273 FRAME_END macros. Otherwise, if it's not a callable function, remove 274 its ELF function annotation by changing ENDPROC to END, and instead 275 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 function 278 uses an inline asm() statement which has a "call" instruction. An 279 asm() statement with a call instruction must declare the use of the 280 stack pointer in its output operand. On x86_64, this means adding 281 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/setup 292 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.o 295 0000 0000000000028220 <em_loop.part.0>: 296 0000 28220: 0f b6 47 61 movzbl 0x61(%rdi),%eax 297 0004 28224: 3c e2 cmp $0xe2,%al 298 0006 28226: 74 2c je 28254 <em_loop.part.0+0x34> 299 0008 28228: 48 8b 57 10 mov 0x10(%rdi),%rdx 300 000c 2822c: 83 f0 05 xor $0x5,%eax 301 000f 2822f: 48 c1 e0 04 shl $0x4,%rax 302 0013 28233: 25 f0 00 00 00 and $0xf0,%eax 303 0018 28238: 81 e2 d5 08 00 00 and $0x8d5,%edx 304 001e 2823e: 80 ce 02 or $0x2,%dh 305 ... 306 3072. file.o: warning: objtool: .text+0x53: unreachable instruction 308 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 (or 312 reachable from) a callable function, the function should be annotated 313 with the ENTRY/ENDPROC macros (ENDPROC is the important one). 314 Otherwise, the code should probably be annotated with the unwind hint 315 macros in asm/unwind_hints.h so objtool and the unwinder can know the 316 stack state associated with the code. 317 318 If you're 100% sure the code won't affect stack traces, or if you're 319 a just a bad person, you can tell objtool to ignore it. See the 320 "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 annotation 326 327 The call from foo() to bar() doesn't return, but bar() is missing the 328 __noreturn annotation. NOTE: In addition to annotating the function 329 with __noreturn, please also add it to tools/objtool/noreturns.h. 330 3314. file.o: warning: objtool: func(): can't find starting instruction 332 or 333 file.o: warning: objtool: func()+0x11dd: can't decode instruction 334 335 Does the file have data in a text section? If so, that can confuse 336 objtool's instruction decoder. Move the data to a more appropriate 337 section like .data or .rodata. 338 339 3405. file.o: warning: objtool: func()+0x6: unsupported instruction in callable function 341 342 This is a kernel entry/exit instruction like sysenter or iret. Such 343 instructions aren't allowed in a callable function, and are most 344 likely part of the kernel entry code. They should usually not have 345 the callable function annotation (ENDPROC) and should always be 346 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 frame 350 351 This is a dynamic jump or a jump to an undefined symbol. Objtool 352 assumed it's a sibling call and detected that the frame pointer 353 wasn't first restored to its original state. 354 355 If it's not really a sibling call, you may need to move the 356 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 with 360 the unwind hint macros in asm/unwind_hints.h. 361 362 3637. file: warning: objtool: func()+0x5c: stack state mismatch 364 365 The instruction's frame pointer state is inconsistent, depending on 366 which execution path was taken to reach the instruction. 367 368 Make sure that, when CONFIG_FRAME_POINTER is enabled, the function 369 pushes and sets up the frame pointer (for x86_64, this means rbp) at 370 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 frame 372 pointer. 373 374 Another possibility is that the code has some asm or inline asm which 375 does some unusual things to the stack or the frame pointer. In such 376 cases it's probably appropriate to use the unwind hint macros in 377 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 an 383 unconditional jump, and that objtool has determined that the function 384 can fall through into the next function. There could be different 385 reasons for this: 386 387 1) funcA()'s last instruction is a call to a "noreturn" function like 388 panic(). In this case the noreturn function needs to be added to 389 objtool's hard-coded global_noreturns array. Feel free to bug the 390 objtool maintainer, or you can submit a patch. 391 392 2) funcA() uses the unreachable() annotation in a section of code 393 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=70646 398 3999. file.o: warning: objtool: funcA() call to funcB() with UACCESS enabled 400 401 This means that an unexpected call to a non-whitelisted function exists 402 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 around 407 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 eventually 410 calling schedule(), potentially leaking the AC flags state, and not 411 restoring them correctly. 412 413 It also helps verify that there are no unexpected calls to funcB() which may 414 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 like 419 __get_user_size()/__put_user_size(). 420 3) add funcB to uaccess_safe_builtin whitelist in tools/objtool/check.c, if 421 funcB obviously does not call schedule(), and is marked notrace (since 422 function tracing inserts additional calls, which is not obvious from the 423 sources). 424 42510. file.o: warning: func()+0x5c: stack layout conflict in alternatives 426 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 means 430 that the ORC unwind entries must be consistent for all possible 431 instruction boundaries regardless of which code has been patched. 432 This limitation can be overcome by massaging the alternatives with 433 NOPs to shift the stack changes around so they no longer conflict. 434 43511. file.o: warning: unannotated intra-function call 436 437 This warning means that a direct call is done to a destination which 438 is not at the beginning of a function. If this is a legit call, you 439 can remove this warning by putting the ANNOTATE_INTRA_FUNCTION_CALL 440 directive right before the call. 441 44212. file.o: warning: func(): not an indirect call target 443 444 This means that objtool is running with --ibt and a function expected 445 to be an indirect call target is not. In particular, this happens for 446 init_module() or cleanup_module() if a module relies on these special 447 names and does not use module_init() / module_exit() macros to create 448 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 exceptions 456----------------- 457 458If you _really_ need objtool to ignore something, and are 100% sure 459that it won't affect kernel stack traces, you can tell objtool to 460ignore it: 461 462- To skip validation of a function, use the STACK_FRAME_NON_STANDARD 463 macro. 464 465- To skip validation of a file, add 466 467 OBJECT_FILES_NON_STANDARD_filename.o := y 468 469 to the Makefile. 470 471- To skip validation of a directory, add 472 473 OBJECT_FILES_NON_STANDARD := y 474 475 to the Makefile. 476 477NOTE: OBJECT_FILES_NON_STANDARD doesn't work for link time validation of 478vmlinux.o or a linked module. So it should only be used for files which 479aren't linked into vmlinux or a module. 480