elspec(5)
elspec - ELF layout specification
As shipped in MIPSpro 7.4.3m.
NAME elspec - ELF layout specification DESCRIPTION This man page describes the ELF Layout Specification (ELSPEC) language implemented by ld(1). ELSPEC allows users to specify the exact layout of object files, programs, and shared objects. It is often desirable to specify the exact layout of an executable file. Some of the uses of this might be embedded systems layout, thread-local data layout, reducing cache conflicts, reducing false sharing, reducing memory utilization. The current linker allows exact specification of layout via the ELF Layout Specification Language. INVOKING LAYOUT SPECIFICATION An ELSPEC file can be specified to the linker on the compiler command line using the -Wl option and the ld(1) command's -elspec option. The following examples shows the cc(1) and ld(1) commands specifying an ELSPEC file: cc -Wl,-elspec,elsfile ... or ld -elspec elsfile ... You can get a sample ELSPEC file for the default link by using the ld(1) command's -elsmap option. The following example shows the cc(1) and ld(1) commands with the -elsmap option: cc -Wl,-elsmap ... or ld -elsmap ... BASIC BUILDING BLOCKS The basic units that the linker manipulates are called input sections. Each object file can have several input sections with familiar names such as .text, .data, .bss, and so on. The correctness of compiled code can depend on the exact layout of code and data within a section, but it never depends on the relative layout between sections. For that reason, the linker will never rearrange or change the contents of any individual input section in any way. The one exception to this are COMMON variables for which space is allocated by the linker, are not allocated to any input section. These can be manipulated freely, but they cannot be split into pieces by an ELF Layout Specification (ELSPEC). You get a COMMON variable by using a Fortran COMMON statement or from C data variables declared at file scope in files that have been compiled with either -cckr or -common. Segments Input sections are linked together more or less contiguously into output sections. Output sections are organized in an ELF file into loadable segments specified in the program header. For more information, see the elf(4) man page. Segments represent a contiguous portion of the file to be loaded into memory as is, with possibly the addition of extra memory at the end. PLACEMENT RULES An ELSPEC works by allowing users to specify the placement of input sections within output sections, and the output sections within segments. In order to avoid requiring the user to specify every input file, we give rules for default placement of an input section in an output section and the placement of output sections within segments. A section from an input file will be placed in the output file according to these rules: 1. If the section (and object and archive) is mentioned explicitly, it is placed as specified. 2. If there is a section specified in the map with the same name, with default as one of its contents, and with matching attributes, it is placed there. The input section maintains its layout position relative to other listed contents. If there is more than one default-placed input section, space is allocated for them in the order encountered. If the attributes of the input section do not match those specified in the map, it is an error. 3. If there is a segment specified in the map with matching attributes that has specified default as one of its contents, the input section is placed in an output section with the same name and attributes. The input section maintains its layout position relative to other listed contents. If there is more than one default-placed input section, space is allocated for them in the order encountered. If the attributes of the input section do not match those specified in the map or those of another default input section, it is an error. 4. If an input object is listed as a segment content without mention of specific input sections, all sections with appropriate attributes are merged by name and laid out in the order encountered. 5. The linker manages file layout in any fashion it sees fit. The -ignorevce option can be used to allow tighter packing. 6. Specifying headers as contents of a segment allows (but does not require) the inclusion of headers, such as the ELF header and the program header, into that segment. Specifying default has this effect as well. Specifying noheaders forbids the inclusion of headers into that segment 7. Loader-generated sections are placed into a segment with matching attributes that has ldgen specified as its segment contents. Specific loader-generated sections can be placed by using $ldobj as the object name. When a non-optional, loader-generated section has no place to be loaded, an error is generated unless the $ignoreldgen ELSPEC variable is set to TRUE. 8. If user-specified alignment results in R4000 alignment problems, ld reports these to the user and produces output anyway. If $r4kbugfix is set to FALSE or if -allow_jump_at_eop is specified on the link line, no checking is performed. 9. In general, command line options take precedence over the general rules stated on this man page. 10.Overlaps in virtual space or physical space are reported unless at least one of the segment descriptions has specified an overlap with the other, or unless the $ignoreoverlaps ELSPEC variable is set to TRUE. 11.The name, type, and flags of an output section uniquely determine a section. Specifying more than one such section in the file yields unpredictable results. 12.Sections with the SHF_ALLOC and SHF_READ flags but not the SHF_WRITE flag are placed in the first segment that has PF_R but not PF_W set. SYNTAX The following sections describe the syntax of an ELSPEC file. Overview An ELSPEC file consists of the following parts, in the following order: 1. A list of global variable settings 2. A list of symbol attribute specifications 3. A list of segment specifications Using modified Backus-Naur Form (BNF), this can be depicted as follows: <layoutspec> ::= <globals> <symlist> <seglist>; Segments Segments are the basic runtime building blocks and are necessarily contiguous, both in memory and in the file. They have a uniform set of protections associated. The following BNF shows how a segment is organized: <segdef> ::= beginseg <segname> <segattr> <segspecial> contents <segcontents> endseg; <segname> ::= /* empty */ | name <idstring>; <segattr> ::= /* empty */ | <segattr> segtype <segtype> | <segattr> vaddr <address> | <segattr> paddr <address> | <segattr> segflags <segflags> | <segattr> segalign <number> ; <segtype> ::= noload /* include in output segment */ | <number> | LOAD /* this is the default */ | REL ; <segflags> ::= /* empty, default settings are RWX */ | <segflags> R /* Set the PF_R flag */ | <segflags> W /* Set the PF_W flag */ | <segflags> X /* Set the PF_X flag */ | <segflags> L; /* Set the PF_MIPS_LOCAL flag */ For programs running under IRIX 5.3 and above, segments with the PF_MIPS_LOCAL flag set will be thread-local and not shared in the event of an sproc system call. For other applications, the meaning of this bit is undefined. Segment Contents The contents of a segment are usually in the form of output sections. These section are further specified to contain input sections (see following) and are laid out in the order specified, building upwards in virtual address space. Specifying default as segment contents allows the linker to place input sections with compatible attributes which are not otherwise mentioned in the current segment. This is accomplished by creating a distinct output section for each unique set of section type, flags, and section name, and placing it in the "best" segment that has specified default as one of its segment contents. <segcontents> ::= /* empty */ | <segcontents> <outsection> | <segcontents> noheaders | <segcontents> default ; Output Sections Output sections are a convenient way to group material within a segment. For example, if you have decided to have read-only data and program text in the same segment, but within that segment, you want to have all the read-only data together and all the text together. You can define two output sections, named .rdata and .text, and place them both within a single segment. <outsection> ::= beginscn <idstring> <scnattr> <scnspecial> <scncontents> endscn | beginscn <idstring> relfor <idstring> endscn | beginscn <idstring> relafor <idstring> endscn ; <scnattr> ::= /* empty string */ | <scnattr> scntype <scntype> | <scnattr> scnflags <scnflags> | <scnattr> scnsize <size> | <scnattr> link <number> | <scnattr> info <number> | <scnattr> scnalign <number> | <scnattr> entsize <number> ; <scntype> ::= PROGBITS | NOTE | NOBITS | <number>; <scnflags> ::= <scnflaglist> | <number> | none; <scnflaglist> ::= /* empty */ | <scngflaglist> WRITE | <scngflaglist> ALLOC | <scngflaglist> EXECINSTR | <scngflaglist> GPREL | <scngflaglist> MERGE | <scngflaglist> ADDR | <scngflaglist> NOSTRIP | <scngflaglist> LOCAL ; Layout specification for relocatable (-r) links is supported. Unlike other types of output sections, the contents of relocation sections cannot be freely specified. Rather, the contents of a given relfor section are determined relative to some other output section. For example, the following section contains all the rel-type relocations for the output section named .mytext: beginscn .rel.mytext relfor .mytext endscn Relocation sections can be given any name, but the relocation must be preceded by the section to which the relocations are relative. Input sections Input sections are the basic building blocks that the linker manipulates. Each object file read by the linker can contain several of these input sections. The ELSPEC file works by specifying the arrangement of these input sections. You can specify input sections by either attempting to specify the section directly or by specifying an external symbol name. Specifying an external symbol name has the effect of specifying the section in which that symbol definition resides. These two methods of specification are defined as follows: <scncontents> ::= /* Nothing */ | <scncontents> default | <scncontents> <inputscn> | <scncontents> <symspec>; Sometimes the attributes of an input section are not compatible with those of the enclosing output section. In the BNF that follows, you see different input section specifications categorized as either specific or generic. Conflicts are handled as follows: * If a specific mention conflicts with default output section attributes, the output section attributes are promoted to be compatible. * If a specific mention conflicts with user-specified output section attributes, the input section is included with a warning, but the output section attributes are not altered. * If a generic mention conflicts with output section attributes, the input section is not included in the output section, regardless of whether the output sections attributes were user-specified or not. In the following BNF, the <idstring> specifies the name of the input section. If no name is specified, all sections from the mentioned object with matching attributes are selected. <inputscn> ::= sec <idstring> /* specific mention */ | sec <idstring> in <object> /* specific mention */ | <object> /* generic mention */ ; <object> ::= obj[ect] <idstring> ( <idstring> ) | obj[ect] <idstring> | ar[chive] <idstring> | ldobj /* for specifying /* loader-defined sections */ ; <symspec> ::= sym <idstring> in <inputscn> | sym <idstring> ; ELSPEC Variables The linker uses the values contained in various ELSPEC variables when laying out your program. These variables are as follows: <globals> ::= /* NULL */ | globals set_global; <set_global ::= <gsize> = <size> | <gbool> = <boolean>; <gsize> ::= $blocksize | $cachesize | $pagesize | $cachelinesize; <gbool> ::= $ignoreldgen | $r4kbugfix | $ignoreoverlaps; Segment Special Attributes These allow users to specify special attributes of a segment. Specifying ascending means that the components are laid out in order of increasing address, beginning at the specific, or default, address. This is the default behavior. Specifying overlap <idstring> denotes that the normal linker checking for overlaps in virtual address are not to be performed between the current segment and the segment named by idstring. This is to facilitate overlay links. <segspecial> ::= /* empty */ | <segspecial> ascending | <segspecial> overlap <idstring>; Base Data Types The base data types are defined as follows: <size> ::= <number> | <number> K | <number> M; <address> ::= <number> <number> ::= 0x[0-9a-f]+ /* Hex number */ | 0[0-7]+ /* Octal number */ | [0-9]+ /* decimal number */ ; <boolean> ::= true | false ; <idstring> ::= [a-zA-Z0-9$_.]+ | "<any string>" ; Comments If the pound character (#) appears in a layout specification (except when within a string specified with quotation marks ("")), the remainder of the line, including the # is treated as a comment and is ignored. EXAMPLES The following examples assume a PAGESIZE value of 0x1000. Example 1. This is the default link specification. Using it should give the same result as not using the -elspec option on the ld(1) command. beginseg name text segtype LOAD vaddr 0x10000000 segflags R X segalign 0x10000 contents default endseg beginseg name data segtype LOAD segflags R W X segalign 0x1000 contents default endseg beginseg name noload segtype noload contents default endseg Example 2. This link specification gives the COMMON symbol a_ an alignment of 128 bytes. This prevents false sharing, among other things. beginseg segtype LOAD segflags R X # vaddr 0x10000000 segalign 0x1000 contents default endseg beginseg segtype LOAD segflags R W # vaddr 0x10011000 segalign 0x1000 contents default beginscn .mybss scntype NOBITS scnflags ALLOC WRITE scnalign 0x80 sym a_ endscn endseg SEE ALSO elfdump(1), ld(1) elf(4)