### Linker Script: Define Output Sections and Place Input Sections

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Example

This linker script defines three output sections: 'outputa', 'outputb', and 'outputc'. It demonstrates how to specify starting addresses for output sections and how to include specific input sections from particular object files, as well as all remaining input sections matching a pattern. The script uses a SECTIONS directive to control the memory layout.

```linker-script
SECTIONS {
  outputa 0x10000 :
    {
    all.o
    foo.o (.input1)
    }

  outputb :
    {
    foo.o (.input2)
    foo1.o (.input1)
    }

  outputc :
    {
    *(.input1)
    *(.input2)
    }
}

```

--------------------------------

### Example MEMORY Command Usage in Linker Scripts

Source: https://sourceware.org/binutils/docs/ld/MEMORY

Provides a practical example of using the MEMORY command to define 'rom' and 'ram' memory regions with specific attributes, origins, and lengths. It demonstrates abbreviations for ORIGIN and LENGTH keywords.

```linker-script
MEMORY
  {
    rom (rx)  : ORIGIN = 0, LENGTH = 256K
    ram (!rx) : org = 0x40000000, l = 4M
  }

```

--------------------------------

### Setting Section Addresses and Sizes with '.'

Source: https://sourceware.org/binutils/docs/ld/Location-Counter

Illustrates how to assign specific start addresses and sizes to output sections using the '.' location counter. It also shows how '.' within a section description refers to the offset from the start of that section.

```Linker Script
SECTIONS
{
    . = 0x100
    .text: {
      *(.text)
      . = 0x200
    }
    . = 0x500
    .data: {
      *(.data)
      . += 0x600
    }
}

```

--------------------------------

### Include All Input Sections by Name

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Basics

This example demonstrates how to include all input sections with a specific name, such as '.text', from any input file using a wildcard. The '*' acts as a wildcard for the file name.

```linker script
*(.text)
```

--------------------------------

### Linker Script SECTIONS with Wildcards for Data Section Mapping

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Wildcards

This linker script example demonstrates how to use wildcard patterns within the SECTIONS command to selectively map '.data' sections based on input file names. It directs the linker to place '.data' sections from files starting with an uppercase letter into the '.DATA' output section, and from all other files into the '.data' output section. The '.text' and '.bss' sections are mapped directly.

```linker-script
SECTIONS {
  .text : { *(.text) }
  .DATA : { [A-Z]*(.data) }
  .data : { *(.data) }
  .bss : { *(.bss) }
}
```

--------------------------------

### Include All Sections from a Specific File

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Basics

This example shows how to include all sections from a specific file ('data.o') if no section list is provided. This is less common but can be used when a file's contents need to be included entirely without specifying individual sections.

```linker script
data.o
```

--------------------------------

### Global Exclusion for Multiple Sections

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Basics

This example shows how placing EXCLUDE_FILE before the file selection wildcard applies the exclusion to all subsequent sections. It achieves the same result as the more verbose conditional exclusion for multiple sections.

```linker script
EXCLUDE_FILE (*somefile.o) *(.text .rdata)
```

--------------------------------

### Conditional Exclusion for Multiple Sections

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Basics

Shows how EXCLUDE_FILE applies to specific sections when placed within the section list. The first example excludes 'somefile.o' only from '.text' inclusion. The second example demonstrates excluding 'somefile.o' from both '.text' and '.rdata' by repeating the directive.

```linker script
*(EXCLUDE_FILE (*somefile.o) .text .rdata)
```

```linker script
*(EXCLUDE_FILE (*somefile.o) .text EXCLUDE_FILE (*somefile.o) .rdata)
```

--------------------------------

### Basic Input Section Wildcard Example

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Wildcards

Illustrates a common scenario in linker scripts where a wildcard '*' is used for the file name, and a section pattern is specified. Note that 'data.o' rule might not be used due to the order.

```linker script
.data : { *(.data) }
.data1 : { data.o(.data) }
```

--------------------------------

### Linker Script Example: Section Assignment

Source: https://sourceware.org/binutils/docs/ld/Expression-Section

Demonstrates the assignment of absolute and section-relative addresses within a linker script's SECTIONS command. It shows how '.' (the current address) and symbols like __executable_start and __data_start are set.

```ldscript
SECTIONS
  {
    . = 0x100;
    __executable_start = 0x100;
    .data :
    {
      . = 0x10;
      __data_start = 0x10;
      *(.data)
    }
    ...
  }


```

--------------------------------

