• Menu
  • Product
  • Email
  • PDF
  • Order now
  • C28x Embedded Application Binary Interface

    • SPRAC71A March   2019  – February 2020

       

  • CONTENTS
  • SEARCH
  • C28x Embedded Application Binary Interface
  1. 1 Introduction
    1. 1.1  ABIs for the C28x
    2. 1.2  Scope
    3. 1.3  ABI Variants
    4. 1.4  Toolchains and Interoperability
    5. 1.5  Libraries
    6. 1.6  Types of Object Files
    7. 1.7  Segments
    8. 1.8  C28x Architecture Overview
    9. 1.9  C28x Memory Models
    10. 1.10 Reference Documents
    11. 1.11 Code Fragment Notation
  2. 2 Data Representation
    1. 2.1 Basic Types
    2. 2.2 Data in Registers
    3. 2.3 Data in Memory
    4. 2.4 Pointer Types
    5. 2.5 Complex Types
    6. 2.6 Structures and Unions
    7. 2.7 Arrays
    8. 2.8 Bit Fields
      1. 2.8.1 Volatile Bit Fields
    9. 2.9 Enumeration Types
  3. 3 Calling Conventions
    1. 3.1 Call and Return
      1. 3.1.1 Call Instructions
        1. 3.1.1.1 Indirect Calls
        2. 3.1.1.2 Direct Calls
      2. 3.1.2 Return Instruction
      3. 3.1.3 Pipeline Conventions
      4. 3.1.4 Weak Functions
    2. 3.2 Register Conventions
      1. 3.2.1 Argument Registers
      2. 3.2.2 Callee-Saved Registers
    3. 3.3 Argument Passing
      1. 3.3.1 Passing 16-Bit Arguments
      2. 3.3.2 Passing Longer Arguments
      3. 3.3.3 C++ Argument Passing
      4. 3.3.4 Passing Structs and Unions
      5. 3.3.5 Stack Layout of Arguments Not Passed in Registers
      6. 3.3.6 Frame Pointer
    4. 3.4 Return Values
    5. 3.5 Structures and Unions Passed and Returned by Reference
    6. 3.6 Conventions for Compiler Helper Functions
    7. 3.7 Prolog and Epilog Helper Functions
    8. 3.8 Scratch Registers for Functions Already Seen
    9. 3.9 Interrupt Functions
  4. 4 Data Allocation and Addressing
    1. 4.1 Data Sections and Segments
    2. 4.2 Data Blocking
    3. 4.3 Addressing Modes
    4. 4.4 Allocation and Addressing of Static Data
      1. 4.4.1 Addressing Methods for Static Data
      2. 4.4.2 Placement Conventions for Static Data
        1. 4.4.2.1 Abstract Conventions for Addressing
      3. 4.4.3 Initialization of Static Data
    5. 4.5 Automatic Variables
    6. 4.6 Frame Layout
      1. 4.6.1 Stack Alignment
      2. 4.6.2 Register Save Order
    7. 4.7 Heap-Allocated Objects
  5. 5 Code Allocation and Addressing
    1. 5.1 Computing the Address of a Code Label
    2. 5.2 Calls
      1. 5.2.1 Direct Call
      2. 5.2.2 Far Call Trampoline
      3. 5.2.3 Indirect Calls
  6. 6 Helper Function API
    1. 6.1 Floating-Point Behavior
    2. 6.2 C Helper Function API
    3. 6.3 Floating-Point Helper Functions for C99
  7. 7 Standard C Library API
    1. 7.1  About Standard C Libraries
    2. 7.2  Reserved Symbols
    3. 7.3  <assert.h> Implementation
    4. 7.4  <complex.h> Implementation
    5. 7.5  <ctype.h> Implementation
    6. 7.6  <errno.h> Implementation
    7. 7.7  <float.h> Implementation
    8. 7.8  <inttypes.h> Implementation
    9. 7.9  <iso646.h> Implementation
    10. 7.10 <limits.h> Implementation
    11. 7.11 <locale.h> Implementation
    12. 7.12 <math.h> Implementation
    13. 7.13 <setjmp.h> Implementation
    14. 7.14 <signal.h> Implementation
    15. 7.15 <stdarg.h> Implementation
    16. 7.16 <stdbool.h> Implementation
    17. 7.17 <stddef.h> Implementation
    18. 7.18 <stdint.h> Implementation
    19. 7.19 <stdio.h> Implementation
    20. 7.20 <stdlib.h> Implementation
    21. 7.21 <string.h> Implementation
    22. 7.22 <tgmath.h> Implementation
    23. 7.23 <time.h> Implementation
    24. 7.24 <wchar.h> Implementation
    25. 7.25 <wctype.h> Implementation
  8. 8 C++ ABI
    1. 8.1  Limits (GC++ABI 1.2)
    2. 8.2  Export Template (GC++ABI 1.4.2)
    3. 8.3  Data Layout (GC++ABI Chapter 2)
    4. 8.4  Initialization Guard Variables (GC++ABI 2.8)
    5. 8.5  Constructor Return Value (GC++ABI 3.1.5)
    6. 8.6  One-Time Construction API (GC++ABI 3.3.2)
    7. 8.7  Controlling Object Construction Order (GC++ ABI 3.3.4)
    8. 8.8  Demangler API (GC++ABI 3.4)
    9. 8.9  Static Data (GC++ ABI 5.2.2)
    10. 8.10 Virtual Tables and the Key function (GC++ABI 5.2.3)
    11. 8.11 Unwind Table Location (GC++ABI 5.3)
  9. 9 Exception Handling
    1. 9.1  Overview
    2. 9.2  PREL31 Encoding
    3. 9.3  The Exception Index Table (EXIDX)
      1. 9.3.1 Pointer to Out-of-Line EXTAB Entry
      2. 9.3.2 EXIDX_CANTUNWIND
      3. 9.3.3 Inlined EXTAB Entry
    4. 9.4  The Exception Handling Instruction Table (EXTAB)
      1. 9.4.1 EXTAB Generic Model
      2. 9.4.2 EXTAB Compact Model
      3. 9.4.3 Personality Routines
    5. 9.5  Unwinding Instructions
      1. 9.5.1 Common Sequence
      2. 9.5.2 Byte-Encoded Unwinding Instructions
    6. 9.6  Descriptors
      1. 9.6.1 Encoding of Type Identifiers
      2. 9.6.2 Scope
      3. 9.6.3 Cleanup Descriptor
      4. 9.6.4 Catch Descriptor
      5. 9.6.5 Function Exception Specification (FESPEC) Descriptor
    7. 9.7  Special Sections
    8. 9.8  Interaction With Non-C++ Code
      1. 9.8.1 Automatic EXIDX Entry Generation
      2. 9.8.2 Hand-Coded Assembly Functions
    9. 9.9  Interaction With System Features
      1. 9.9.1 Shared Libraries
      2. 9.9.2 Overlays
      3. 9.9.3 Interrupts
    10. 9.10 Assembly Language Operators in the TI Toolchain
  10. 10DWARF
    1. 10.1 DWARF Register Names
    2. 10.2 Call Frame Information
    3. 10.3 Vendor Names
    4. 10.4 Vendor Extensions
  11. 11ELF Object Files (Processor Supplement)
    1. 11.1 Registered Vendor Names
    2. 11.2 ELF Header
    3. 11.3 Sections
      1. 11.3.1 Section Indexes
      2. 11.3.2 Section Types
      3. 11.3.3 Extended Section Header Attributes
      4. 11.3.4 Subsections
      5. 11.3.5 Special Sections
      6. 11.3.6 Section Alignment
    4. 11.4 Symbol Table
      1. 11.4.1 Symbol Types
      2. 11.4.2 Common Block Symbols
      3. 11.4.3 Symbol Names
      4. 11.4.4 Reserved Symbol Names
      5. 11.4.5 Mapping Symbols
    5. 11.5 Relocation
      1. 11.5.1 Relocation Types
        1. 11.5.1.1 Absolute Relocations
        2. 11.5.1.2 PC-Relative Relocations
        3. 11.5.1.3 Relocations in Data Sections
        4. 11.5.1.4 Relocations for C28x Instructions
        5. 11.5.1.5 Other Relocation Types
      2. 11.5.2 Relocation Operations
      3. 11.5.3 Relocation of Unresolved Weak References
  12. 12ELF Program Loading and Linking (Processor Supplement)
    1. 12.1 Program Header
      1. 12.1.1 Base Address
      2. 12.1.2 Segment Contents
      3. 12.1.3 Thread-Local Storage
    2. 12.2 Program Loading
  13. 13Build Attributes
    1. 13.1 About Build Attributes
    2. 13.2 C28x ABI Build Attribute Subsection
    3. 13.3 C28x Build Attribute Tags
  14. 14Copy Tables and Variable Initialization
    1. 14.1 About Copy Tables
    2. 14.2 Copy Table Format
    3. 14.3 Compressed Data Formats
      1. 14.3.1 RLE
      2. 14.3.2 LZSS Format
    4. 14.4 Variable Initialization
  15. 15Revision History
  16. IMPORTANT NOTICE
search No matches found.
  • Full reading width
    • Full reading width
    • Comfortable reading width
    • Expanded reading width
  • Card for each section
  • Card with all content

 

APPLICATION NOTE

C28x Embedded Application Binary Interface

1 Introduction

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.

1.1 ABIs for the C28x

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.

1.2 Scope

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.

GUID-FD7386F6-1D68-476A-A047-116D23017467-low.png 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.

1.3 ABI Variants

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.

1.4 Toolchains and Interoperability

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.

1.5 Libraries

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.

1.6 Types of Object Files

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 .

 

Texas Instruments

© Copyright 1995-2025 Texas Instruments Incorporated. All rights reserved.
Submit documentation feedback | IMPORTANT NOTICE | Trademarks | Privacy policy | Cookie policy | Terms of use | Terms of sale