Mapping Examples

The following are examples of user-defined mapfiles. The numbers on the left are included in the example for tutorial purposes. Only the information to the right of the numbers actually appears in the mapfile.

Example: Section to Segment Assignment

This example demonstrates how to define segments and assign input sections to them.

Example 8-1 Basic Section to Segment Assignment

        1    $mapfile_version 2
        2    LOAD_SEGMENT elephant {
        3            ASSIGN_SECTION {
        4                    IS_NAME=.data;
        5                    FILE_PATH=peanuts.o;
        6            };
        7            ASSIGN_SECTION {
        8                    IS_NAME=.data;
        9                    FILE_OBJNAME=popcorn.o;
       10           };
       11   };
       12
       13   LOAD_SEGMENT monkey {
       14           VADDR=0x80000000;
       15           MAX_SIZE=0x4000;
       16           ASSIGN_SECTION {
       17                   TYPE=progbits;
       18                   FLAGS=ALLOC EXECUTE;
       19           };
       20           ASSIGN_SECTION {
       21                   IS_NAME=.data
       22           };
       23   };
       24
       25   LOAD_SEGMENT donkey {
       26           FLAGS=READ EXECUTE;
       27           ALIGN=0x1000;
       28           ASSIGN_SECTION {
       29                   IS_NAME=.data;
       30           };
       31   };
       32
       33   LOAD_SEGMENT text {
       34           VADDR=0x80008000
       35   };

Four separate segments are manipulated in this example. Every mapfile starts with a $mapfile_version declaration as shown on line 1. Segment elephant (lines 2-11) receives all of the data sections from the files peanuts.o or popcorn.o. The object popcorn.o can come from an archive, in which case the archive file can have any name. Alternatively, popcorn.o can come from any file with a basename of popcorn.o. In contrast, peanuts.o can only come from a file with exactly that name. For example, the file /var/tmp/peanuts.o supplied to a link-edit does not match peanuts.o.

Segment monkey (lines 13-23) has a virtual address of 0x80000000, and a maximum length of 0x4000. This segment receives all sections that are both PROGBITS and allocable-executable, as well as all sections not already in the segment elephant with the name .data. The .data sections entering the monkey segment need not be PROGBITS or allocable-executable, because they match the entrance criterion on line 20 rather than the one on line 16. This illustrates that and and relationship exists between the sub-attributes within a ASSIGN_SECTION attribute, while an or relationship exists between the different ASSIGN_SECTION attributes for a single segment.

The donkey segment (lines 25-31) is given non-default permission flags and alignment, and will accept all sections named .data. However, this segment will never be assigned any sections, and as a result, segment donkey will never appear in the output object. The reason for this is that the link-editor examines entrance criteria in the order they appear in the mapfile. In this mapfile, segment elephant accepts some .data sections, and segment monkey takes any that are left, leaving none for donkey.

Lines 33-35 set the virtual address of the text segment to 0x80008000. The text segment is one of the standard predefined segments, as described in Predefined Segments, so this statement modifies the existing segment rather than creating a new one.

Example: Predefined Section Modification

The following mapfile example manipulates the predefined text and data segments, header options and section within segment ordering.

Example 8-2 Predefined Section Manipulation and Section to Segment Assignment

        1    $mapfile_version 2
        2    HDR_NOALLOC;
        3
        4    LOAD_SEGMENT text {
        5            VADDR=0xf0004000;
        6            FLAGS=READ EXECUTE;
        7            OS_ORDER=.text .rodata;
        9            ASSIGN_SECTION {
       10                   TYPE=PROGBITS;
       11                   FLAGS=ALLOC !WRITE;
       12           };
       13   };
       14
       15   LOAD_SEGMENT data {
       16           FLAGS=READ WRITE EXECUTE;
       17           ALIGN=0x1000;
       18           ROUND=0x1000;
       19   };

As always, the first line declares the mapfile language version to be used. The HDR_NOALLOC directive (line 2) specifies that the resulting object should not include the ELF header or program header array within the first allocable segment in the object, which is the predefined text segment.

The segment directive on lines 4-13 set a virtual address and permission flags for the text segment. This directive also specifies that sections named .text sections should be placed at the head of the segment, followed by any sections named .rodata, and that all other sections will follow these. Finally, allocable, non-writable PROGBITS sections are assigned to the segment.

The segment directive on lines 15-19 specifies that the data segment must be aligned on a boundary of 0x1000. This has the effect of aligning the first section within the segment at the same alignment. The length of the segment is to be rounded up to a multiple of the same value as the alignment. The segment permissions are set to read, write, and execute.