10eae32dcSDimitry Andric-z start-stop-gc 20eae32dcSDimitry Andric================ 30eae32dcSDimitry Andric 40eae32dcSDimitry AndricIf your ``-Wl,--gc-sections`` build fail with a linker error like this: 50eae32dcSDimitry Andric 60eae32dcSDimitry Andric error: undefined symbol: __start_meta 70eae32dcSDimitry Andric >>> referenced by {{.*}} 80eae32dcSDimitry Andric >>> the encapsulation symbol needs to be retained under --gc-sections properly; consider -z nostart-stop-gc (see https://lld.llvm.org/start-stop-gc) 90eae32dcSDimitry Andric 100eae32dcSDimitry Andricit is likely your C identifier name sections are not properly annotated to 110eae32dcSDimitry Andricsuffice under ``--gc-sections``. 120eae32dcSDimitry Andric 13*06c3fb27SDimitry Andric``__start_meta`` and ``__stop_meta`` are sometimes called encapsulation 140eae32dcSDimitry Andricsymbols. In October 2015, GNU ld switched behavior and made a ``__start_meta`` 150eae32dcSDimitry Andricreference from a live section retain all ``meta`` input sections. This 160eae32dcSDimitry Andricconservative behavior works for existing code which does not take GC into fair 170eae32dcSDimitry Andricconsideration, but unnecessarily increases sizes for modern metadata section 180eae32dcSDimitry Andricusage which desires precise GC. 190eae32dcSDimitry Andric 200eae32dcSDimitry AndricGNU ld 2.37 added ``-z start-stop-gc`` to restore the traditional behavior 210eae32dcSDimitry Andricld.lld 13.0.0 defaults to ``-z start-stop-gc`` and supports ``-z nostart-stop-gc`` 220eae32dcSDimitry Andricto switch to the conservative behavior. 230eae32dcSDimitry Andric 240eae32dcSDimitry AndricThe Apple ld64 linker has a similar ``section$start`` feature and always 250eae32dcSDimitry Andricallowed GC (like ``-z start-stop-gc``). 260eae32dcSDimitry Andric 270eae32dcSDimitry AndricAnnotate C identifier name sections 280eae32dcSDimitry Andric----------------------------------- 290eae32dcSDimitry Andric 300eae32dcSDimitry AndricA C identifier name section (``meta``) sometimes depends on another section. 310eae32dcSDimitry AndricLet that section reference ``meta`` via a relocation. 320eae32dcSDimitry Andric 330eae32dcSDimitry Andric.. code-block:: c 340eae32dcSDimitry Andric 350eae32dcSDimitry Andric asm(".pushsection .init_array,\"aw\",@init_array\n" \ 360eae32dcSDimitry Andric ".reloc ., R_AARCH64_NONE, meta\n" \ 370eae32dcSDimitry Andric ".popsection\n") 380eae32dcSDimitry Andric 390eae32dcSDimitry AndricIf a relocation is inconvenient, consider using ``__attribute__((retain))`` 400eae32dcSDimitry Andric(GCC 11 with modern binutils, Clang 13). 410eae32dcSDimitry Andric 420eae32dcSDimitry Andric.. code-block:: c 430eae32dcSDimitry Andric 440eae32dcSDimitry Andric #pragma GCC diagnostic push 450eae32dcSDimitry Andric #pragma GCC diagnostic ignored "-Wattributes" 460eae32dcSDimitry Andric __attribute__((retain,used,section("meta"))) 470eae32dcSDimitry Andric static const char dummy[0]; 480eae32dcSDimitry Andric #pragma GCC diagnostic pop 490eae32dcSDimitry Andric 500eae32dcSDimitry AndricGCC before 11 and Clang before 13 do not recognize ``__attribute__((retain))``, 510eae32dcSDimitry Andricso ``-Wattributes`` may need to be ignored. On ELF targets, 520eae32dcSDimitry Andric``__attribute__((used))`` prevents compiler discarding, but does not affect 530eae32dcSDimitry Andriclinker ``--gc-sections``. 540eae32dcSDimitry Andric 550eae32dcSDimitry AndricIn a macro, you may use: 560eae32dcSDimitry Andric 570eae32dcSDimitry Andric.. code-block:: c 580eae32dcSDimitry Andric 590eae32dcSDimitry Andric _Pragma("GCC diagnostic push") 600eae32dcSDimitry Andric _Pragma("GCC diagnostic ignored \"-Wattributes\"") 610eae32dcSDimitry Andric ... 620eae32dcSDimitry Andric _Pragma("GCC diagnostic pop") 630eae32dcSDimitry Andric 640eae32dcSDimitry AndricIf you use the ``SECTIONS`` command in a linker script, use 650eae32dcSDimitry Andric`the ``KEEP`` keyword <https://sourceware.org/binutils/docs/ld/Input-Section-Keep.html>`_, e.g. 660eae32dcSDimitry Andric``meta : { KEEP(*(meta)) }`` 67