4.1. C and C++ Run-Time Support Libraries

ARM compiler releases include pre-built run-time support (RTS) libraries that provide all the standard capabilities. Separate libraries are provided for each mode, big and little endian support, each ABI (compiler version 4.1.0 and later), various architectures, and C++ exception support. See Library Naming Conventions for information on the library-naming conventions.

The run-time-support library contains the following:

  • ANSI/ISO C/C++ standard library

  • C I/O library

  • Low-level support functions that provide I/O to the host operating system

  • Fundamental arithmetic routines

  • System startup routine, _c_int00

  • Compiler helper functions (to support language features that are not directly efficiently expressible in C/C++)

The run-time-support libraries do not contain functions involving signals and locale issues.

The C++ library supports wide chars, in that template functions and classes that are defined for char are also available for wide char. For example, wide char stream classes wios, wiostream, wstreambuf and so on (corresponding to char classes ios, iostream, streambuf) are implemented. However, there is no low-level file I/O for wide chars. Also, the C library interface to wide char support (through the C++ headers <cwchar> and <cwctype>) is limited as described in C/C++ Language Options.

TI does not provide documentation that covers the functionality of the C++ library. TI suggests referring to one of the following sources:

  • The Standard C++ Library: A Tutorial and Reference, Nicolai M. Josuttis, Addison-Wesley, ISBN 0-201-37926-0

  • The C++ Programming Language (Third or Special Editions), Bjarne Stroustrup, Addison-Wesley, ISBN 0-201-88954-4 or 0-201-70073-5

Note

You can avoid linking with the C and C++ Run-Time Support Libraries by using the -nostdlib compiler option. See C/C++ Run-Time Standard Header and Library Options for more information.

4.1.1. Linking Code With the Object Library

When you link your program, you must specify the object library as one of the linker input files so that references to the I/O and run-time-support functions can be resolved. You can either specify the library or allow the compiler to select one for you. See Automatic Library Selection (--disable_auto_rts Option) for further information.

When a library is linked, the linker includes only those library members required to resolve undefined references. For more information about linking, see Linker Description.

C, C++, and mixed C and C++ programs can use the same run-time-support library. Run-time-support functions and variables that can be called and referenced from both C and C++ will have the same linkage.

If you want to link object files created with the TI CodeGen tools with object files generated by other compiler tool chains, the Arm standard specifies that you should define the _AEABI_PORTABILITY_LEVEL preprocessor symbol as follows before #including any standard header files, such as <stdlib.h>.

#define _AEABI_PORTABILITY_LEVEL 1

This definition enables full portability. Defining the symbol to 0 specifies that the “C standard” portability level will be used.

4.1.2. Header Files

You must use the header files provided with the compiler run-time support when using functions from C/C++ standard library.

The following header files provide TI extensions to the C standard:

  • cpy_tbl.h – Declares the copy_in() RTS function, which is used to move code or data from a load location to a separate run location at run-time. This function helps manage overlays.

  • file.h – Declares functions used by low-level I/O functions in the RTS library.

  • _lock.h – Used when declaring system-wide mutex locks. This header file is deprecated; use _reg_mutex_api.h and _mutex.h instead.

  • memory.h – Provides the memalign() function, which is not required by the C standard.

  • _mutex.h – Declares functions used by the RTS library to help facilitate mutexes for specific resources that are owned by the RTS. For example, these functions are used for heap or file table allocation.

  • _pthread.h – Declares low-level mutex infrastructure functions and provides support for recursive mutexes.

  • _reg_mutex_api.h – Declares a function that can be used by an RTOS to register an underlying lock mechanism and/or thread ID mechanism that is implemented in the RTOS but is called indirectly by the RTS’ _mutex.h functions.

  • _reg_synch_api.h – Declares a function that can be used by an RTOS to register an underlying cache synchronization mechanism that is implemented in the RTOS but is called indirectly by the RTS’ _data_synch.h functions.

  • strings.h – Provides additional string functions, including bcmp(), bcopy(), bzero(), ffs(), index(), rindex(), strcasecmp(), and strncasecmp().

4.1.3. Support for String and Character Handling

