tools/objtool/Documentation/stack-validation.txt

   1 Compile-time stack metadata validation
   2 ======================================
   3
   4
   5 Overview
   6 --------
   7
   8 The kernel CONFIG_STACK_VALIDATION option enables a host tool named
   9 objtool which runs at compile time.  It has a "check" subcommand which
  10 analyzes every .o file and ensures the validity of its stack metadata.
  11 It enforces a set of rules on asm code and C inline assembly code so
  12 that stack traces can be reliable.
  13
  14 Currently it only checks frame pointer usage, but there are plans to add
  15 CFI validation for C files and CFI generation for asm files.
  16
  17 For each function, it recursively follows all possible code paths and
  18 validates the correct frame pointer state at each instruction.
  19
  20 It also follows code paths involving special sections, like
  21 .altinstructions, __jump_table, and __ex_table, which can add
  22 alternative execution paths to a given instruction (or set of
  23 instructions).  Similarly, it knows how to follow switch statements, for
  24 which gcc sometimes uses jump tables.
  25
  26
  27 Why do we need stack metadata validation?
  28 -----------------------------------------
  29
  30 Here are some of the benefits of validating stack metadata:
  31
  32 a) More reliable stack traces for frame pointer enabled kernels
  33
  34    Frame pointers are used for debugging purposes.  They allow runtime
  35    code and debug tools to be able to walk the stack to determine the
  36    chain of function call sites that led to the currently executing
  37    code.
  38
  39    For some architectures, frame pointers are enabled by
  40    CONFIG_FRAME_POINTER.  For some other architectures they may be
  41    required by the ABI (sometimes referred to as "backchain pointers").
  42
  43    For C code, gcc automatically generates instructions for setting up
  44    frame pointers when the -fno-omit-frame-pointer option is used.
  45
  46    But for asm code, the frame setup instructions have to be written by
  47    hand, which most people don't do.  So the end result is that
  48    CONFIG_FRAME_POINTER is honored for C code but not for most asm code.
  49
  50    For stack traces based on frame pointers to be reliable, all
  51    functions which call other functions must first create a stack frame
  52    and update the frame pointer.  If a first function doesn't properly
  53    create a stack frame before calling a second function, the *caller*
  54    of the first function will be skipped on the stack trace.
  55
  56    For example, consider the following example backtrace with frame
  57    pointers enabled:
  58
  59      [<ffffffff81812584>] dump_stack+0x4b/0x63
  60      [<ffffffff812d6dc2>] cmdline_proc_show+0x12/0x30
  61      [<ffffffff8127f568>] seq_read+0x108/0x3e0
  62      [<ffffffff812cce62>] proc_reg_read+0x42/0x70
  63      [<ffffffff81256197>] __vfs_read+0x37/0x100
  64      [<ffffffff81256b16>] vfs_read+0x86/0x130
  65      [<ffffffff81257898>] SyS_read+0x58/0xd0
  66      [<ffffffff8181c1f2>] entry_SYSCALL_64_fastpath+0x12/0x76
  67
  68    It correctly shows that the caller of cmdline_proc_show() is
  69    seq_read().
  70
  71    If we remove the frame pointer logic from cmdline_proc_show() by
  72    replacing the frame pointer related instructions with nops, here's
  73    what it looks like instead:
  74
  75      [<ffffffff81812584>] dump_stack+0x4b/0x63
  76      [<ffffffff812d6dc2>] cmdline_proc_show+0x12/0x30
  77      [<ffffffff812cce62>] proc_reg_read+0x42/0x70
  78      [<ffffffff81256197>] __vfs_read+0x37/0x100
  79      [<ffffffff81256b16>] vfs_read+0x86/0x130
  80      [<ffffffff81257898>] SyS_read+0x58/0xd0
  81      [<ffffffff8181c1f2>] entry_SYSCALL_64_fastpath+0x12/0x76
  82
  83    Notice that cmdline_proc_show()'s caller, seq_read(), has been
  84    skipped.  Instead the stack trace seems to show that
  85    cmdline_proc_show() was called by proc_reg_read().
  86
  87    The benefit of objtool here is that because it ensures that *all*
  88    functions honor CONFIG_FRAME_POINTER, no functions will ever[*] be
  89    skipped on a stack trace.
  90
  91    [*] unless an interrupt or exception has occurred at the very
  92        beginning of a function before the stack frame has been created,
  93        or at the very end of the function after the stack frame has been
  94        destroyed.  This is an inherent limitation of frame pointers.
  95
  96 b) 100% reliable stack traces for DWARF enabled kernels
  97
  98    (NOTE: This is not yet implemented)
  99
 100    As an alternative to frame pointers, DWARF Call Frame Information
 101    (CFI) metadata can be used to walk the stack.  Unlike frame pointers,
 102    CFI metadata is out of band.  So it doesn't affect runtime
 103    performance and it can be reliable even when interrupts or exceptions
 104    are involved.
 105
 106    For C code, gcc automatically generates DWARF CFI metadata.  But for
 107    asm code, generating CFI is a tedious manual approach which requires
 108    manually placed .cfi assembler macros to be scattered throughout the
 109    code.  It's clumsy and very easy to get wrong, and it makes the real
 110    code harder to read.
 111
 112    Stacktool will improve this situation in several ways.  For code
 113    which already has CFI annotations, it will validate them.  For code
 114    which doesn't have CFI annotations, it will generate them.  So an
 115    architecture can opt to strip out all the manual .cfi annotations
 116    from their asm code and have objtool generate them instead.
 117
 118    We might also add a runtime stack validation debug option where we
 119    periodically walk the stack from schedule() and/or an NMI to ensure
 120    that the stack metadata is sane and that we reach the bottom of the
 121    stack.
 122
 123    So the benefit of objtool here will be that external tooling should
 124    always show perfect stack traces.  And the same will be true for
 125    kernel warning/oops traces if the architecture has a runtime DWARF
 126    unwinder.
 127
 128 c) Higher live patching compatibility rate
 129
 130    (NOTE: This is not yet implemented)
 131
 132    Currently with CONFIG_LIVEPATCH there's a basic live patching
 133    framework which is safe for roughly 85-90% of "security" fixes.  But
 134    patches can't have complex features like function dependency or
 135    prototype changes, or data structure changes.
 136
 137    There's a strong need to support patches which have the more complex
 138    features so that the patch compatibility rate for security fixes can
 139    eventually approach something resembling 100%.  To achieve that, a
 140    "consistency model" is needed, which allows tasks to be safely
 141    transitioned from an unpatched state to a patched state.
 142
 143    One of the key requirements of the currently proposed livepatch
 144    consistency model [*] is that it needs to walk the stack of each
 145    sleeping task to determine if it can be transitioned to the patched
 146    state.  If objtool can ensure that stack traces are reliable, this
 147    consistency model can be used and the live patching compatibility
 148    rate can be improved significantly.
 149
 150    [*] https://lkml.kernel.org/r/cover.1423499826.git.jpoimboe@redhat.com
 151
 152
 153 Rules
 154 -----
 155
 156 To achieve the validation, objtool enforces the following rules:
 157
 158 1. Each callable function must be annotated as such with the ELF
 159    function type.  In asm code, this is typically done using the
 160    ENTRY/ENDPROC macros.  If objtool finds a return instruction
 161    outside of a function, it flags an error since that usually indicates
 162    callable code which should be annotated accordingly.
 163
 164    This rule is needed so that objtool can properly identify each
 165    callable function in order to analyze its stack metadata.
 166
 167 2. Conversely, each section of code which is *not* callable should *not*
 168    be annotated as an ELF function.  The ENDPROC macro shouldn't be used
 169    in this case.
 170
 171    This rule is needed so that objtool can ignore non-callable code.
 172    Such code doesn't have to follow any of the other rules.
 173
 174 3. Each callable function which calls another function must have the
 175    correct frame pointer logic, if required by CONFIG_FRAME_POINTER or
 176    the architecture's back chain rules.  This can by done in asm code
 177    with the FRAME_BEGIN/FRAME_END macros.
 178
 179    This rule ensures that frame pointer based stack traces will work as
 180    designed.  If function A doesn't create a stack frame before calling
 181    function B, the _caller_ of function A will be skipped on the stack
 182    trace.
 183
 184 4. Dynamic jumps and jumps to undefined symbols are only allowed if:
 185
 186    a) the jump is part of a switch statement; or
 187
 188    b) the jump matches sibling call semantics and the frame pointer has
 189       the same value it had on function entry.
 190
 191    This rule is needed so that objtool can reliably analyze all of a
 192    function's code paths.  If a function jumps to code in another file,
 193    and it's not a sibling call, objtool has no way to follow the jump
 194    because it only analyzes a single file at a time.
 195
 196 5. A callable function may not execute kernel entry/exit instructions.
 197    The only code which needs such instructions is kernel entry code,
 198    which shouldn't be be in callable functions anyway.
 199
 200    This rule is just a sanity check to ensure that callable functions
 201    return normally.
 202
 203
 204 Errors in .S files
 205 ------------------
 206
 207 If you're getting an error in a compiled .S file which you don't
 208 understand, first make sure that the affected code follows the above
 209 rules.
 210
 211 Here are some examples of common warnings reported by objtool, what
 212 they mean, and suggestions for how to fix them.
 213
 214
 215 1. asm_file.o: warning: objtool: func()+0x128: call without frame pointer save/setup
 216
 217    The func() function made a function call without first saving and/or
 218    updating the frame pointer.
 219
 220    If func() is indeed a callable function, add proper frame pointer
 221    logic using the FRAME_BEGIN and FRAME_END macros.  Otherwise, remove
 222    its ELF function annotation by changing ENDPROC to END.
 223
 224    If you're getting this error in a .c file, see the "Errors in .c
 225    files" section.
 226
 227
 228 2. asm_file.o: warning: objtool: .text+0x53: return instruction outside of a callable function
 229
 230    A return instruction was detected, but objtool couldn't find a way
 231    for a callable function to reach the instruction.
 232
 233    If the return instruction is inside (or reachable from) a callable
 234    function, the function needs to be annotated with the ENTRY/ENDPROC
 235    macros.
 236
 237    If you _really_ need a return instruction outside of a function, and
 238    are 100% sure that it won't affect stack traces, you can tell
 239    objtool to ignore it.  See the "Adding exceptions" section below.
 240
 241
 242 3. asm_file.o: warning: objtool: func()+0x9: function has unreachable instruction
 243
 244    The instruction lives inside of a callable function, but there's no
 245    possible control flow path from the beginning of the function to the
 246    instruction.
 247
 248    If the instruction is actually needed, and it's actually in a
 249    callable function, ensure that its function is properly annotated
 250    with ENTRY/ENDPROC.
 251
 252    If it's not actually in a callable function (e.g. kernel entry code),
 253    change ENDPROC to END.
 254
 255
 256 4. asm_file.o: warning: objtool: func(): can't find starting instruction
 257    or
 258    asm_file.o: warning: objtool: func()+0x11dd: can't decode instruction
 259
 260    Did you put data in a text section?  If so, that can confuse
 261    objtool's instruction decoder.  Move the data to a more appropriate
 262    section like .data or .rodata.
 263
 264
 265 5. asm_file.o: warning: objtool: func()+0x6: kernel entry/exit from callable instruction
 266
 267    This is a kernel entry/exit instruction like sysenter or sysret.
 268    Such instructions aren't allowed in a callable function, and are most
 269    likely part of the kernel entry code.
 270
 271    If the instruction isn't actually in a callable function, change
 272    ENDPROC to END.
 273
 274
 275 6. asm_file.o: warning: objtool: func()+0x26: sibling call from callable instruction with changed frame pointer
 276
 277    This is a dynamic jump or a jump to an undefined symbol.  Stacktool
 278    assumed it's a sibling call and detected that the frame pointer
 279    wasn't first restored to its original state.
 280
 281    If it's not really a sibling call, you may need to move the
 282    destination code to the local file.
 283
 284    If the instruction is not actually in a callable function (e.g.
 285    kernel entry code), change ENDPROC to END.
 286
 287
 288 7. asm_file: warning: objtool: func()+0x5c: frame pointer state mismatch
 289
 290    The instruction's frame pointer state is inconsistent, depending on
 291    which execution path was taken to reach the instruction.
 292
 293    Make sure the function pushes and sets up the frame pointer (for
 294    x86_64, this means rbp) at the beginning of the function and pops it
 295    at the end of the function.  Also make sure that no other code in the
 296    function touches the frame pointer.
 297
 298
 299 Errors in .c files
 300 ------------------
 301
 302 If you're getting an objtool error in a compiled .c file, chances are
 303 the file uses an asm() statement which has a "call" instruction.  An
 304 asm() statement with a call instruction must declare the use of the
 305 stack pointer in its output operand.  For example, on x86_64:
 306
 307    register void *__sp asm("rsp");
 308    asm volatile("call func" : "+r" (__sp));
 309
 310 Otherwise the stack frame may not get created before the call.
 311
 312 Another possible cause for errors in C code is if the Makefile removes
 313 -fno-omit-frame-pointer or adds -fomit-frame-pointer to the gcc options.
 314
 315 Also see the above section for .S file errors for more information what
 316 the individual error messages mean.
 317
 318 If the error doesn't seem to make sense, it could be a bug in objtool.
 319 Feel free to ask the objtool maintainer for help.
 320
 321
 322 Adding exceptions
 323 -----------------
 324
 325 If you _really_ need objtool to ignore something, and are 100% sure
 326 that it won't affect kernel stack traces, you can tell objtool to
 327 ignore it:
 328
 329 - To skip validation of a function, use the STACK_FRAME_NON_STANDARD
 330   macro.
 331
 332 - To skip validation of a file, add
 333
 334     OBJECT_FILES_NON_STANDARD_filename.o := n
 335
 336   to the Makefile.
 337
 338 - To skip validation of a directory, add
 339
 340     OBJECT_FILES_NON_STANDARD := y
 341
 342   to the Makefile.