elspec(5)
elspec - ELF layout specification
As shipped in IRIX 6.5.30. Last changed in IRIX 6.5.19.
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. 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 does not rearrange or change the contents of any individual input section with the exception of uninitialized common variables. Uninitialized 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 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 .B -cckr or .B -common. Segments Input sections are linked together 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 it is, with possibly the addition of extra memory at the end. PLACEMENT RULES An ELSPEC allows you to specify the following: * The placement of input sections within output sections. * The placement of output sections within segments. Rules exist regarding default placement. The following rules describe when a section from an input file is placed in the output file: 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. 6. Specifying headers or specifying default 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 noheaders forbids the inclusion of headers into that segment 7. Linker-generated sections are placed into a segment with matching attributes that has ldgen specified as its segment contents. Specific linker-generated sections can be placed by using $ldobj as the object name. When a non-optional, linker-generated section has no place to be loaded, an error is generated unless the $ignoreldgen ELSPEC variable is set to TRUE. For more information, see the ELSPEC Variables section in this man page. 8. Command line options are available to override the general rules stated on this man page. 9. 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. 10.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. 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 comprised of one or more sections. The content of each segment is contiguous. Sections within a segment must have compatible attributes. The following BNF shows how a segment is organized: <segdef> ::= beginseg <segname> <segattr> contents <segcontents> endseg ; <segname> ::= /* empty */ | <idstring> ; <segattr> ::= /* empty */ | <segattr> segtype <segtype> | <segattr> vaddr <address> | <segattr> paddr <address> | <segattr> filesz <size> | <segattr> memsz <size> | <segattr> segflags <segflags> | <segattr> segalign <number> | <segattr> prepad <number> ; WHERE: "segtype" is the segment type (see the following BNF for <segtype>). "vaddr" is the virtual address. "paddr" is the physical address. "filesz" is the size of the segment in the file. "memsz" is the size of the segment at runtime in memory. "segflags" is the bit mask of flags for this segment (see the following BNF for <segflags>). "segalign" is the alignment of the segment. Usually this is modulo PAGESIZE in value. "prepad" is the amount of padding to put at the beginning of the segment. <segtype> ::= noload | <number> | LOAD | REL ; WHERE: "noload" indicates that the section should not be loaded at runtime. This is a pseudo segment used to group nonloadable sections. "<number>" is the hexadecimal number for the section type. See the ELF ABI for possible segment types. "LOAD" indicates that the segment should be loaded at runtime. DEFAULT. "REL" indicates relocatable output. See the following <segflags>. <segflags> ::= /* empty, default settings are RWX */ | <segflags> R | <segflags> W | <segflags> X | <segflags> L ; WHERE: "R" is readable. "W" is writable. "X" is executable. "L" is thread local. 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. The segment contents (segcontents) are defined as follows: <segcontents> ::= /* empty */ | <segcontents> <outsection> | <segcontents> noheaders | <segcontents> default | <segcontents> default_gprel | <segcontents> ldgen ; WHERE: "<outsection>" is a specific output section. For more information, see the Output Sections section of this man page. "noheaders" excludes ELF, PROGRAM, and SECTION headers. "default" allows the linker to place input sections with compatible attributes that are not otherwise mentioned in the current segment. This is accomplished by creating distinct output sections 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. "default_gprel" specifies all output sections that are GP-relative. GP is the Global Pointer. "ldgen" consists of linker-generated output sections. 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. Most of the terms used in the section syntax maps to the ELF section header structure fields, which are as follows: Field name Content sh_name Section name sh_type Section type sh_flags Section flags sh_addr Address of first byte, or zero sh_offset File offset of section sh_size Section's size in bytes sh_link Table index link (section specific) sh_info Extra information (section specific) sh_addralign Address alignment constraint sh_entsize Size of fixed-size entries in section, or zero The output sections are defined as follows: <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> ; WHERE: "PROGBITS" means the section will be in memory at runtime. "NOTE" means the section with marked as note section. "NOBITS" means the contents of the section may not take up any space in the file, but it is filled out at runtime. "<number>" is the hexadecimal number that represents the section type. (See the MIPS ABI). <scnflags> ::= <scnflaglist> | <number> | none ; <scnflaglist> ::= /* empty */ | <scngflaglist> WRITE | <scnflaglist> ALLOC | <scnflaglist> EXECINSTR | <scnflaglist> GPREL | <scnflaglist> MERGE | <scnflaglist> NOSTRIP | <scnflaglist> LOCAL ; WHERE: "WRITE" means that the contents are writable. "ALLOC" means that the contents will be in memory. "EXECINSTR" means that the contents are executable instrutions. "GPREL" means that the contents are within 64K bytes of the value contained in the GP register (short data). "MERGE" means that the contents of the section can be merged with other similar sections. For example, literal sections. "NOSTRIP" means that this section should not be stripped from the file. "LOCAL" means that the contents are thread-local data. Layout specification for relocatable links is supported; for information on these see the -r option on the ld(1) man page. 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: <item> ::= <inputscn> | <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 /* linker-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 ; 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 Example 3. If data needs to be loaded relative to the Global Pointer (the gprel area), the ELSPEC file must contain information regarding this data. When this information is missing from the ELSPEC file, the system generates the following messages: ld32: FATAL 173: No gprel area specified in elspec file. Try using "default_gprel" after the data section declaration. See ELSPEC(5) ld32: INFO 152: Output file removed because of error. To correct the file, add the following line: default_gprel Here is the corrected ELSPEC file: beginseg segtype LOAD segflags R W X vaddr 0x88500000 segalign 0x1000 contents beginscn .text scntype PROGBITS scnflags ALLOC EXECINSTR scnalign 0x10 section .text endscn endseg beginseg segtype LOAD segflags R W vaddr 0xa85a5000 segalign 0x1000 contents beginscn .rodata scntype PROGBITS scnflags ALLOC WRITE scnalign 0x8 section .rodata endscn beginscn .rdata scntype PROGBITS scnflags ALLOC WRITE scnalign 0x8 section .rdata endscn beginscn .data scntype PROGBITS scnflags ALLOC WRITE scnalign 0x8 section .data endscn default_gprel # SPECIFIES gprel LOADING beginscn .bss scntype NOBITS scnflags ALLOC WRITE section .bss endscn beginscn .MIPS.options scntype 0x7000000d scnflags ALLOC NOSTRIP scnalign 0x8 section .MIPS.options endscn beginscn .reginfo scntype NOBITS scnflags ALLOC NOSTRIP scnalign 0x8 section .reginfo endscn endseg SEE ALSO elfdump(1), ld(1) elf(4)