1 Objtool
2 =======
3
4 The kernel CONFIG_OBJTOOL option enables a hos
5 which runs at compile time. It can do various
6 transformations on .o files.
7
8 Objtool has become an integral part of the x86
9 kernel depends on it for a variety of security
10 (and other types of features as well).
11
12
13 Features
14 --------
15
16 Objtool has the following features:
17
18 - Stack unwinding metadata validation -- usefu
19 stack traces are reliable for live patching
20
21 - ORC unwinder metadata generation -- a faster
22 alternative to frame pointer based unwinding
23
24 - Retpoline validation -- ensures that all ind
25 retpoline thunks, for Spectre v2 mitigations
26
27 - Retpoline call site annotation -- annotates
28 sites, enabling the kernel to patch them inl
29 funneling" for both security and performance
30
31 - Non-instrumentation validation -- validates
32 ("noinstr") code rules, preventing instrumen
33 entry code
34
35 - Static call annotation -- annotates static c
36 kernel to implement inline static calls, a f
37 indirect branches
38
39 - Uaccess validation -- validates uaccess rule
40 implementation of Supervisor Mode Access Pro
41
42 - Straight Line Speculation validation -- vali
43 mitigations
44
45 - Indirect Branch Tracking validation -- valid
46 to ensure that all functions referenced by f
47 corresponding ENDBR instructions
48
49 - Indirect Branch Tracking annotation -- annot
50 instruction sites, enabling the kernel to "s
51 with NOPs) to further harden IBT
52
53 - Function entry annotation -- annotates funct
54 kernel function tracing
55
56 - Other toolchain hacks which will go unmentio
57
58 Each feature can be enabled individually or in
59 objtool cmdline.
60
61
62 Objects
63 -------
64
65 Typically, objtool runs on every translation u
66 the kernel. If a TU is part of a kernel modul
67 is added.
68
69 However:
70
71 - If noinstr validation is enabled, it also ru
72 options removed and '--noinstr' added.
73
74 - If IBT or LTO is enabled, it doesn't run on
75 runs on vmlinux.o and linked modules, with a
76
77 In 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_X
85 TU: objtool [--module] <options>
86 vmlinux: objtool --noinstr
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 <o
93
94
95 Stack validation
96 ----------------
97
98 Objtool's stack validation feature analyzes ev
99 the validity of its stack metadata. It enforc
100 code and C inline assembly code so that stack
101
102 For each function, it recursively follows all
103 validates the correct frame pointer state at e
104
105 It also follows code paths involving special s
106 .altinstructions, __jump_table, and __ex_table
107 alternative execution paths to a given instruc
108 instructions). Similarly, it knows how to fol
109 which gcc sometimes uses jump tables.
110
111 Here are some of the benefits of validating st
112
113 a) More reliable stack traces for frame pointe
114
115 Frame pointers are used for debugging purpo
116 code and debug tools to be able to walk the
117 chain of function call sites that led to th
118 code.
119
120 For some architectures, frame pointers are
121 CONFIG_FRAME_POINTER. For some other archi
122 required by the ABI (sometimes referred to
123
124 For C code, gcc automatically generates ins
125 frame pointers when the -fno-omit-frame-poi
126
127 But for asm code, the frame setup instructi
128 hand, which most people don't do. So the e
129 CONFIG_FRAME_POINTER is honored for C code
130
131 For stack traces based on frame pointers to
132 functions which call other functions must f
133 and update the frame pointer. If a first f
134 create a stack frame before calling a secon
135 of the first function will be skipped on th
136
137 For example, consider the following example
138 pointers enabled:
139
140 [<ffffffff81812584>] dump_stack+0x4b/0x63
141 [<ffffffff812d6dc2>] cmdline_proc_show+0x
142 [<ffffffff8127f568>] seq_read+0x108/0x3e0
143 [<ffffffff812cce62>] proc_reg_read+0x42/0
144 [<ffffffff81256197>] __vfs_read+0x37/0x10
145 [<ffffffff81256b16>] vfs_read+0x86/0x130
146 [<ffffffff81257898>] SyS_read+0x58/0xd0
147 [<ffffffff8181c1f2>] entry_SYSCALL_64_fas
148
149 It correctly shows that the caller of cmdli
150 seq_read().
151
152 If we remove the frame pointer logic from c
153 replacing the frame pointer related instruc
154 what it looks like instead:
155
156 [<ffffffff81812584>] dump_stack+0x4b/0x63
157 [<ffffffff812d6dc2>] cmdline_proc_show+0x
158 [<ffffffff812cce62>] proc_reg_read+0x42/0
159 [<ffffffff81256197>] __vfs_read+0x37/0x10
160 [<ffffffff81256b16>] vfs_read+0x86/0x130
161 [<ffffffff81257898>] SyS_read+0x58/0xd0
162 [<ffffffff8181c1f2>] entry_SYSCALL_64_fas
163
164 Notice that cmdline_proc_show()'s caller, s
165 skipped. Instead the stack trace seems to
166 cmdline_proc_show() was called by proc_reg_
167
168 The benefit of objtool here is that because
169 functions honor CONFIG_FRAME_POINTER, no fu
170 skipped on a stack trace.
171
172 [*] unless an interrupt or exception has oc
173 beginning of a function before the stac
174 or at the very end of the function afte
175 destroyed. This is an inherent limitat
176
177 b) ORC (Oops Rewind Capability) unwind table g
178
179 An alternative to frame pointers and DWARF,
180 used to walk the stack. Unlike frame point
181 band. So it doesn't affect runtime perform
182 reliable even when interrupts or exceptions
183
184 For more details, see Documentation/arch/x8
185
186 c) Higher live patching compatibility rate
187
188 Livepatch has an optional "consistency mode
189 more complex patches. In order for the con
190 stack traces need to be reliable (or an unr
191 be detectable). Objtool makes that possibl
192
193 For more details, see the livepatch documen
194 source tree at Documentation/livepatch/live
195
196 To achieve the validation, objtool enforces th
197
198 1. Each callable function must be annotated as
199 function type. In asm code, this is typica
200 ENTRY/ENDPROC macros. If objtool finds a r
201 outside of a function, it flags an error si
202 callable code which should be annotated acc
203
204 This rule is needed so that objtool can pro
205 callable function in order to analyze its s
206
207 2. Conversely, each section of code which is *
208 be annotated as an ELF function. The ENDPR
209 in this case.
210
211 This rule is needed so that objtool can ign
212 Such code doesn't have to follow any of the
213
214 3. Each callable function which calls another
215 correct frame pointer logic, if required by
216 the architecture's back chain rules. This
217 with the FRAME_BEGIN/FRAME_END macros.
218
219 This rule ensures that frame pointer based
220 designed. If function A doesn't create a s
221 function B, the _caller_ of function A will
222 trace.
223
224 4. Dynamic jumps and jumps to undefined symbol
225
226 a) the jump is part of a switch statement;
227
228 b) the jump matches sibling call semantics
229 the same value it had on function entry.
230
231 This rule is needed so that objtool can rel
232 function's code paths. If a function jumps
233 and it's not a sibling call, objtool has no
234 because it only analyzes a single file at a
235
236 5. A callable function may not execute kernel
237 The only code which needs such instructions
238 which shouldn't be be in callable functions
239
240 This rule is just a sanity check to ensure
241 return normally.
242
243
244 Objtool warnings
245 ----------------
246
247 NOTE: When requesting help with an objtool war
248 OBJTOOL_VERBOSE=1 (e.g., "make OBJTOOL_VERBOSE
249 output, including any disassembly or backtrace
250 objtool maintainers.
251
252 For asm files, if you're getting an error whic
253 first make sure that the affected code follows
254
255 For C files, the common culprits are inline as
256 "noreturn" functions. See below for more deta
257
258 Another possible cause for errors in C code is
259 -fno-omit-frame-pointer or adds -fomit-frame-p
260
261 Here are some examples of common warnings repo
262 they mean, and suggestions for how to fix them
263 the objtool maintainers.
264
265
266 1. file.o: warning: objtool: func()+0x128: cal
267
268 The func() function made a function call wi
269 updating the frame pointer, and CONFIG_FRAM
270
271 If the error is for an asm file, and func()
272 function, add proper frame pointer logic us
273 FRAME_END macros. Otherwise, if it's not a
274 its ELF function annotation by changing END
275 use the manual unwind hint macros in asm/un
276
277 If it's a GCC-compiled .c file, the error m
278 uses an inline asm() statement which has a
279 asm() statement with a call instruction mus
280 stack pointer in its output operand. On x8
281 the ASM_CALL_CONSTRAINT as an output constr
282
283 asm volatile("call func" : ASM_CALL_CONST
284
285 Otherwise the stack frame may not get creat
286
287 objtool can help with pinpointing the exact
288
289 $ OBJTOOL_ARGS="--verbose" make arch/x86/kv
290
291 arch/x86/kvm/kvm.o: warning: objtool: .alti
292 arch/x86/kvm/kvm.o: warning: objtool: em_
293 arch/x86/kvm/kvm.o: warning: objtool: em_
294 LD [M] arch/x86/kvm/kvm-intel.o
295 0000 0000000000028220 <em_loop.part.0>:
296 0000 28220: 0f b6 47 61 mov
297 0004 28224: 3c e2 cmp
298 0006 28226: 74 2c je
299 0008 28228: 48 8b 57 10 mov
300 000c 2822c: 83 f0 05 xor
301 000f 2822f: 48 c1 e0 04 shl
302 0013 28233: 25 f0 00 00 00 and
303 0018 28238: 81 e2 d5 08 00 00 and
304 001e 2823e: 80 ce 02 or
305 ...
306
307 2. file.o: warning: objtool: .text+0x53: unrea
308
309 Objtool couldn't find a code path to reach
310
311 If the error is for an asm file, and the in
312 reachable from) a callable function, the fu
313 with the ENTRY/ENDPROC macros (ENDPROC is t
314 Otherwise, the code should probably be anno
315 macros in asm/unwind_hints.h so objtool and
316 stack state associated with the code.
317
318 If you're 100% sure the code won't affect s
319 a just a bad person, you can tell objtool t
320 "Adding exceptions" section below.
321
322 If it's not actually in a callable function
323 change ENDPROC to END.
324
325 3. file.o: warning: objtool: foo+0x48c: bar()
326
327 The call from foo() to bar() doesn't return
328 __noreturn annotation. NOTE: In addition t
329 with __noreturn, please also add it to tool
330
331 4. file.o: warning: objtool: func(): can't fin
332 or
333 file.o: warning: objtool: func()+0x11dd: ca
334
335 Does the file have data in a text section?
336 objtool's instruction decoder. Move the da
337 section like .data or .rodata.
338
339
340 5. file.o: warning: objtool: func()+0x6: unsup
341
342 This is a kernel entry/exit instruction lik
343 instructions aren't allowed in a callable f
344 likely part of the kernel entry code. They
345 the callable function annotation (ENDPROC)
346 annotated with the unwind hint macros in as
347
348
349 6. file.o: warning: objtool: func()+0x26: sibl
350
351 This is a dynamic jump or a jump to an unde
352 assumed it's a sibling call and detected th
353 wasn't first restored to its original state
354
355 If it's not really a sibling call, you may
356 destination code to the local file.
357
358 If the instruction is not actually in a cal
359 kernel entry code), change ENDPROC to END a
360 the unwind hint macros in asm/unwind_hints.
361
362
363 7. file: warning: objtool: func()+0x5c: stack
364
365 The instruction's frame pointer state is in
366 which execution path was taken to reach the
367
368 Make sure that, when CONFIG_FRAME_POINTER i
369 pushes and sets up the frame pointer (for x
370 the beginning of the function and pops it a
371 Also make sure that no other code in the fu
372 pointer.
373
374 Another possibility is that the code has so
375 does some unusual things to the stack or th
376 cases it's probably appropriate to use the
377 asm/unwind_hints.h.
378
379
380 8. file.o: warning: objtool: funcA() falls thr
381
382 This means that funcA() doesn't end with a
383 unconditional jump, and that objtool has de
384 can fall through into the next function. T
385 reasons for this:
386
387 1) funcA()'s last instruction is a call to
388 panic(). In this case the noreturn func
389 objtool's hard-coded global_noreturns ar
390 objtool maintainer, or you can submit a
391
392 2) funcA() uses the unreachable() annotatio
393 that is actually reachable.
394
395 3) If funcA() calls an inline function, the
396 might be corrupt due to a gcc bug. For
397 https://gcc.gnu.org/bugzilla/show_bug.cg
398
399 9. file.o: warning: objtool: funcA() call to f
400
401 This means that an unexpected call to a non
402 outside of arch-specific guards.
403 X86: SMAP (stac/clac): __uaccess_begin()/__
404 ARM: PAN: uaccess_enable()/uaccess_disable(
405
406 These functions should be called to denote
407 access to __user variables. See also: https
408
409 The intention of the warning is to prevent
410 calling schedule(), potentially leaking the
411 restoring them correctly.
412
413 It also helps verify that there are no unex
414 access user space pages with protections ag
415
416 To fix, either:
417 1) remove explicit calls to funcB() from fu
418 2) add the correct guards before and after
419 __get_user_size()/__put_user_size().
420 3) add funcB to uaccess_safe_builtin whitel
421 funcB obviously does not call schedule()
422 function tracing inserts additional call
423 sources).
424
425 10. file.o: warning: func()+0x5c: stack layout
426
427 This means that in the use of the alternat
428 macro, the code paths have conflicting mod
429 The problem is that there is only one ORC
430 that the ORC unwind entries must be consis
431 instruction boundaries regardless of which
432 This limitation can be overcome by massagi
433 NOPs to shift the stack changes around so
434
435 11. file.o: warning: unannotated intra-functio
436
437 This warning means that a direct call is do
438 is not at the beginning of a function. If t
439 can remove this warning by putting the ANNO
440 directive right before the call.
441
442 12. file.o: warning: func(): not an indirect c
443
444 This means that objtool is running with --i
445 to be an indirect call target is not. In pa
446 init_module() or cleanup_module() if a modu
447 names and does not use module_init() / modu
448 them.
449
450
451 If the error doesn't seem to make sense, it co
452 Feel free to ask the objtool maintainer for he
453
454
455 Adding exceptions
456 -----------------
457
458 If you _really_ need objtool to ignore somethi
459 that it won't affect kernel stack traces, you
460 ignore it:
461
462 - To skip validation of a function, use the ST
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
477 NOTE: OBJECT_FILES_NON_STANDARD doesn't work f
478 vmlinux.o or a linked module. So it should on
479 aren't linked into vmlinux or a module.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.