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 2882. file.o: warning: objtool: .text+0x53: unreachable instruction 289 290 Objtool couldn't find a code path to reach the instruction. 291 292 If the error is for an asm file, and the instruction is inside (or 293 reachable from) a callable function, the function should be annotated 294 with the ENTRY/ENDPROC macros (ENDPROC is the important one). 295 Otherwise, the code should probably be annotated with the unwind hint 296 macros in asm/unwind_hints.h so objtool and the unwinder can know the 297 stack state associated with the code. 298 299 If you're 100% sure the code won't affect stack traces, or if you're 300 a just a bad person, you can tell objtool to ignore it. See the 301 "Adding exceptions" section below. 302 303 If it's not actually in a callable function (e.g. kernel entry code), 304 change ENDPROC to END. 305 3063. file.o: warning: objtool: foo+0x48c: bar() is missing a __noreturn annotation 307 308 The call from foo() to bar() doesn't return, but bar() is missing the 309 __noreturn annotation. NOTE: In addition to annotating the function 310 with __noreturn, please also add it to tools/objtool/noreturns.h. 311 3124. file.o: warning: objtool: func(): can't find starting instruction 313 or 314 file.o: warning: objtool: func()+0x11dd: can't decode instruction 315 316 Does the file have data in a text section? If so, that can confuse 317 objtool's instruction decoder. Move the data to a more appropriate 318 section like .data or .rodata. 319 320 3215. file.o: warning: objtool: func()+0x6: unsupported instruction in callable function 322 323 This is a kernel entry/exit instruction like sysenter or iret. Such 324 instructions aren't allowed in a callable function, and are most 325 likely part of the kernel entry code. They should usually not have 326 the callable function annotation (ENDPROC) and should always be 327 annotated with the unwind hint macros in asm/unwind_hints.h. 328 329 3306. file.o: warning: objtool: func()+0x26: sibling call from callable instruction with modified stack frame 331 332 This is a dynamic jump or a jump to an undefined symbol. Objtool 333 assumed it's a sibling call and detected that the frame pointer 334 wasn't first restored to its original state. 335 336 If it's not really a sibling call, you may need to move the 337 destination code to the local file. 338 339 If the instruction is not actually in a callable function (e.g. 340 kernel entry code), change ENDPROC to END and annotate manually with 341 the unwind hint macros in asm/unwind_hints.h. 342 343 3447. file: warning: objtool: func()+0x5c: stack state mismatch 345 346 The instruction's frame pointer state is inconsistent, depending on 347 which execution path was taken to reach the instruction. 348 349 Make sure that, when CONFIG_FRAME_POINTER is enabled, the function 350 pushes and sets up the frame pointer (for x86_64, this means rbp) at 351 the beginning of the function and pops it at the end of the function. 352 Also make sure that no other code in the function touches the frame 353 pointer. 354 355 Another possibility is that the code has some asm or inline asm which 356 does some unusual things to the stack or the frame pointer. In such 357 cases it's probably appropriate to use the unwind hint macros in 358 asm/unwind_hints.h. 359 360 3618. file.o: warning: objtool: funcA() falls through to next function funcB() 362 363 This means that funcA() doesn't end with a return instruction or an 364 unconditional jump, and that objtool has determined that the function 365 can fall through into the next function. There could be different 366 reasons for this: 367 368 1) funcA()'s last instruction is a call to a "noreturn" function like 369 panic(). In this case the noreturn function needs to be added to 370 objtool's hard-coded global_noreturns array. Feel free to bug the 371 objtool maintainer, or you can submit a patch. 372 373 2) funcA() uses the unreachable() annotation in a section of code 374 that is actually reachable. 375 376 3) If funcA() calls an inline function, the object code for funcA() 377 might be corrupt due to a gcc bug. For more details, see: 378 https://gcc.gnu.org/bugzilla/show_bug.cgi?id=70646 379 3809. file.o: warning: objtool: funcA() call to funcB() with UACCESS enabled 381 382 This means that an unexpected call to a non-whitelisted function exists 383 outside of arch-specific guards. 384 X86: SMAP (stac/clac): __uaccess_begin()/__uaccess_end() 385 ARM: PAN: uaccess_enable()/uaccess_disable() 386 387 These functions should be called to denote a minimal critical section around 388 access to __user variables. See also: https://lwn.net/Articles/517475/ 389 390 The intention of the warning is to prevent calls to funcB() from eventually 391 calling schedule(), potentially leaking the AC flags state, and not 392 restoring them correctly. 393 394 It also helps verify that there are no unexpected calls to funcB() which may 395 access user space pages with protections against doing so disabled. 396 397 To fix, either: 398 1) remove explicit calls to funcB() from funcA(). 399 2) add the correct guards before and after calls to low level functions like 400 __get_user_size()/__put_user_size(). 401 3) add funcB to uaccess_safe_builtin whitelist in tools/objtool/check.c, if 402 funcB obviously does not call schedule(), and is marked notrace (since 403 function tracing inserts additional calls, which is not obvious from the 404 sources). 405 40610. file.o: warning: func()+0x5c: stack layout conflict in alternatives 407 408 This means that in the use of the alternative() or ALTERNATIVE() 409 macro, the code paths have conflicting modifications to the stack. 410 The problem is that there is only one ORC unwind table, which means 411 that the ORC unwind entries must be consistent for all possible 412 instruction boundaries regardless of which code has been patched. 413 This limitation can be overcome by massaging the alternatives with 414 NOPs to shift the stack changes around so they no longer conflict. 415 41611. file.o: warning: unannotated intra-function call 417 418 This warning means that a direct call is done to a destination which 419 is not at the beginning of a function. If this is a legit call, you 420 can remove this warning by putting the ANNOTATE_INTRA_FUNCTION_CALL 421 directive right before the call. 422 42312. file.o: warning: func(): not an indirect call target 424 425 This means that objtool is running with --ibt and a function expected 426 to be an indirect call target is not. In particular, this happens for 427 init_module() or cleanup_module() if a module relies on these special 428 names and does not use module_init() / module_exit() macros to create 429 them. 430 431 432If the error doesn't seem to make sense, it could be a bug in objtool. 433Feel free to ask the objtool maintainer for help. 434 435 436Adding exceptions 437----------------- 438 439If you _really_ need objtool to ignore something, and are 100% sure 440that it won't affect kernel stack traces, you can tell objtool to 441ignore it: 442 443- To skip validation of a function, use the STACK_FRAME_NON_STANDARD 444 macro. 445 446- To skip validation of a file, add 447 448 OBJECT_FILES_NON_STANDARD_filename.o := y 449 450 to the Makefile. 451 452- To skip validation of a directory, add 453 454 OBJECT_FILES_NON_STANDARD := y 455 456 to the Makefile. 457 458NOTE: OBJECT_FILES_NON_STANDARD doesn't work for link time validation of 459vmlinux.o or a linked module. So it should only be used for files which 460aren't linked into vmlinux or a module. 461