elspec(5)
ELSPEC - ELF Layout specification
As shipped in IRIX 6.5. First release of IRIX 6.5.
NAME ELSPEC - ELF Layout specification TOPIC This manpage describes the ELF Layout Specification language implemented by ld(1) which allows users to exactly specify layout of object files, programs, and shared objects. INTRODUCTION It is often desirable to specify the exact layout of an executable file. Some of the uses of this might be embedded systems, 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 is specified to the linker using cc -Wl,-elspec,<filename> ... or ld -elspec <filename> ... You may get a sample elspec file for the default link using: cc -Wl,-elsmap ... or ld -elsmap ... Basic Building Blocks The basic units that the linker manipulates are called input sections. Each object file may have several of these, with familiar names such as `.text', `.data', `.bss', and so on. The correctness of compiled code may depend on the exact layout of a section, but 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, and as such, are not allocated to any input section. These can be manipulated freely, but not split into pieces by ELF Layout Specification. You get a COMMON variable by using a FORTRAN COMMON, or from C data variables declared at file scope in files which 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 and ELF file into loadable segments which are specified in the program header. See elf(5). Segments represent a contiguous portion of the file which is to be loaded into memory as-is, with possibly the addition of extra memory at the end. Placement Rules ELF Layout Specification works by allowing the user 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 the 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) are mentioned explicitly, place it there. 2. If there is a section specified in the map with the same name, which has "default" as one of its contents, and which has matching attributes, place it there. The input section will maintain its layout position relative to other listed contents. If there is more than one default-placed input section, they will be allocated space 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 which has specified "default" as one of its contents, the input section will be placed in an output section with the same name and attributes. The input section will maintain its layout position relative to other listed contents. If there is more than one default-placed input section, they will be allocated space 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. File layout will be managed by the linker in any fashion it sees fit. We can provide a flag -ignorevce 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" will forbid the inclusion of headers into that segment 7. Loader-generated sections will be placed in to a segment with matching attributes which has specified "ldgen" as its segment contents. Specific loader-generated sections may 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 global switch "$ignoreldgen" has the value "true". 8. Should user-specified alignment result in R4000 alignment problems, ld will report these to the user, and produce output anyway. If "$r4kbugfix" is set to false (or -allow_jump_at_eop specfied on the linkline), no checking will be performed. 9. In general, command line options take precedence over specifications here. 10.Overlaps in virtual space or physical space will be reported unless at least one of the segment descriptions has specified an overlap with the other, or unless "$ignoreoverlaps" is true. 11.The name, type, and flags of an output section uniquely determines that section. Specifying more than one such section in the file will yield unpredictable results. 12.Sections with flags SHF_ALLOC and SHF_READ but not SHF_WRITE, will be placed in the first segment which has PF_R but not PF_W set. SYNTAX This section describes the actual syntax of an ELSPEC file. There are some examples at the end. Overview There are three main parts to the layout specification (lspec) file. In order expected, they are: a list of global variable settings, a list of symbols attribute specifications, and a list of segment specifications. <layoutspec> ::= <globals> <symlist> <seglist>; Segments Segments are the basic runtime building blocks. They are necessarily contiguous, both in memory and in the file. They have a uniform set of protections associated. <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 under the 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(2) system call. For other applications, the meaning of this bit is undefined. Segment contents Contents of a segment are usually in the form of output sections. These section are further specified to contain input sections (see below), and are laid out in the order specified. The default is to build 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 sections for each unique set of section type, flags, and section name, and placing it in the "best" segment which 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, we may wish to have read-only data and program text in the same segment, but within that segment we want to have all the read-only data together and all the text together. We 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 | <scnflaglist> ALLOC | <scnflaglist> EXECINSTR | <scnflaglist> GPREL | <scnflaglist> MERGE | <scnflaglist> ADDR | <scnflaglist> NOSTRIP | <scnflaglist> 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 section specified by beginscn .rel.mytext relfor .mytext endscn contains all the Rel-type relocations for the output section named ".mytext". Relocation sections can be given any name, but the relocation must be preceded by the section the relocations are relative to. Input sections Input sections are the basic building blocks which the linker manipulates. Each object file read by the linker may contain several of these input section. The lspec file works by specifying the arrangement of these input sections. Input sections may be specified in two basic ways. The user may attempt to specify the section directly, or may specify an external symbol name, which has the effect of specifying the section in which that symbol definition resides. <scncontents> ::= /* Nothing */ | <scncontents> default | <scncontents> <inputscn> | <scncontents> <symspec>; In the rule below, 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. Sometimes it may occur that the attributes of an input section are not compatible with those of the enclosing output section. Below you see different input section specifications categorized as either specific or generic. 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. <inputscn> ::= sec <idstring> /* specific mention */ | sec <idstring> in <object> /* specific mention */ | <object>; /* generic mention */ <object> ::= obj[ect] <idstring> ( <idstring> ) /* archive(filename) */ | obj[ect] <idstring> | ar[chive] <idstring> | ldobj; /* for specifying loader-defined sections */ <symspec> ::= sym <idstring> in <inputscn> | sym <idstring>; ELSpec Variables Various ELF layout Specification (ELSpec) variables can be given values. These values will be used by the linker when laying out your program. <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 will be laid out in order of increasing address, beginning at the specified (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 Here is the syntax for numbers, booleans, strings and so on. <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 character '#' appears in a layout specification (except when with in a string specified with ""), the remainder of the line, including the '#' will be treated as a comment and ignored. EXAMPLES Default link spec # # This is the default link spec. Using it should give the # same result as not using -elspec # 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 Aligning a COMMON symbol # # This link spec will give the COMMON symbol a_ an alignment of 128 # bytes. This can be useful to prevent 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 ld(1), elf(5), elfdump(5) UPDATES This manpage is updated periodically, the last update was on 3/1/95 for IRIX 6.0.2