The library includes the header files <string.h>, <strings.h>, and <wchar.h>, which provide the following functions for string handling beyond those required.

  • string.h

    • memcpy(), which copies memory from one location to another

    • memcmp(), which compares sections of memory

    • strcmp() and strncmp(), which perform case-sensitive string comparisons

    • strdup(), which duplicates a string by dynamically allocating memory and copying the string to this allocated memory

    • strlen_s(), which is the same as the strlen() function, except that it provides checking for null pointers or strings that are not null-terminated. This function is available only if you are using C11/C++11 or later and if you have used #define to set __STDC_WANT_LIB_EXT1__ to the integer constant 1 prior to the #include statement for string.h.

  • strings.h

    • bcmp(), which is equivalent to memcmp()

    • bcopy(), which is equivalent to memmove()

    • bzero(), which is equivalent to memset(.., 0, …);

    • ffs(), which finds the first bit set and returns the index of that bit

    • index(), which is equivalent to strchr()

    • rindex(), which is equivalent to strrchr()

    • strcasecmp() and strncasecmp(), which perform case-insensitive string comparisons

  • wchar.h

    • wcsnlen_s(), which is the same as the wcsnlen() function, except that it provides checking for null pointers or strings that are not null-terminated. This function is available only if you are using C11/C++11 or later and if you have used #define to set __STDC_WANT_LIB_EXT1__ to the integer constant 1 prior to the #include statement for wchar.h.

4.1.4. Minimal Support for Internationalization

The library includes the header files <locale.h>, <wchar.h>, and <wctype.h>, which provide APIs to support non-ASCII character sets and conventions. Our implementation of these APIs is limited in the following ways:

  • The library has minimal support for wide and multibyte characters. The type wchar_t is implemented as int. The wide character set is equivalent to the set of values of type char. The library includes the header files <wchar.h> and <wctype.h> but does not include all the functions specified in the standard. See Generic Compiler Pre-Defined Macro Symbols for more information about extended character sets.

  • The C library includes the header file <locale.h> but with a minimal implementation. The only supported locale is the C locale. That is, library behavior that is specified to vary by locale is hard-coded to the behavior of the C locale, and attempting to install a different locale via a call to setlocale() will return NULL.

4.1.5. Allowable Number of Open Files

In the <stdio.h> header file, the value for the macro FOPEN_MAX has the value of the macro _NFILE, which is set to 10. The impact is that you can only have 10 files simultaneously open at one time (including the pre-defined streams stdin, stdout, and stderr).

The C standard requires that the minimum value for the FOPEN_MAX macro is 8. The macro determines the maximum number of files that can be opened at one time. The macro is defined in the stdio.h header file and can be modified by changing the value of the _NFILE macro and recompiling the library.

4.1.6. Nonstandard Header Files in the Source Tree

The source code in the lib/src subdirectory of the compiler installation contains these non-ANSI include files that are used to build the library:

  • The file.h file includes macros and definitions used for low-level I/O functions.

  • The format.h file includes structures and macros used in printf and scanf.

  • The trgcio.h file includes low-level, target-specific C I/O macro definitions. If necessary, you can customize trgcio.h.

4.1.7. Library Naming Conventions

By default, the linker uses automatic library selection to select the correct run-time-support library (see Invoking the Compiler) for your application. If you select the library manually, you must select the matching library using a naming scheme like the following:

arm<sub><endian>-ti-none-eabi<float>

Where the following must be indicated:

  • <sub>: “v6m”, “v7r”, “v7m”, “v7em”, or “v8m.main”

  • <endian>: “eb” for big-endian or blank for little-endian

  • <float>: “hf” for VFP support or blank for no VFP support

Each directory variant contains the following files and subdirectories:

libc++.a
libc++abi.a
c/libc.a
c/libsysbm.a
except/libc++.a
except/libc++abi.a

The except directory provided for each variant contains C++ run-time-support libraries compiled with exception handling support. These library variants are used automatically if you use the -exceptions compiler option.

For example, on a Windows installation, the directory containing run-time-support libraries for Arm v7r using little-endian code, VFP support, and no exception handling support might be:

C:\mycompilers\ti-cgt-armllvm_3.1.0.LTS\lib\armv7r-ti-none-eabihf

The corresponding libraries with exception handling support would then be:

C:\mycompilers\ti-cgt-armllvm_3.1.0.LTS\lib\armv7r-ti-none-eabihf\except