How C and C++ programs use the library functions

The entry point of a program is at __main in the C library where library code does the following:

If you do not want the library to perform these actions, you can define your own __main that branches to __rt_entry as shown in Example 2.1.

    IMPORT __rt_entry
    EXPORT __main
    ENTRY
__main
    B     __rt_entry
    END

The library function __rt_entry() runs the program as follows:

C++ places certain requirements on the construction and destruction of objects with static storage duration. See section 3.6 of the C++ Standard.

The ARM C++ compiler uses the .init_array area to achieve this. This is a const data array of self‑relative pointers to functions. For example, you might have the following C++ translation unit, contained in the file test.cpp:

struct T
{
    T();
    ~T();
} t;

int f()
{
    return 4;
}

int i = f();

This translates into the following pseudocode:

         AREA ||.text||, CODE, READONLY
     int f()
    {
         return 4;
    }

     static void __sti___8_test_cpp
     {
         // construct 't' and register its destruction
         __aeabi_atexit(T::T(&t), &T::~T, &__dso_handle);
         i = f();
     }
         AREA ||.init_array||, DATA, READONLY
         DCD __sti___8_test_cpp ‑ {PC}

         AREA ||.data||, DATA
     t   % 4
     i   % 4

This pseudocode is for illustration only. To see the code that is generated, compile the C++ source code with armcc ‑c ‑‑cpp ‑S.

The linker collects each .init_array from the various translation units together. It is important that the .init_array is accumulated in the same order.

The library routine __cpp_initialize__aeabi_ is called from the C library startup code, __rt_lib_init, before main. __cpp_initialize__aeabi_ walks through the .init_array calling each function in turn. On exit, __rt_lib_shutdown calls __cxa_finalize.

Usually there is at most one function for T::T(), mangled name _ZN1TC1Ev, one function for T::~T(), mangled name _ZN1TD1Ev, one __sti__ function, and four bytes of .init_array for each translation unit. The mangled name for the function f() is _Z1fv. There is no way to determine the initialization order between translation units.

Function‑local static objects with destructors are also handled using __aeabi_atexit.

Certain sections must be placed contiguously within the same region, for their base/limit symbols to be accessible. If they are not, the linker generates an error.

For example, the .init_array area is generated by the C++ compiler. This area must be placed in the same region as __cpp_initialize__aeabi_. To do this, specify the sections in a scatter‑loading description file, for example:

LOAD_ROM 0x0000000
{
    EXEC_ROM 0x0000000
    {
        init_aeabi.o(+RO)
        * (.init_array)
        ...
    }
    RAM 0x0100000
    {
        * (+RW,+ZI)
    }
}

LOAD_ROM 0x0000000
{
    EXEC_ROM 0x0000000
    {
        init_aeabi.o(+RO)
        init.o(+RO)              ; backwards compatibility
        * (.init_array)
        * (C$$pi_ctorvec)        ; backwards compatibility
        ...
    }
    RAM 0x0100000
    {
        * (+RW,+ZI)
    }
}

The exceptions system can be initialized either on demand (that is, when first used), or before main is entered. Initialization on demand has the advantage of not allocating heap memory unless the exceptions system is used, but has the disadvantage that it becomes impossible to throw any exception (such as std::bad_alloc) if the heap is exhausted at the time of first use.

The default is to initialize on demand. To initialize the exceptions system before main is entered, include the following function in the link:

extern "C" void __cxa_get_globals(void);
extern "C" void __ARM_exceptions_init(void)
{
    __cxa_get_globals();
}

Although you can place the call to __cxa_get_globals directly in your code, placing it in __ARM_exceptions_init ensures that it is called as early as possible. That is, before any global variables are initialized and before main is entered.

__ARM_exceptions_init is weakly referenced by the library initialization mechanism, and is called if it is present as part of __rt_lib_init.

You can choose whether or not to allocate emergency memory that is to be used for throwing a std::bad_alloc exception when the heap is exhausted.

To allocate emergency memory, you must include the symbol __ARM_exceptions_buffer_required in the link. A call is then made to __ARM_exceptions_buffer_init() as part of the exceptions system initialization. The symbol is not included by default.

The following routines manage the exceptions emergency buffer:

Default definitions of these routines are present in the image, but you can supply your own versions to override the defaults supplied by the library. The default routines reserve just enough space for a single std::bad_alloc exceptions object. If you do not require an emergency buffer, it is safe to redefine all these routines to return only NULL.

The function main() is the user‑level root of the application. It requires that the execution environment is initialized, and that input/output functions can be called. While in main() the program might perform one of the following actions that calls user‑customizable functions in the C library: