This document is a specification for the ELF-based Embedded Application Binary Interface (EABI) for the C28x family of processors from Texas Instruments. The EABI is a broad standard that defines the low-level interface between programs, program components, and the execution environment, including the operating system if one is present. Components of the EABI include calling conventions, data layout and addressing conventions, and object file formats.

This specification aims to enable tool providers, software providers, and users of the C28x to build tools and programs that can interoperate with each other.

Prior to release 18.12.0.LTS of TI's C28x Compiler Tools , the one and only ABI for C28x was the original COFF-based ABI. It was strictly a bare-metal ABI; there was no execution-level component.

Release 18.12.0.LTS of the TI Compiler Tools introduced a new ABI called the C28x EABI. It is based on the ELF object file format. It is derived from industry standard models, including the IA-64 C++ ABI and the System V ABI for ELF and Dynamic Linking. The processor-specific aspects of the ABI, such as data layout and calling conventions, are largely unchanged from the COFF ABI, although there are some differences. Needless to say, the COFF ABI and the EABI are incompatible; that is to say, all of the code in a given system must follow the same ABI. TI's compiler tools support both the new EABI and the older COFF ABI, although we encourage migration to the new ABI as support for the COFF ABI may be discontinued in the future.

A platform is the software environment upon which a program runs. The ABI has platform-specific aspects, particularly in the area of conventions related to the execution environment, such as the number and use of program segments, addressing conventions, visibility conventions, pre-emption, program loading, and initialization. Currently bare metal is the only supported platform. The term bare metal represents the absence of any specific environment. That is not to say there cannot be an OS; it simply says that there are no OS-specific ABI specifications. In other words, how the program is loaded and run, and how it interacts with other parts of the system, is not covered by the bare-metal ABI.

The bare-metal ABI allows substantial variability in many specific aspects. For example, an implementation may provide position independence (PIC), but if a given system does not require position independence, these conventions do not apply. Because of this variability, programs may still be ABI-conforming but incompatible; for example if one program uses PIC but the other does not, they cannot interoperate. Toolchains should endeavor to enforce such incompatibilities.

Figure 1-1 shows the components of the ABI and their relationship. We will briefly describe the components, beginning with the lower part of the diagram and moving upward, and provide references to the appropriate chapter of this ABI specification.

The components in the bottom area relate to object-level interoperability.

Figure 1-1 Parts of the ABI Specification

The C Language ABI (Chapter 2, Chapter 3, Chapter 4, Chapter 5, Chapter 6 and Chapter 7) specifies function calling conventions, data type representations, addressing conventions, and the interface to the C run-time library.

The C++ ABI (Chapter 8) specifies how the C++ language is implemented; this includes details about virtual function tables, name mangling, how constructors are called, and the exception handling mechanism (Chapter 9). The C28x C++ ABI is based on the prevalent IA-64 (Itanium) C++ ABI.

The DWARF component (Chapter 10) specifies the representation of object-level debug information. The base standard is the DWARF3 standard. This specification details processor-specific extensions.

The ELF component (Chapter 11) specifies the representation of object files. This specification extends the System V ABI specification with processor specific information.

Build Attributes (Chapter 13) refer to a means of encoding into an object file various parameters that affect inter-object compatibility, such as target device assumptions, memory models, or ABI variants. Toolchains can use build attributes to prevent incompatible object files from being combined or loaded.

The components in the central area of the diagram relate to execution-time interoperability.

The components in the top part of Figure 1-1 augment the ABI with platform-specific conventions that define the requirements for executables to be compatible with an execution environment, such as the number and use of program segments, addressing conventions, visibility conventions, pre-emption, program loading, and initialization. Bare-Metal refers to the absence of any specific environment.

Finally, there is a set of specifications that are not formally part of the ABI but are documented here both for reference and so that other toolchains can optionally implement them.

Initialization (Chapter 14) refers to the mechanism whereby initialized variables obtain their initial value. Nominally these variables reside in the .data section and they are initialized directly when the .data section is loaded, requiring no additional participation from the tools. However the TI toolchain supports a mechanism whereby the .data section is encoded into the object file in compressed form, and decompressed at startup time. This is a special use of a general mechanism that programmatically copies compressed code or data from offline storage (e.g. ROM) to its execution address. We refer to this facility as copy tables. While not part of the ABI, the initialization and copy table mechanism is documented here so that other toolchains can support it if desired.

As mentioned, the ABI does not define specific behavior in all instances but rather is a canon of principles that allow for platform or system-specific variation. There are model variants within the ABI that may be used or not used. The ABI standardizes the implementation in cases where such variants are used. Some of the variants are incompatible with each other. If any object uses a particular model, all objects must. In such cases, toolchains are expected to use build attributes to prevent incompatible objects from being combined.

• Bare Metal—Standalone. This model refers to a single self-contained statically-linked executable. It is the simplest form in terms of interoperability. The relevant parts of the ABI are the object-level components in the lower part of Figure 1-1. Since the executable is statically linked and bound (relocated), there is no need for position-independence.

This ABI is not specific to any particular vendor's toolchain. In fact, its purpose is to enable alternative toolchains to exist and interoperate. The ABI describes how mechanisms are implemented; not how toolchains support them at the user level. Occasionally references are made to the TI tools, these are for illustration only. However, TI's C28x Compiler Tools by nature have unique status since they originate from the silicon vendor and were co-developed with the ABI specification, and in some cases form its basis.

In cases where the behavior of the TI tools conflict with this ABI, it shall be considered a defect in the tools; if you find such a case, please submit a defect report to support@tools.ti.com. However, in cases where this specification is incomplete or unclear, the behavior of the TI tools shall be considered definitive. A major goal of the ABI standard is interoperability with TI tools; toolchain vendors should strive to meet this goal regardless of omissions or ambiguities in the standard itself. Please notify us in such cases and we will endeavor to clarify the specification.

Generally, a toolchain includes a linker as well as standard run-time libraries that implement part of the language support provided by the toolchain.

The library format used by the C28x is the common GNU/SVR4 ar format.

Often the linker and libraries have interdependencies that are outside the realm of the ABI. For example, many linkers use special symbols to control the inclusion or exclusion of various library components; alternatively some libraries refer to special linker-defined symbols. For this reason the linker and library are expected to come from the same toolchain. Using a linker from one toolchain and a library from a different one is not supported under this ABI. This only applies to the built-in libraries that are part of the toolchain; application libraries built with a different toolchain can be linked.

ELF defines the following distinct classes of object files:

• A relocatable file holds code and data suitable for static linking with other object files to create an executable file.
• An executable file holds a program suitable for execution.

This specification uses the terms static link unit and load module interchangeably to refer to executables .

An ELF load module (an executable file ) represents the memory image of the program in the form of segments. In this context a segment is a contiguous, indivisible range of memory with common properties. A segment becomes bound when its address is determined, which happens statically at link time.