### ELF HIDDEN Directive Example

Source: https://sourceware.org/binutils/docs/ld/HIDDEN

Demonstrates the usage of the HIDDEN directive for ELF targeted ports to make symbols internal to a module. It rewrites a previous example to explicitly hide symbols like _etext and _bdata.

```linker-script
HIDDEN(floating_point = 0);
SECTIONS
{
  .text :
    {
      *(.text)
      HIDDEN(_etext = .);
    }
  HIDDEN(_bdata = (. + 3) & ~ 3);
  .data : { *(.data) }
}

```

--------------------------------

### ARM/Thumb Interworking Code Stub Example

Source: https://sourceware.org/binutils/docs/ld/ARM

This code snippet illustrates a veneer used for ARM/Thumb interworking, particularly when dealing with R_ARM_V4BX relocations. It checks the condition flags and branches accordingly, allowing ARMv4 objects to be interworking-safe with ARMv4t or to build pure ARMv4 binaries. This veneer may affect program behavior due to clobbering condition flags.

```assembly
TST rM, #1
MOVEQ PC, rM
BX Rn
```

--------------------------------

### Linker Script Example: Non-Constant Expression

Source: https://sourceware.org/binutils/docs/ld/Evaluation

This code snippet demonstrates an invalid linker script expression where a symbol or undefined value is used in the initial address calculation for a section. This will result in a 'non constant expression for initial address' error.

```linker-script
SECTIONS
  {
    .text 9+this_isnt_constant :
      { *(.text) }
  }

```

--------------------------------

### Filter Sections by ELF Header Flags

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Basics

This example shows how to use INPUT_SECTION_FLAGS to filter input sections based on their ELF section header flags. The first case includes sections with both SHF_MERGE and SHF_STRINGS set. The second case includes sections where SHF_WRITE is clear.

```linker script
SECTIONS {
  .text : { INPUT_SECTION_FLAGS (SHF_MERGE & SHF_STRINGS) *(.text) }
  .text2 :  { INPUT_SECTION_FLAGS (!SHF_WRITE) *(.text) }
}
```

--------------------------------

### Get Header Size (SIZEOF_HEADERS)

Source: https://sourceware.org/binutils/docs/ld/Builtin-Functions

The SIZEOF_HEADERS function returns the size in bytes of the output file's headers. This can be used when setting the start address of the first section. For ELF files, using SIZEOF_HEADERS may require careful management of program headers to avoid errors.

```linker-script
SIZEOF_HEADERS
```

--------------------------------

### Specify Initial Input File

Source: https://sourceware.org/binutils/docs/ld/File-Commands

The STARTUP command designates a specific file to be the very first input file processed by the linker. This is useful in systems where the program's entry point is consistently located at the beginning of the first linked file.

```linker-script
STARTUP(filename)
```

--------------------------------

### Include Multiple Sections in Output

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Basics

Illustrates two methods for including multiple input sections, '.text' and '.rdata'. The first method interleaves sections based on their input order, while the second places all '.text' sections before all '.rdata' sections.

```linker script
*(.text .rdata)
```

```linker script
*(.text) *(.rdata)
```

--------------------------------

### Get Section Alignment with ALIGNOF()

Source: https://sourceware.org/binutils/docs/ld/Builtin-Functions

The ALIGNOF() function returns the alignment in bytes of a named section. If the section has not been allocated, it returns zero. If the section does not exist, the linker reports an error.

```linker-script
SECTIONS{
  .output {
    LONG (ALIGNOF (.output))
    ...
    }
...
}
```

--------------------------------

### Include Sections from a Specific File

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Basics

This demonstrates including only the '.data' sections from a specific file named 'data.o'. This is useful for placing special data at a particular memory location.

```linker script
data.o(.data)
```

--------------------------------

### Sorting Input Sections by Initialization Priority

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Wildcards

Explains how to use SORT_BY_INIT_PRIORITY to sort sections based on the GCC init_priority attribute encoded in their names, in ascending numerical order.

```linker script
*(SORT_BY_INIT_PRIORITY(.init_array* .ctors*))
```

--------------------------------

### Get Absolute Value with ABSOLUTE()

Source: https://sourceware.org/binutils/docs/ld/Builtin-Functions

The ABSOLUTE() function returns the absolute value of an expression. It is primarily used to assign an absolute value to a symbol within a section definition, where symbol values are normally section-relative.

