CrossStudio section-placement files are structured using XML syntax to enable simple
construction and parsing.
The first entry of the project file defines the XML document type
used to validate the file format:
<!DOCTYPE Linker_Placement_File>
The next entry is the Root element. There can only be one Root element
in a memory map file:
<Root name="Flash Placement">
A Root element has a name attribute. Every element in a section-placement
file has a name attribute. Each name should be unique within its hierarchy level.
Within a Root element, there are MemorySegment elements. These correspond
to memory regions defined in a memory map file that will be used in
conjunction with the section-placement file when linking a program. For example:
<Root name="Flash Placement">
<MemorySegment name="FLASH">
A MemorySegment contains ProgramSection elements that represent program sections created
by the C/C++ compiler and assembler. The order of ProgramSection elements within a MemorySegment
element represents the order in which the sections will be placed when linking a program. The
first ProgramSection will be placed first and the last one will be placed last.
<Root name="My Board" >
<MemorySegment name="FLASH">
<ProgramSection name=".text">
ProgramSection elements have the following attributes:
- address_symbol: A symbolic name for the start address of the section.
- alignment: The required alignment of the program section; a decimal number specifying the byte alignment.
- end_symbol: A symbolic name for the end address of the section.
- fill: The optional value used to fill unspecified regions of memory, a hexadecimal number with a 0x prefix.
- inputsections: An expression describing the input sections to be placed in this section.
If you omit this (recommended) and the section name isn't one of .text, .dtors,
.ctors, .data, .rodata, or .bss, then the equivalent input section of
*(.name .name.*) is supplied to the linker.
- keep: If Yes, the section will be kept even if none of the symbols are referenced by the rest of the program.
- load: If Yes, the section is loaded. If No, the section isn't loaded.
- place_from_segment_end: If Yes, this section and following sections will be placed at the end of the segment. Please note that this will only succeed if the section and all following sections have a fixed size specified with the size attribute.
- runin: This specifies the name of the section to copy this section to. Multiple sections can be specified separated by a semicolon, the first section that exists will be used.
- runoffset: This specifies an offset from the load address that the section will be run from.
- size: The optional size of the program section in bytes, a hexadecimal number with a 0x prefix. The macro $(SEGMENT_SIZE_REMAINING) can be used for size calcuations based on the remaining number of bytes in the segment.
- size_symbol: A symbolic name for the size of the section.
- start: The optional start address of the program section, a hexadecimal number with a 0x prefix.
When a section placement file is used for linking it is preprocessed using the (as yet undocumented)
CrossWorks XML preprocessor.