Documentation/core-api/asm-annotations.rst

4 Copyright (c) 2017-2019 Jiri Slaby
6 This document describes the new macros for annotation of data and code in
7 assembly. In particular, it contains information about ``SYM_FUNC_START``,
11 ---------
12 Some code like entries, trampolines, or boot code needs to be written in
13 assembly. The same as in C, such code is grouped into functions and
18 some functions as *global* in order to be visible outside of their translation
24 annotations in assembly.  Due to the lack of their documentation, the macros
25 are used in rather wrong contexts at some locations. Clearly, ``ENTRY`` was
27 ``END`` used to mark the end of data or end of special functions with
28 *non-standard* calling convention. In contrast, ``ENDPROC`` should annotate
29 only ends of *standard* functions.
43 information. In particular, on properly annotated objects, ``objtool`` can be
45 missing frame pointer setup/destruction in functions. It can also
47 (Documentation/arch/x86/orc-unwinder.rst)
49 stack traces which are in turn necessary for kernel live patching
53 ---------------------
57 * standard/non-standard function
68 .. _discussion: https://lore.kernel.org/r/20170217104757.28588-1-jslaby@suse.cz
71 ------------------
76 1. ``SYM_FUNC_*`` -- to annotate C-like functions. This means functions with
79    the function can happen in a standard way. When frame pointers are enabled,
83    Checking tools like ``objtool`` should ensure such marked functions conform
84    to these rules. The tools can also easily annotate these functions with
87 2. ``SYM_CODE_*`` -- special functions called with special stack. Be it
89    functions.
91    Checking tools mostly ignore checking of these functions. But some debug
95 3. ``SYM_DATA*`` -- obviously data belonging to ``.data`` sections and not to
104 ``objtool`` requires that all code must be contained in an ELF symbol. Symbol
110   most frequent markings**. They are used for functions with standard calling
111   conventions -- global and local. Like in C, they both align the functions to
124   So in most cases, developers should write something like in the following
125   example, having some asm instructions in between the macros, of course::
131   In fact, this kind of annotation corresponds to the now deprecated ``ENTRY``
142   In this example, one can call ``__memset`` or ``memset`` with the same
144   the object file only once -- for the non-``ALIAS`` case.
146 * ``SYM_CODE_START`` and ``SYM_CODE_START_LOCAL`` should be used only in
147   special cases -- if you know what you are doing. This is used exclusively
166         /* save_mcount_regs fills in first two parameters */
181 Similar to instructions, there is a couple of macros to describe data in the
185   and shall be used in conjunction with either ``SYM_DATA_END``, or
187   people can use ``lstack`` and (local) ``lstack_end`` in the following
194 * ``SYM_DATA`` and ``SYM_DATA_LOCAL`` are variants for simple, mostly one-line
200   In the end, they expand to ``SYM_DATA_START`` with ``SYM_DATA_END``
209 Further, in the above examples, one could see ``SYM_L_LOCAL``. There are also
211 symbol marked by them. They are used either in ``_LABEL`` variants of the
212 earlier macros, or in ``SYM_START``.
217 Architecture can also override any of the macros in their own
220 described in this file is surrounded by ``#ifdef`` + ``#endif``, it is enough
221 to define the macros differently in the aforementioned architecture-dependent