```linker-script
SECTIONS {
  .output1 : {
    start_of_output_1 = ABSOLUTE(.);
    ...
  }
  .output : {
    symbol_1 = ADDR(.output1);
    symbol_2 = start_of_output_1;
  }
...
}
```

--------------------------------

### Specify Input Files for Linking

Source: https://sourceware.org/binutils/docs/ld/File-Commands

The INPUT command instructs the linker to include the specified files in the linking process, similar to providing them on the command line. It supports various path resolution mechanisms including sysroot prefixes and transformation of -lfile to libfile.a.

```linker-script
INPUT(file, file, …)
INPUT(file file …)
```

--------------------------------

### Define Output Filename

Source: https://sourceware.org/binutils/docs/ld/File-Commands

The OUTPUT command specifies the name for the linker's output file. This is equivalent to using the -o option on the command line, with the command-line option taking precedence if both are specified.

```linker-script
OUTPUT(filename)
```

--------------------------------

### Get Section Size (SECTIONS)

Source: https://sourceware.org/binutils/docs/ld/Builtin-Functions

The SIZEOF function returns the size in bytes of a named section if it has been allocated, or zero otherwise. If the section does not exist, the linker reports an error. It can also return the alignment of the next allocated section.

```linker-script
SECTIONS{
  .output {
    .start = . ;
    ...
    .end = . ;
    }
  symbol_1 = .end - .start ;
  symbol_2 = SIZEOF(.output);
...
}
```

--------------------------------

### Handling Multiple Wildcard Patterns with Sorting

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Wildcards

Illustrates the correct way to apply sorting to multiple wildcard patterns by listing them individually, as nested sorting commands for multiple patterns are not supported.

```linker script
*(REVERSE(.text*))
*(REVERSE(.init*))
```

--------------------------------

### Group Archives for Repeated Searching

Source: https://sourceware.org/binutils/docs/ld/File-Commands

The GROUP command is similar to INPUT but specifically expects archive files. It repeatedly searches these archives until no new undefined references are resolved, ensuring all dependencies within the group are met.

```linker-script
GROUP(file, file, …)
GROUP(file file …)
```

--------------------------------

### Conditionally Include Needed Libraries

Source: https://sourceware.org/binutils/docs/ld/File-Commands

AS_NEEDED is used within INPUT or GROUP commands to optimize the inclusion of ELF shared libraries. These libraries are only linked if they are actually required by the object files, effectively enabling the --as-needed linker option for the specified files.

```linker-script
AS_NEEDED(file, file, …)
AS_NEEDED(file file …)
```

--------------------------------

### Linker Script Example: Using ABSOLUTE() Builtin

Source: https://sourceware.org/binutils/docs/ld/Expression-Section

Illustrates the use of the ABSOLUTE() builtin function in a linker script to ensure that a symbol (_edata) is assigned an absolute address, specifically the address of the end of the .data section. Without ABSOLUTE(), the symbol would be relative to the section.

```ldscript
SECTIONS
  {
    .data : { *(.data) _edata = ABSOLUTE(.); }
  }


```

--------------------------------

### Add Archive Search Directories

Source: https://sourceware.org/binutils/docs/ld/File-Commands

The SEARCH_DIR command adds a directory to the list of paths where the linker looks for archive libraries. This functionality is identical to using the -L command-line option, and paths from both sources are searched.

```linker-script
SEARCH_DIR(path)
```

--------------------------------

### Linker Script Wildcard Patterns Explained

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Wildcards

Describes the wildcard characters used in linker scripts for matching file and section names. These patterns behave similarly to Unix shell wildcards.

```text
* matches any number of characters
? matches any single character
[chars] matches a single instance of any of the chars; the ‘-’ character may be used to specify a range of characters, as in ‘[a-z]’ to match any lower case letter
\ quotes the following character
```

--------------------------------

### Linker Script for Common Symbols

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Common

This linker script snippet demonstrates how to group common symbols from all input files into the '.bss' section of the output file. It specifically targets the standard COMMON section and any '.bss' sections present in the input files. This is a common pattern for memory layout definition in embedded systems.

```linker-script
.bss { *(.bss) *(COMMON) }
```

--------------------------------

### Define Constants with Suffixes in Linker Scripts

Source: https://sourceware.org/binutils/docs/ld/Constants

Demonstrates defining constants using various bases and scaling suffixes like K and M. These constants represent integer values and follow C-like prefix rules for bases. Suffixes K and M scale the value by 1024 and 1024*1024 respectively. Base and scaling suffixes cannot be combined.

