Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) Assembler Annotations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) Copyright (c) 2017-2019 Jiri Slaby
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) This document describes the new macros for annotation of data and code in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) assembly. In particular, it contains information about ``SYM_FUNC_START``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) ``SYM_FUNC_END``, ``SYM_CODE_START``, and similar.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) Rationale
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) ---------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) Some code like entries, trampolines, or boot code needs to be written in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) assembly. The same as in C, such code is grouped into functions and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) accompanied with data. Standard assemblers do not force users into precisely
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) marking these pieces as code, data, or even specifying their length.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) Nevertheless, assemblers provide developers with such annotations to aid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) debuggers throughout assembly. On top of that, developers also want to mark
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) some functions as *global* in order to be visible outside of their translation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) units.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) Over time, the Linux kernel has adopted macros from various projects (like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) ``binutils``) to facilitate such annotations. So for historic reasons,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) developers have been using ``ENTRY``, ``END``, ``ENDPROC``, and other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) annotations in assembly.  Due to the lack of their documentation, the macros
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) are used in rather wrong contexts at some locations. Clearly, ``ENTRY`` was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) intended to denote the beginning of global symbols (be it data or code).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) ``END`` used to mark the end of data or end of special functions with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) *non-standard* calling convention. In contrast, ``ENDPROC`` should annotate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) only ends of *standard* functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) When these macros are used correctly, they help assemblers generate a nice
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) object with both sizes and types set correctly. For example, the result of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) ``arch/x86/lib/putuser.S``::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35)    Num:    Value          Size Type    Bind   Vis      Ndx Name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36)     25: 0000000000000000    33 FUNC    GLOBAL DEFAULT    1 __put_user_1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37)     29: 0000000000000030    37 FUNC    GLOBAL DEFAULT    1 __put_user_2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38)     32: 0000000000000060    36 FUNC    GLOBAL DEFAULT    1 __put_user_4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39)     35: 0000000000000090    37 FUNC    GLOBAL DEFAULT    1 __put_user_8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) This is not only important for debugging purposes. When there are properly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) annotated objects like this, tools can be run on them to generate more useful
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) information. In particular, on properly annotated objects, ``objtool`` can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) run to check and fix the object if needed. Currently, ``objtool`` can report
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) missing frame pointer setup/destruction in functions. It can also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) automatically generate annotations for :doc:`ORC unwinder <x86/orc-unwinder>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) for most code. Both of these are especially important to support reliable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) stack traces which are in turn necessary for :doc:`Kernel live patching
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) <livepatch/livepatch>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) Caveat and Discussion
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) As one might realize, there were only three macros previously. That is indeed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) insufficient to cover all the combinations of cases:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) * standard/non-standard function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) * code/data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) * global/local symbol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) There was a discussion_ and instead of extending the current ``ENTRY/END*``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) macros, it was decided that brand new macros should be introduced instead::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63)     So how about using macro names that actually show the purpose, instead
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64)     of importing all the crappy, historic, essentially randomly chosen
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65)     debug symbol macro names from the binutils and older kernels?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) .. _discussion: https://lkml.kernel.org/r/20170217104757.28588-1-jslaby@suse.cz
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) Macros Description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) The new macros are prefixed with the ``SYM_`` prefix and can be divided into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) three main groups:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) 1. ``SYM_FUNC_*`` -- to annotate C-like functions. This means functions with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76)    standard C calling conventions. For example, on x86, this means that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77)    stack contains a return address at the predefined place and a return from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78)    the function can happen in a standard way. When frame pointers are enabled,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79)    save/restore of frame pointer shall happen at the start/end of a function,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80)    respectively, too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82)    Checking tools like ``objtool`` should ensure such marked functions conform
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83)    to these rules. The tools can also easily annotate these functions with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84)    debugging information (like *ORC data*) automatically.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) 2. ``SYM_CODE_*`` -- special functions called with special stack. Be it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87)    interrupt handlers with special stack content, trampolines, or startup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88)    functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90)    Checking tools mostly ignore checking of these functions. But some debug
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91)    information still can be generated automatically. For correct debug data,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92)    this code needs hints like ``UNWIND_HINT_REGS`` provided by developers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) 3. ``SYM_DATA*`` -- obviously data belonging to ``.data`` sections and not to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95)    ``.text``. Data do not contain instructions, so they have to be treated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96)    specially by the tools: they should not treat the bytes as instructions,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97)    nor assign any debug information to them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99) Instruction Macros
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) ~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) This section covers ``SYM_FUNC_*`` and ``SYM_CODE_*`` enumerated above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) ``objtool`` requires that all code must be contained in an ELF symbol. Symbol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) names that have a ``.L`` prefix do not emit symbol table entries. ``.L``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) prefixed symbols can be used within a code region, but should be avoided for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) denoting a range of code via ``SYM_*_START/END`` annotations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) * ``SYM_FUNC_START`` and ``SYM_FUNC_START_LOCAL`` are supposed to be **the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)   most frequent markings**. They are used for functions with standard calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)   conventions -- global and local. Like in C, they both align the functions to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)   architecture specific ``__ALIGN`` bytes. There are also ``_NOALIGN`` variants
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)   for special cases where developers do not want this implicit alignment.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)   ``SYM_FUNC_START_WEAK`` and ``SYM_FUNC_START_WEAK_NOALIGN`` markings are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)   also offered as an assembler counterpart to the *weak* attribute known from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)   C.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)   All of these **shall** be coupled with ``SYM_FUNC_END``. First, it marks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)   the sequence of instructions as a function and computes its size to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)   generated object file. Second, it also eases checking and processing such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)   object files as the tools can trivially find exact function boundaries.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)   So in most cases, developers should write something like in the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)   example, having some asm instructions in between the macros, of course::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)     SYM_FUNC_START(memset)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)         ... asm insns ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)     SYM_FUNC_END(memset)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)   In fact, this kind of annotation corresponds to the now deprecated ``ENTRY``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)   and ``ENDPROC`` macros.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) * ``SYM_FUNC_START_ALIAS`` and ``SYM_FUNC_START_LOCAL_ALIAS`` serve for those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)   who decided to have two or more names for one function. The typical use is::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)     SYM_FUNC_START_ALIAS(__memset)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)     SYM_FUNC_START(memset)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)         ... asm insns ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)     SYM_FUNC_END(memset)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)     SYM_FUNC_END_ALIAS(__memset)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)   In this example, one can call ``__memset`` or ``memset`` with the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)   result, except the debug information for the instructions is generated to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)   the object file only once -- for the non-``ALIAS`` case.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) * ``SYM_CODE_START`` and ``SYM_CODE_START_LOCAL`` should be used only in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)   special cases -- if you know what you are doing. This is used exclusively
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)   for interrupt handlers and similar where the calling convention is not the C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)   one. ``_NOALIGN`` variants exist too. The use is the same as for the ``FUNC``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)   category above::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)     SYM_CODE_START_LOCAL(bad_put_user)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)         ... asm insns ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)     SYM_CODE_END(bad_put_user)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156)   Again, every ``SYM_CODE_START*`` **shall** be coupled by ``SYM_CODE_END``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158)   To some extent, this category corresponds to deprecated ``ENTRY`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)   ``END``. Except ``END`` had several other meanings too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) * ``SYM_INNER_LABEL*`` is used to denote a label inside some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)   ``SYM_{CODE,FUNC}_START`` and ``SYM_{CODE,FUNC}_END``.  They are very similar
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)   to C labels, except they can be made global. An example of use::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)     SYM_CODE_START(ftrace_caller)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)         /* save_mcount_regs fills in first two parameters */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)         ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)     SYM_INNER_LABEL(ftrace_caller_op_ptr, SYM_L_GLOBAL)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170)         /* Load the ftrace_ops into the 3rd parameter */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)         ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)     SYM_INNER_LABEL(ftrace_call, SYM_L_GLOBAL)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)         call ftrace_stub
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)         ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176)         retq
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)     SYM_CODE_END(ftrace_caller)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) Data Macros
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) ~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) Similar to instructions, there is a couple of macros to describe data in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) assembly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) * ``SYM_DATA_START`` and ``SYM_DATA_START_LOCAL`` mark the start of some data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)   and shall be used in conjunction with either ``SYM_DATA_END``, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186)   ``SYM_DATA_END_LABEL``. The latter adds also a label to the end, so that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)   people can use ``lstack`` and (local) ``lstack_end`` in the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188)   example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190)     SYM_DATA_START_LOCAL(lstack)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191)         .skip 4096
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192)     SYM_DATA_END_LABEL(lstack, SYM_L_LOCAL, lstack_end)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) * ``SYM_DATA`` and ``SYM_DATA_LOCAL`` are variants for simple, mostly one-line
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)   data::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)     SYM_DATA(HEAP,     .long rm_heap)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)     SYM_DATA(heap_end, .long rm_stack)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)   In the end, they expand to ``SYM_DATA_START`` with ``SYM_DATA_END``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)   internally.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) Support Macros
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) ~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) All the above reduce themselves to some invocation of ``SYM_START``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) ``SYM_END``, or ``SYM_ENTRY`` at last. Normally, developers should avoid using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) these.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) Further, in the above examples, one could see ``SYM_L_LOCAL``. There are also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) ``SYM_L_GLOBAL`` and ``SYM_L_WEAK``. All are intended to denote linkage of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) symbol marked by them. They are used either in ``_LABEL`` variants of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) earlier macros, or in ``SYM_START``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) Overriding Macros
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) ~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) Architecture can also override any of the macros in their own
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) ``asm/linkage.h``, including macros specifying the type of a symbol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) (``SYM_T_FUNC``, ``SYM_T_OBJECT``, and ``SYM_T_NONE``).  As every macro
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) described in this file is surrounded by ``#ifdef`` + ``#endif``, it is enough
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) to define the macros differently in the aforementioned architecture-dependent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) header.