diff options
Diffstat (limited to '')
| -rw-r--r-- | Documentation/core-api/asm-annotations.rst (renamed from Documentation/asm-annotations.rst) | 25 |
1 files changed, 15 insertions, 10 deletions
diff --git a/Documentation/asm-annotations.rst b/Documentation/core-api/asm-annotations.rst index 32ea57483378..bc514ed59887 100644 --- a/Documentation/asm-annotations.rst +++ b/Documentation/core-api/asm-annotations.rst @@ -43,10 +43,11 @@ annotated objects like this, tools can be run on them to generate more useful information. In particular, on properly annotated objects, ``objtool`` can be run to check and fix the object if needed. Currently, ``objtool`` can report missing frame pointer setup/destruction in functions. It can also -automatically generate annotations for :doc:`ORC unwinder <x86/orc-unwinder>` +automatically generate annotations for the ORC unwinder +(Documentation/x86/orc-unwinder.rst) for most code. Both of these are especially important to support reliable -stack traces which are in turn necessary for :doc:`Kernel live patching -<livepatch/livepatch>`. +stack traces which are in turn necessary for kernel live patching +(Documentation/livepatch/livepatch.rst). Caveat and Discussion --------------------- @@ -64,7 +65,7 @@ macros, it was decided that brand new macros should be introduced instead:: of importing all the crappy, historic, essentially randomly chosen debug symbol macro names from the binutils and older kernels? -.. _discussion: https://lkml.kernel.org/r/20170217104757.28588-1-jslaby@suse.cz +.. _discussion: https://lore.kernel.org/r/20170217104757.28588-1-jslaby@suse.cz Macros Description ------------------ @@ -100,6 +101,11 @@ Instruction Macros ~~~~~~~~~~~~~~~~~~ This section covers ``SYM_FUNC_*`` and ``SYM_CODE_*`` enumerated above. +``objtool`` requires that all code must be contained in an ELF symbol. Symbol +names that have a ``.L`` prefix do not emit symbol table entries. ``.L`` +prefixed symbols can be used within a code region, but should be avoided for +denoting a range of code via ``SYM_*_START/END`` annotations. + * ``SYM_FUNC_START`` and ``SYM_FUNC_START_LOCAL`` are supposed to be **the most frequent markings**. They are used for functions with standard calling conventions -- global and local. Like in C, they both align the functions to @@ -125,14 +131,13 @@ This section covers ``SYM_FUNC_*`` and ``SYM_CODE_*`` enumerated above. In fact, this kind of annotation corresponds to the now deprecated ``ENTRY`` and ``ENDPROC`` macros. -* ``SYM_FUNC_START_ALIAS`` and ``SYM_FUNC_START_LOCAL_ALIAS`` serve for those - who decided to have two or more names for one function. The typical use is:: +* ``SYM_FUNC_ALIAS``, ``SYM_FUNC_ALIAS_LOCAL``, and ``SYM_FUNC_ALIAS_WEAK`` can + be used to define multiple names for a function. The typical use is:: - SYM_FUNC_START_ALIAS(__memset) - SYM_FUNC_START(memset) + SYM_FUNC_START(__memset) ... asm insns ... - SYM_FUNC_END(memset) - SYM_FUNC_END_ALIAS(__memset) + SYN_FUNC_END(__memset) + SYM_FUNC_ALIAS(memset, __memset) In this example, one can call ``__memset`` or ``memset`` with the same result, except the debug information for the instructions is generated to |