```linker script
_fourk_1 = 4K;
_fourk_2 = 4096;
_fourk_3 = 0x1000;
_fourk_4 = 10000o;

```

--------------------------------

### MEMORY Command Syntax for Linker Scripts

Source: https://sourceware.org/binutils/docs/ld/MEMORY

Defines the basic syntax for the MEMORY command in linker scripts. It outlines how to declare memory regions with their names, optional attributes, origin, and length.

```linker-script
MEMORY
  {
    name [(attr)] : ORIGIN = origin, LENGTH = len
    ...
  }

```

--------------------------------

### Nested Section Sorting Rule 7

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Wildcards

Describes a valid nesting for reverse sorting by init priority: SORT_BY_INIT_PRIORITY followed by REVERSE.

```linker script
SORT_BY_INIT_PRIORITY(REVERSE(.init_array*))
```

--------------------------------

### Specify Output File Format with OUTPUT_FORMAT

Source: https://sourceware.org/binutils/docs/ld/Format-Commands

The OUTPUT_FORMAT command defines the BFD format for the linker's output file. It can accept a single BFD name or three names to handle default, big-endian, and little-endian formats based on command-line options like -EB and -EL. The command-line option --oformat takes precedence if both are used.

```linker-script
OUTPUT_FORMAT(bfdname)

OUTPUT_FORMAT(default, big, little)
```

```linker-script
OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
```

--------------------------------

### GFDL Copyright and Permission Notice (With Cover/Invariant Sections)

Source: https://sourceware.org/binutils/docs/ld/GNU-Free-Documentation-License

This code snippet provides an alternative copyright and permission notice for documents licensed under the GNU Free Documentation License (GFDL). It is used when the document includes Invariant Sections, Front-Cover Texts, or Back-Cover Texts, allowing for their specific listing.

```text
    with the Invariant Sections being list their titles, with
    the Front-Cover Texts being list, and the Back-Cover Texts
    being list.

```

--------------------------------

### Nesting Sorting Commands with EXCLUDE_FILE

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Wildcards

Shows the correct syntax for nesting the EXCLUDE_FILE command within a sorting command, emphasizing that the sorting command must be the outer one.

```linker script
*(SORT_BY_NAME(EXCLUDE_FILE(foo) .text*))
```

--------------------------------

### GFDL v1.3 Copyright and Permission Notice (No Cover/Invariant Sections)

Source: https://sourceware.org/binutils/docs/ld/GNU-Free-Documentation-License

This code snippet shows the standard copyright and permission notice for documents licensed under the GNU Free Documentation License (GFDL) version 1.3, specifically when there are no Invariant Sections, Front-Cover Texts, or Back-Cover Texts. It grants permission to copy, distribute, and modify the document under the GFDL terms.

```text
Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.3
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
  Texts.  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

```

--------------------------------

### Include Files in Linker Script

Source: https://sourceware.org/binutils/docs/ld/File-Commands

The INCLUDE command incorporates the content of another linker script file into the current script. It searches for the specified filename in the current directory and directories provided via the -L option. Nested INCLUDEs are supported up to 10 levels deep.

```linker-script
INCLUDE filename
```

--------------------------------

### Sorting Input Sections by Name

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Wildcards

Demonstrates how to use the SORT_BY_NAME keyword (or its alias SORT) to sort input sections or files alphabetically by name. This can be applied to wildcard patterns.

```linker script
*(SORT_BY_NAME(.text*))
```

--------------------------------

### Accessing Memory Origin and Length in Expressions

Source: https://sourceware.org/binutils/docs/ld/MEMORY

Illustrates how to use the ORIGIN() and LENGTH() functions within linker script expressions to calculate values based on defined memory regions, such as setting the stack pointer.

```linker-script
  _fstack = ORIGIN(ram) + LENGTH(ram) - 4;

```

--------------------------------

### Sorting Input Sections by Alignment

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Wildcards

Shows the usage of SORT_BY_ALIGNMENT to sort input sections based on their alignment in descending order. This can help minimize padding.

```linker script
*(SORT_BY_ALIGNMENT(.text*))
```

--------------------------------

### Reversing Sorting Order

Source: https://sourceware.org/binutils/docs/ld/Input-Section-Wildcards

Demonstrates the REVERSE keyword to invert the sorting order. It can be used independently or to reverse an existing SORT command.

```linker script
*(REVERSE(.text*))
```

```linker script
*(.REVERSE(.text*))
```