XMOS executable (XE) file format¶
The XMOS executable (XE) binary file format holds executable programs compiled to run on XMOS devices. The format supports distinct programs for each xCORE tile in a multi-tile or multi-chip design, and allows multiple loads and runs on each tile.
In addition to the program itself, an XE file contains a description of the system it is intended to run on. This description takes the form of either an XML system configuration description or a 64-bit per-node system identifier.
Binary format¶
The following sections explain the common elements of the binary format. All data is encoded as little endian.
XE header¶
An XE file must start with an XE header. It has the following format:
Byte offset |
Length (bytes) |
Description |
|---|---|---|
0x0 |
4 |
The string |
0x4 |
1 |
Major version number (2). |
0x5 |
1 |
Minor version number (0). |
0x6 |
2 |
Reserved. Must be set to zero. |
Sectors¶
The XE header is followed by a list of sectors. The end of the sector list must be marked using a sector with a sector type of 0x5555. Each sector consists of a sector header, optionally followed by a variable-length sector contents block containing sector data. Padding is added after the sector data to make the sector contents block a whole number of 32-bit words.
Byte offset |
Length (bytes) |
Description |
|---|---|---|
0x0 |
2 |
Sector type. |
0x2 |
2 |
Reserved. Must be set to zero. |
0x4 |
8 |
Size in bytes of the sector contents block. Set to zero if this sector has no sector contents block. |
Byte offset |
Length (bytes) |
Description |
|---|---|---|
0x0 |
1 |
Size in bytes of the padding after the sector data. |
0x1 |
3 |
Reserved. Must be set to zero. |
0x4 |
n |
Sector data. |
0x4+n |
p |
Padding bytes to align to the next 32-bit word. |
0x4+n+p |
4 |
Sector CRC. |
The sector CRC is calculated on the byte stream from the start of the sector header to the byte before the sector CRC. The polynomial used is 0x04C11DB7 (IEEE 802.3); the CRC register is initialized with 0xFFFFFFFF and residue is inverted to produce the CRC.
The following sector types are defined:
Value |
Name |
Description |
|---|---|---|
0x1 |
Binary |
Load binary image. |
0x2 |
ELF |
Load ELF image. |
0x3 |
SysConfig |
System description XML. |
0x4 |
NodeDescriptor |
Node description. |
0x5 |
Goto |
Start execution. |
0x6 |
Call |
Start execution and wait for return. |
0x8 |
XN |
XN description. |
0x5555 |
Last sector |
Marks the end of the file. |
0xFFFF |
Skip |
Skip this sector. |
The meaning of the sector data depends on the sector type. The following sections provide further details of the format of the sector data for each sector type.
SysConfig sector¶
The SysConfig sector contains a full XML description of the system, including number of nodes, xCORE tiles and link/interconnect configuration. This information is provided by XMOS to describe its chip products. The format of the SysConfig sector is currently undocumented.
Node descriptor sector¶
The NodeDescriptor sector describes an individual node, allowing the toolchain to validate an executable file matches the target device. There may be 0 or more NodeDescriptor sectors.
Data byte offset |
Length (bytes) |
Description |
|---|---|---|
0x0 |
2 |
Index of the node in the JTAG scan chain. |
0x2 |
2 |
Reserved. |
0x4 |
4 |
Device JTAG ID. |
0x8 |
4 |
Device JTAG user ID. |
XN sector¶
The XN sector contains a XN description of the system.
Binary/ELF sectors¶
Binary or ELF sectors instruct the loader to load a program image on the specified xCORE tile. Binary/ELF sectors are formatted as shown in the following table:
Data byte offset |
Length (bytes) |
Description |
|---|---|---|
0x0 |
2 |
Index of the node in the JTAG scan chain. |
0x2 |
2 |
xCORE tile number. |
0x4 |
8 |
Load address of the binary image data. For ELF sectors this field should be set to 0. |
0xC |
n |
Image data. |
When a binary sector is loaded the data field is copied into memory starting at the specified load address. When a ELF sector is loaded the loadable segments of ELF image contained in the data field are loaded to the addresses specified in the ELF image.
Goto/call sectors¶
Goto and call sectors instruct the loader to execute code on the specified
xCORE tile. If the last image loaded onto the tile was a ELF image execution
starts at address of the _start symbol, otherwise execution starts at address
specified as a field in the sector.
When processing a call sector the loader should wait for the code to indicate successful termination via a done or exit system call before processing the next sector.
Data byte offset |
Length (bytes) |
Description |
|---|---|---|
0x0 |
2 |
Index of the node in the JTAG scan chain. |
0x2 |
2 |
xCORE tile number. |
0x4 |
8 |
Specifies the address to jump to if the last image loaded onto the tile was a binary image. This field should be set to 0 if the last image loaded was an ELF image. |
Last sector¶
The last sector type is used to indicate the end of the sector list. A sector of this type should have no sector contents block.
Skip sector¶
A loader must ignore any skip sectors that appear in the sector list. Changing the type of an existing sector to the skip sector type allows removal of sectors without effecting the layout of the XE file.
Booting an XE File¶
To boot an XE file the sectors within the file must be processed in sequential order. This allows a loader to load and execute sectors to initialize the system in an order defined by the toolchain, using as many boot stages as required. If an image is loaded onto an xCORE tile there must be exactly one Goto sector. This sector must appear after all Call, Binary and ELF sectors for that tile.
A loader may choose to delay processing of Call sectors until a set of Call sectors have been accumulated for all xCORE tiles on the target device. This allows the loader to reduce boot time by executing as much code as possible in parallel.
The example in Example XE file shows a typical layout for an XE file containing a program compiled to run on a 4-tile XS1-G4 device.
Sector type |
Node |
Tile |
Description |
|---|---|---|---|
SysConfig |
XML System description, ignored by the loader. |
||
XN |
XN description, ignored by the loader. |
||
ELF |
0 |
3 |
Load ELF image onto node 0 tile 3. |
Call |
0 |
3 |
Execute program on node 0 tile 3 and wait for successful termination. |
ELF |
0 |
2 |
Load ELF image onto node 0 tile 2. |
Call |
0 |
2 |
Execute program on node 0 tile 2 and wait for successful termination. |
ELF |
0 |
1 |
Load ELF image onto node 0 tile 1. |
Call |
0 |
1 |
Execute program on node 0 tile 1 and wait for successful termination. |
ELF |
0 |
0 |
Load ELF image onto node 0 tile 0. |
Call |
0 |
0 |
Execute program on node 0 tile 0 and wait for successful termination. |
ELF |
0 |
3 |
Load ELF image onto node 0 tile 3. |
Goto |
0 |
3 |
Execute program on node 0 tile 3. |
ELF |
0 |
2 |
Load ELF image onto node 0 tile 2. |
Goto |
0 |
2 |
Execute program on node 0 tile 2. |
ELF |
0 |
1 |
Load ELF image onto node 0 tile 1. |
Goto |
0 |
1 |
Execute program on node 0 tile 1. |
ELF |
0 |
0 |
Load ELF image onto node 0 tile 0. |
Goto |
0 |
0 |
Execute program on node 0 tile 0. |
Last sector |
Last sector marker. |
A further example is given in the tutorial Understanding XE files and how they are loaded.