tools/objtool/Documentation/objtool.txt

Source file repositories/reference/linux-study-clean/tools/objtool/Documentation/objtool.txt

File Facts

System
Linux kernel
Corpus path
tools/objtool/Documentation/objtool.txt
Extension
.txt
Size
19769 bytes
Lines
489
Domain
Support Tooling And Documentation
Bucket
tools
Inferred role
Support Tooling And Documentation: exported/initcall integration point
Status
integration implementation candidate

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

[<ffffffff81256b16>] vfs_read+0x86/0x130
     [<ffffffff81257898>] SyS_read+0x58/0xd0
     [<ffffffff8181c1f2>] entry_SYSCALL_64_fastpath+0x12/0x76

   It correctly shows that the caller of cmdline_proc_show() is
   seq_read().

   If we remove the frame pointer logic from cmdline_proc_show() by
   replacing the frame pointer related instructions with nops, here's
   what it looks like instead:

     [<ffffffff81812584>] dump_stack+0x4b/0x63
     [<ffffffff812d6dc2>] cmdline_proc_show+0x12/0x30
     [<ffffffff812cce62>] proc_reg_read+0x42/0x70
     [<ffffffff81256197>] __vfs_read+0x37/0x100
     [<ffffffff81256b16>] vfs_read+0x86/0x130
     [<ffffffff81257898>] SyS_read+0x58/0xd0
     [<ffffffff8181c1f2>] entry_SYSCALL_64_fastpath+0x12/0x76

   Notice that cmdline_proc_show()'s caller, seq_read(), has been
   skipped.  Instead the stack trace seems to show that
   cmdline_proc_show() was called by proc_reg_read().

   The benefit of objtool here is that because it ensures that *all*
   functions honor CONFIG_FRAME_POINTER, no functions will ever[*] be
   skipped on a stack trace.

   [*] unless an interrupt or exception has occurred at the very
       beginning of a function before the stack frame has been created,
       or at the very end of the function after the stack frame has been
       destroyed.  This is an inherent limitation of frame pointers.

b) ORC (Oops Rewind Capability) unwind table generation

   An alternative to frame pointers and DWARF, ORC unwind data can be
   used to walk the stack.  Unlike frame pointers, ORC data is out of
   band.  So it doesn't affect runtime performance and it can be
   reliable even when interrupts or exceptions are involved.

   For more details, see Documentation/arch/x86/orc-unwinder.rst.

c) Higher live patching compatibility rate

   Livepatch has an optional "consistency model", which is needed for
   more complex patches.  In order for the consistency model to work,
   stack traces need to be reliable (or an unreliable condition needs to
   be detectable).  Objtool makes that possible.

   For more details, see the livepatch documentation in the Linux kernel
   source tree at Documentation/livepatch/livepatch.rst.

To achieve the validation, objtool enforces the following rules:

1. Each callable function must be annotated as such with the ELF
   function type.  In asm code, this is typically done using the
   SYM_FUNC_{START,END} macros.  If objtool finds a return instruction
   outside of a function, it flags an error since that usually indicates
   callable code which should be annotated accordingly.

   This rule is needed so that objtool can properly identify each
   callable function in order to analyze its stack metadata.

2. Conversely, each section of code which is *not* callable, or is
   otherwise doing funny things with the stack or registers, should
   *not* be annotated as an ELF function.  Rather, SYM_CODE_{START,END}
   should be used along with unwind hints.

3. Each callable function which calls another function must have the
   correct frame pointer logic, if required by CONFIG_FRAME_POINTER or
   the architecture's back chain rules.  This can by done in asm code

Annotation

Implementation Notes