ld: Miscellaneous Commands

1 
1 3.4.5 Other Linker Script Commands
1 ----------------------------------
1 
1 There are a few other linker scripts commands.
1 
1 'ASSERT(EXP, MESSAGE)'
1      Ensure that EXP is non-zero.  If it is zero, then exit the linker
1      with an error code, and print MESSAGE.
1 
1      Note that assertions are checked before the final stages of linking
1      take place.  This means that expressions involving symbols PROVIDEd
1      inside section definitions will fail if the user has not set values
1      for those symbols.  The only exception to this rule is PROVIDEd
1      symbols that just reference dot.  Thus an assertion like this:
1 
1             .stack :
1             {
1               PROVIDE (__stack = .);
1               PROVIDE (__stack_size = 0x100);
1               ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
1             }
1 
1      will fail if '__stack_size' is not defined elsewhere.  Symbols
1      PROVIDEd outside of section definitions are evaluated earlier, so
1      they can be used inside ASSERTions.  Thus:
1 
1             PROVIDE (__stack_size = 0x100);
1             .stack :
1             {
1               PROVIDE (__stack = .);
1               ASSERT ((__stack > (_end + __stack_size)), "Error: No room left for the stack");
1             }
1 
1      will work.
1 
1 'EXTERN(SYMBOL SYMBOL ...)'
1      Force SYMBOL to be entered in the output file as an undefined
1      symbol.  Doing this may, for example, trigger linking of additional
1      modules from standard libraries.  You may list several SYMBOLs for
1      each 'EXTERN', and you may use 'EXTERN' multiple times.  This
1      command has the same effect as the '-u' command-line option.
1 
1 'FORCE_COMMON_ALLOCATION'
1      This command has the same effect as the '-d' command-line option:
1      to make 'ld' assign space to common symbols even if a relocatable
1      output file is specified ('-r').
1 
1 'INHIBIT_COMMON_ALLOCATION'
1      This command has the same effect as the '--no-define-common'
1      command-line option: to make 'ld' omit the assignment of addresses
1      to common symbols even for a non-relocatable output file.
1 
1 'FORCE_GROUP_ALLOCATION'
1      This command has the same effect as the '--force-group-allocation'
1      command-line option: to make 'ld' place section group members like
1      normal input sections, and to delete the section groups even if a
1      relocatable output file is specified ('-r').
1 
1 'INSERT [ AFTER | BEFORE ] OUTPUT_SECTION'
1      This command is typically used in a script specified by '-T' to
1      augment the default 'SECTIONS' with, for example, overlays.  It
1      inserts all prior linker script statements after (or before)
1      OUTPUT_SECTION, and also causes '-T' to not override the default
1      linker script.  The exact insertion point is as for orphan
1      sections.  ⇒Location Counter.  The insertion happens after
1      the linker has mapped input sections to output sections.  Prior to
1      the insertion, since '-T' scripts are parsed before the default
1      linker script, statements in the '-T' script occur before the
1      default linker script statements in the internal linker
1      representation of the script.  In particular, input section
1      assignments will be made to '-T' output sections before those in
1      the default script.  Here is an example of how a '-T' script using
1      'INSERT' might look:
1 
1           SECTIONS
1           {
1             OVERLAY :
1             {
1               .ov1 { ov1*(.text) }
1               .ov2 { ov2*(.text) }
1             }
1           }
1           INSERT AFTER .text;
1 
1 'NOCROSSREFS(SECTION SECTION ...)'
1      This command may be used to tell 'ld' to issue an error about any
1      references among certain output sections.
1 
1      In certain types of programs, particularly on embedded systems when
1      using overlays, when one section is loaded into memory, another
1      section will not be.  Any direct references between the two
1      sections would be errors.  For example, it would be an error if
1      code in one section called a function defined in the other section.
1 
1      The 'NOCROSSREFS' command takes a list of output section names.  If
1      'ld' detects any cross references between the sections, it reports
1      an error and returns a non-zero exit status.  Note that the
1      'NOCROSSREFS' command uses output section names, not input section
1      names.
1 
1 'NOCROSSREFS_TO(TOSECTION FROMSECTION ...)'
1      This command may be used to tell 'ld' to issue an error about any
1      references to one section from a list of other sections.
1 
1      The 'NOCROSSREFS' command is useful when ensuring that two or more
1      output sections are entirely independent but there are situations
1      where a one-way dependency is needed.  For example, in a multi-core
1      application there may be shared code that can be called from each
1      core but for safety must never call back.
1 
1      The 'NOCROSSREFS_TO' command takes a list of output section names.
1      The first section can not be referenced from any of the other
1      sections.  If 'ld' detects any references to the first section from
1      any of the other sections, it reports an error and returns a
1      non-zero exit status.  Note that the 'NOCROSSREFS_TO' command uses
1      output section names, not input section names.
1 
1 'OUTPUT_ARCH(BFDARCH)'
1      Specify a particular output machine architecture.  The argument is
1      one of the names used by the BFD library (⇒BFD).  You can
1      see the architecture of an object file by using the 'objdump'
1      program with the '-f' option.
1 
1 'LD_FEATURE(STRING)'
1      This command may be used to modify 'ld' behavior.  If STRING is
1      '"SANE_EXPR"' then absolute symbols and numbers in a script are
1      simply treated as numbers everywhere.  ⇒Expression Section.
1