223 lines · plain
1Assembler Annotations2=====================3 4Copyright (c) 2017-2019 Jiri Slaby5 6This document describes the new macros for annotation of data and code in7assembly. In particular, it contains information about ``SYM_FUNC_START``,8``SYM_FUNC_END``, ``SYM_CODE_START``, and similar.9 10Rationale11---------12Some code like entries, trampolines, or boot code needs to be written in13assembly. The same as in C, such code is grouped into functions and14accompanied with data. Standard assemblers do not force users into precisely15marking these pieces as code, data, or even specifying their length.16Nevertheless, assemblers provide developers with such annotations to aid17debuggers throughout assembly. On top of that, developers also want to mark18some functions as *global* in order to be visible outside of their translation19units.20 21Over time, the Linux kernel has adopted macros from various projects (like22``binutils``) to facilitate such annotations. So for historic reasons,23developers have been using ``ENTRY``, ``END``, ``ENDPROC``, and other24annotations in assembly. Due to the lack of their documentation, the macros25are used in rather wrong contexts at some locations. Clearly, ``ENTRY`` was26intended to denote the beginning of global symbols (be it data or code).27``END`` used to mark the end of data or end of special functions with28*non-standard* calling convention. In contrast, ``ENDPROC`` should annotate29only ends of *standard* functions.30 31When these macros are used correctly, they help assemblers generate a nice32object with both sizes and types set correctly. For example, the result of33``arch/x86/lib/putuser.S``::34 35 Num: Value Size Type Bind Vis Ndx Name36 25: 0000000000000000 33 FUNC GLOBAL DEFAULT 1 __put_user_137 29: 0000000000000030 37 FUNC GLOBAL DEFAULT 1 __put_user_238 32: 0000000000000060 36 FUNC GLOBAL DEFAULT 1 __put_user_439 35: 0000000000000090 37 FUNC GLOBAL DEFAULT 1 __put_user_840 41This is not only important for debugging purposes. When there are properly42annotated objects like this, tools can be run on them to generate more useful43information. In particular, on properly annotated objects, ``objtool`` can be44run to check and fix the object if needed. Currently, ``objtool`` can report45missing frame pointer setup/destruction in functions. It can also46automatically generate annotations for the ORC unwinder47(Documentation/arch/x86/orc-unwinder.rst)48for most code. Both of these are especially important to support reliable49stack traces which are in turn necessary for kernel live patching50(Documentation/livepatch/livepatch.rst).51 52Caveat and Discussion53---------------------54As one might realize, there were only three macros previously. That is indeed55insufficient to cover all the combinations of cases:56 57* standard/non-standard function58* code/data59* global/local symbol60 61There was a discussion_ and instead of extending the current ``ENTRY/END*``62macros, it was decided that brand new macros should be introduced instead::63 64 So how about using macro names that actually show the purpose, instead65 of importing all the crappy, historic, essentially randomly chosen66 debug symbol macro names from the binutils and older kernels?67 68.. _discussion: https://lore.kernel.org/r/20170217104757.28588-1-jslaby@suse.cz69 70Macros Description71------------------72 73The new macros are prefixed with the ``SYM_`` prefix and can be divided into74three main groups:75 761. ``SYM_FUNC_*`` -- to annotate C-like functions. This means functions with77 standard C calling conventions. For example, on x86, this means that the78 stack contains a return address at the predefined place and a return from79 the function can happen in a standard way. When frame pointers are enabled,80 save/restore of frame pointer shall happen at the start/end of a function,81 respectively, too.82 83 Checking tools like ``objtool`` should ensure such marked functions conform84 to these rules. The tools can also easily annotate these functions with85 debugging information (like *ORC data*) automatically.86 872. ``SYM_CODE_*`` -- special functions called with special stack. Be it88 interrupt handlers with special stack content, trampolines, or startup89 functions.90 91 Checking tools mostly ignore checking of these functions. But some debug92 information still can be generated automatically. For correct debug data,93 this code needs hints like ``UNWIND_HINT_REGS`` provided by developers.94 953. ``SYM_DATA*`` -- obviously data belonging to ``.data`` sections and not to96 ``.text``. Data do not contain instructions, so they have to be treated97 specially by the tools: they should not treat the bytes as instructions,98 nor assign any debug information to them.99 100Instruction Macros101~~~~~~~~~~~~~~~~~~102This section covers ``SYM_FUNC_*`` and ``SYM_CODE_*`` enumerated above.103 104``objtool`` requires that all code must be contained in an ELF symbol. Symbol105names that have a ``.L`` prefix do not emit symbol table entries. ``.L``106prefixed symbols can be used within a code region, but should be avoided for107denoting a range of code via ``SYM_*_START/END`` annotations.108 109* ``SYM_FUNC_START`` and ``SYM_FUNC_START_LOCAL`` are supposed to be **the110 most frequent markings**. They are used for functions with standard calling111 conventions -- global and local. Like in C, they both align the functions to112 architecture specific ``__ALIGN`` bytes. There are also ``_NOALIGN`` variants113 for special cases where developers do not want this implicit alignment.114 115 ``SYM_FUNC_START_WEAK`` and ``SYM_FUNC_START_WEAK_NOALIGN`` markings are116 also offered as an assembler counterpart to the *weak* attribute known from117 C.118 119 All of these **shall** be coupled with ``SYM_FUNC_END``. First, it marks120 the sequence of instructions as a function and computes its size to the121 generated object file. Second, it also eases checking and processing such122 object files as the tools can trivially find exact function boundaries.123 124 So in most cases, developers should write something like in the following125 example, having some asm instructions in between the macros, of course::126 127 SYM_FUNC_START(memset)128 ... asm insns ...129 SYM_FUNC_END(memset)130 131 In fact, this kind of annotation corresponds to the now deprecated ``ENTRY``132 and ``ENDPROC`` macros.133 134* ``SYM_FUNC_ALIAS``, ``SYM_FUNC_ALIAS_LOCAL``, and ``SYM_FUNC_ALIAS_WEAK`` can135 be used to define multiple names for a function. The typical use is::136 137 SYM_FUNC_START(__memset)138 ... asm insns ...139 SYN_FUNC_END(__memset)140 SYM_FUNC_ALIAS(memset, __memset)141 142 In this example, one can call ``__memset`` or ``memset`` with the same143 result, except the debug information for the instructions is generated to144 the object file only once -- for the non-``ALIAS`` case.145 146* ``SYM_CODE_START`` and ``SYM_CODE_START_LOCAL`` should be used only in147 special cases -- if you know what you are doing. This is used exclusively148 for interrupt handlers and similar where the calling convention is not the C149 one. ``_NOALIGN`` variants exist too. The use is the same as for the ``FUNC``150 category above::151 152 SYM_CODE_START_LOCAL(bad_put_user)153 ... asm insns ...154 SYM_CODE_END(bad_put_user)155 156 Again, every ``SYM_CODE_START*`` **shall** be coupled by ``SYM_CODE_END``.157 158 To some extent, this category corresponds to deprecated ``ENTRY`` and159 ``END``. Except ``END`` had several other meanings too.160 161* ``SYM_INNER_LABEL*`` is used to denote a label inside some162 ``SYM_{CODE,FUNC}_START`` and ``SYM_{CODE,FUNC}_END``. They are very similar163 to C labels, except they can be made global. An example of use::164 165 SYM_CODE_START(ftrace_caller)166 /* save_mcount_regs fills in first two parameters */167 ...168 169 SYM_INNER_LABEL(ftrace_caller_op_ptr, SYM_L_GLOBAL)170 /* Load the ftrace_ops into the 3rd parameter */171 ...172 173 SYM_INNER_LABEL(ftrace_call, SYM_L_GLOBAL)174 call ftrace_stub175 ...176 retq177 SYM_CODE_END(ftrace_caller)178 179Data Macros180~~~~~~~~~~~181Similar to instructions, there is a couple of macros to describe data in the182assembly.183 184* ``SYM_DATA_START`` and ``SYM_DATA_START_LOCAL`` mark the start of some data185 and shall be used in conjunction with either ``SYM_DATA_END``, or186 ``SYM_DATA_END_LABEL``. The latter adds also a label to the end, so that187 people can use ``lstack`` and (local) ``lstack_end`` in the following188 example::189 190 SYM_DATA_START_LOCAL(lstack)191 .skip 4096192 SYM_DATA_END_LABEL(lstack, SYM_L_LOCAL, lstack_end)193 194* ``SYM_DATA`` and ``SYM_DATA_LOCAL`` are variants for simple, mostly one-line195 data::196 197 SYM_DATA(HEAP, .long rm_heap)198 SYM_DATA(heap_end, .long rm_stack)199 200 In the end, they expand to ``SYM_DATA_START`` with ``SYM_DATA_END``201 internally.202 203Support Macros204~~~~~~~~~~~~~~205All the above reduce themselves to some invocation of ``SYM_START``,206``SYM_END``, or ``SYM_ENTRY`` at last. Normally, developers should avoid using207these.208 209Further, in the above examples, one could see ``SYM_L_LOCAL``. There are also210``SYM_L_GLOBAL`` and ``SYM_L_WEAK``. All are intended to denote linkage of a211symbol marked by them. They are used either in ``_LABEL`` variants of the212earlier macros, or in ``SYM_START``.213 214 215Overriding Macros216~~~~~~~~~~~~~~~~~217Architecture can also override any of the macros in their own218``asm/linkage.h``, including macros specifying the type of a symbol219(``SYM_T_FUNC``, ``SYM_T_OBJECT``, and ``SYM_T_NONE``). As every macro220described in this file is surrounded by ``#ifdef`` + ``#endif``, it is enough221to define the macros differently in the aforementioned architecture-dependent222header.223