60

The LD manual does not explain what the KEEP command does. Below is a snippet from a third-party linker script that features KEEP. What does the KEEP command do in ld?

SECTIONS
{  
    .text :
    {
        . = ALIGN(4);
        _text = .;
        PROVIDE(stext = .);
        KEEP(*(.isr_vector))
        KEEP(*(.init))
        *(.text .text.*)        
        *(.rodata .rodata.*)        
        *(.gnu.linkonce.t.*)
        *(.glue_7)
        *(.glue_7t)
        *(.gcc_except_table)
        *(.gnu.linkonce.r.*)
        . = ALIGN(4);
        _etext = .;
        _sidata = _etext;
        PROVIDE(etext = .);   
            _fini = . ;
                *(.fini)

    } >flash
Randomblue
  • 112,777
  • 145
  • 353
  • 547
  • 8
    KEEP is documented in [this](https://sourceware.org/binutils/docs/ld/Input-Section-Keep.html#Input-Section-Keep) version of the manual. – alexei Nov 02 '13 at 04:24

3 Answers3

58

Afaik LD keeps the symbols in the section even if symbols are not referenced. (--gc-sections).

Usually used for sections that have some special meaning in the binary startup process, more or less to mark the roots of the dependency tree.

(For Sabuncu below)

Dependency tree:

If you eliminate unused code, you analyze the code and mark all reachable sections (code+global variables + constants).

So you pick a section, mark it as "used" and see what other (unused) section it references, then you mark those section as "used", and check what they reference etc.

The section that are not marked "used" are then redundant, and can be eliminated.

Since a section can reference multiple other sections (e.g. one procedure calling three different other ones), if you would draw the result you get a tree.

Roots:

The above principle however leaves us with a problem: what is the "first" section that is always used? The first node (root) of the tree so to speak? This is what "keep()" does, it tells the linker which sections (if available) are the first ones to look at. As a consequence these are always linked in.

Typically these are sections that are called from the program loader to perform tasks related to dynamic linking (can be optional, and OS/fileformat dependent), and the entry point of the program.

Marco van de Voort
  • 25,628
  • 5
  • 56
  • 89
  • 7
    +1 What is the dependency tree? Why is it important to mark its roots? Thanks. – Sabuncu Dec 30 '13 at 11:18
  • 1
    I add a short explanation to the post. – Marco van de Voort Dec 30 '13 at 11:40
  • THANK you! You say "...tells the linker which sections (if available) are the first ones to look at." Why wouldn't a section be available if it is marked as KEEP? Maybe I am missing some of the fundamentals here, but this topic is really obscure (yet vital) and I am having difficulty finding resources for educating myself. – Sabuncu Dec 30 '13 at 11:46
  • 1
    You can imagine e.g. one script and two sets of startup code, one for profiling, one not. – Marco van de Voort Dec 30 '13 at 14:11
  • Some pedantry: the dependency structure is actually a graph, not a tree. Dependencies can go in both directions, there can even be cycles. – Brendan Nov 18 '15 at 09:39
  • That depends on if you regard following a dependency or marking an unused section as structure determining action. If you never mark an already marked section, the structure you build is a tree. – Marco van de Voort Nov 18 '15 at 19:27
  • So I can imagine `Keep` exactly as `volatile` keyword in C? – Mohammed Noureldin Jun 22 '19 at 11:51
20

Minimal Linux IA-32 example that illustrates its usage

main.S

.section .text
.global _start
_start:
    /* Dummy access so that after will be referenced and kept. */
    mov after, %eax
    /*mov keep, %eax*/

    /* Exit system call. */
    mov $1, %eax

    /* Take the exit status 4 bytes after before. */
    mov $4, %ebx
    mov before(%ebx), %ebx

    int $0x80

.section .before
    before: .long 0
/* TODO why is the `"a"` required? */
.section .keep, "a"
    keep: .long 1
.section .after
    after: .long 2

link.ld

ENTRY(_start)
SECTIONS
{
    . = 0x400000;
    .text :
    {
        *(.text)
        *(.before)
        KEEP(*(.keep));
        *(.keep)
        *(.after)
    }
}

Compile and run:

as --32 -o main.o main.S
ld --gc-sections -m elf_i386 -o main.out -T link.ld main.o
./main.out
echo $?

Output:

1

If we comment out the KEEP line the output is:

2

If we either:

  • add a dummy mov keep, %eax
  • remove --gc-sections

The output goes back to 1.

Tested on Ubuntu 14.04, Binutils 2.25.

Explanation

There is no reference to the symbol keep, and therefore its containing section .keep.

Therefore if garbage collection is enabled and we don't use KEEP to make an exception, that section will not be put in the executable.

Since we are adding 4 to the address of before, if the keep section is not present, then the exit status will be 2, which is present on the next .after section.

TODO: nothing happens if we remove the "a" from .keep, which makes it allocatable. I don't understand why that is so: that section will be put inside the .text segment, which because of it's magic name will be allocatable.

Ciro Santilli OurBigBook.com
  • 347,512
  • 102
  • 1,199
  • 985
  • Very clear example, thank you ! However I don't see when it can be useful to use this KEEP statement – Axel B Mar 04 '22 at 10:46
  • @AxelB I don't have a good example right now, but this kind of stuff tends to show up when [writing operating systems/baremetal programs](https://stackoverflow.com/questions/22054578/how-to-run-a-program-without-an-operating-system). In this case, the KEEP section is presumably something that would be used by something outside of your program, e.g. a bootloader who reads your binary, or a debugger. – Ciro Santilli OurBigBook.com Mar 04 '22 at 11:57
  • @AxelB if you git grep into the Linux kernel source tree you can see some examples. I'm not 100% what each of one for, but we can make reasonable guesses by googling their section names. E.g. in x86 they have some king of [PLG/GOT](https://reverseengineering.stackexchange.com/questions/1992/what-is-plt-got) system at: https://github.com/cirosantilli/linux/blob/94710cac0ef4ee177a63b5227664b38c95bbf703/arch/x86/boot/compressed/vmlinux.lds.S#L47 – Ciro Santilli OurBigBook.com Mar 04 '22 at 12:41
2

Force the linker to keep some specific sections

SECTIONS 
{
....
....

*(.rodata .rodata.*)

KEEP(*(SORT(.scattered_array*)));
}
leesagacious
  • 182
  • 1
  • 8