8.4.18 Create a Map File (--map_file Option)

The syntax for the --map_file option is:

--map_file=filename

The linker map describes:

• Memory configuration
• Input and output section allocation
• Linker-generated copy tables
• Trampolines
• The addresses of external symbols after they have been relocated
• Hidden and localized symbols

The map file contains the name of the output module and the entry point; it can also contain up to three tables:

• A table showing the new memory configuration if any nondefault memory is specified (memory configuration). The table has the following columns; this information is generated on the basis of the information in the MEMORY directive in the linker command file:
  • Name. This is the name of the memory range specified with the MEMORY directive.
  • Origin. This specifies the starting address of a memory range.
  • Length. This specifies the length of a memory range.
  • Unused. This specifies the total amount of unused (available) memory in that memory area.
  • Attributes. This specifies one to four attributes associated with the named range:

  	R	specifies that the memory can be read.
  	W	specifies that the memory can be written to.
  	X	specifies that the memory can contain executable code.
  	I	specifies that the memory can be initialized.

For more information about the MEMORY directive, see Section 8.5.4.

• A table showing the linked addresses of each output section and the input sections that make up the output sections (section placement map). This table has the following columns; this information is generated on the basis of the information in the SECTIONS directive in the linker command file:
  • Output section. This is the name of the output section specified with the SECTIONS directive.
  • Origin. The first origin listed for each output section is the starting address of that output section. The indented origin value is the starting address of that portion of the output section.
  • Length. The first length listed for each output section is the length of that output section. The indented length value is the length of that portion of the output section.
  • Attributes/input sections. This lists the input file or value associated with an output section. If the input section could not be allocated, the map file will indicate this with "FAILED TO ALLOCATE".

For more information about the SECTIONS directive, see Section 8.5.5.

• A table showing each external symbol and its address sorted by symbol name.
• A table showing each external symbol and its address sorted by symbol address.

The following example links file1.obj and file2.obj and creates a map file called map.out:

cl6x --run_linker file1.obj file2.obj --map_file=map.out

Example 26 shows an example of a map file.