So how about using macro names that actually show the purpose, instead
of importing all the crappy, historic, essentially randomly chosen
debug symbol macro names from the binutils and older kernels?

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
  architecture specific ``__ALIGN`` bytes. There are also ``_NOALIGN`` variants
  for special cases where developers do not want this implicit alignment.

  ``SYM_FUNC_START_WEAK`` and ``SYM_FUNC_START_WEAK_NOALIGN`` markings are
  also offered as an assembler counterpart to the *weak* attribute known from
  C.

  All of these **shall** be coupled with ``SYM_FUNC_END``. First, it marks
  the sequence of instructions as a function and computes its size to the
  generated object file. Second, it also eases checking and processing such
  object files as the tools can trivially find exact function boundaries.

  So in most cases, developers should write something like in the following
  example, having some asm instructions in between the macros, of course::

    SYM_FUNC_START(memset)
        ... asm insns ...
    SYM_FUNC_END(memset)

  In fact, this kind of annotation corresponds to the now deprecated ``ENTRY``
  and ``ENDPROC`` macros.

* ``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(__memset)
        ... asm insns ...
    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
  the object file only once -- for the non-``ALIAS`` case.

* ``SYM_CODE_START`` and ``SYM_CODE_START_LOCAL`` should be used only in
  special cases -- if you know what you are doing. This is used exclusively
  for interrupt handlers and similar where the calling convention is not the C
  one. ``_NOALIGN`` variants exist too. The use is the same as for the ``FUNC``
  category above::

    SYM_CODE_START_LOCAL(bad_put_user)
        ... asm insns ...
    SYM_CODE_END(bad_put_user)

  Again, every ``SYM_CODE_START*`` **shall** be coupled by ``SYM_CODE_END``.

  To some extent, this category corresponds to deprecated ``ENTRY`` and
  ``END``. Except ``END`` had several other meanings too.

* ``SYM_INNER_LABEL*`` is used to denote a label inside some
  ``SYM_{CODE,FUNC}_START`` and ``SYM_{CODE,FUNC}_END``.  They are very similar
  to C labels, except they can be made global. An example of use::

    SYM_CODE_START(ftrace_caller)
        /* save_mcount_regs fills in first two parameters */
        ...

    SYM_INNER_LABEL(ftrace_caller_op_ptr, SYM_L_GLOBAL)
        /* Load the ftrace_ops into the 3rd parameter */
        ...

    SYM_INNER_LABEL(ftrace_call, SYM_L_GLOBAL)
        call ftrace_stub
        ...
        retq
    SYM_CODE_END(ftrace_caller)

Data Macros
~~~~~~~~~~~
Similar to instructions, there is a couple of macros to describe data in the
assembly.

* ``SYM_DATA_START`` and ``SYM_DATA_START_LOCAL`` mark the start of some data
  and shall be used in conjunction with either ``SYM_DATA_END``, or
  ``SYM_DATA_END_LABEL``. The latter adds also a label to the end, so that
  people can use ``lstack`` and (local) ``lstack_end`` in the following
  example::

    SYM_DATA_START_LOCAL(lstack)
        .skip 4096
    SYM_DATA_END_LABEL(lstack, SYM_L_LOCAL, lstack_end)

* ``SYM_DATA`` and ``SYM_DATA_LOCAL`` are variants for simple, mostly one-line
  data::

    SYM_DATA(HEAP,     .long rm_heap)
    SYM_DATA(heap_end, .long rm_stack)

  In the end, they expand to ``SYM_DATA_START`` with ``SYM_DATA_END``
  internally.

Support Macros
~~~~~~~~~~~~~~
All the above reduce themselves to some invocation of ``SYM_START``,
``SYM_END``, or ``SYM_ENTRY`` at last. Normally, developers should avoid using
these.

Further, in the above examples, one could see ``SYM_L_LOCAL``. There are also
``SYM_L_GLOBAL`` and ``SYM_L_WEAK``. All are intended to denote linkage of a
symbol marked by them. They are used either in ``_LABEL`` variants of the
earlier macros, or in ``SYM_START``.


Overriding Macros
~~~~~~~~~~~~~~~~~
Architecture can also override any of the macros in their own
``asm/linkage.h``, including macros specifying the type of a symbol
(``SYM_T_FUNC``, ``SYM_T_OBJECT``, and ``SYM_T_NONE``).  As every macro
described in this file is surrounded by ``#ifdef`` + ``#endif``, it is enough
to define the macros differently in the aforementioned architecture-dependent
header.