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

  • Time Routines

  • 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.

4.1.1.1. Enabling AEABI Portability

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> or <time.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. Support for time.h and time_t

The library includes the header file <time.h>, which provides the following functions for time handling beyond those required:

  • asctime(), which returns a pointer to a string representing the day and time

  • clock(), which returns the processor clock time

  • ctime(), which returns a string representing the localtime

  • difftime(), which returns the difference in seconds between two times

  • gmtime(), which expresses the time value expressed in Greenwich Mean Time (GMT)

  • localtime(), which returns the time value expressed in the local time zone

  • mktime(), which converts the given time structure into a time_t value

  • strftime(), which formats the time according to given format rules

  • time(), which calculates the current calendar time and returns it as time_t

The library defines time_t by default as a POSIX-compatible signed 64-bit value using the POSIX epoch of January 1, 1970. This is different from the TI proprietary ARM compiler (armcl), which defines time_t as an unsigned 32-bit value using a legacy TI-defined epoch of January 1, 1900. You do not need to take any special steps or define any macros to use the new implementation, just be sure to include time.h and use the standard C time functions, which will automatically map to 64-bit implementations.

4.1.4.1. Enabling AEABI Portability

Enabling AEABI portability mode as described above will force the compiler to use an unsigned 32-bit representation for time_t with POSIX epoch. All calls to the standard C time functions will refer to their 32-bit variants. In addition, the compiler will also ensure that the _AEABI_PORTABLE macro is defined, as required by the standard.

Note

If your program attempts to use or manipulate any time_t with value larger than INT_MAX (which corresponds to a date in 2038), the time functions may not work properly.

You may also interlink third party object code with the tiarmclang linker and runtime library, including calling the standard C time functions, requiring no special steps. You are responsible for ensuring that AEABI portability is used consistently throughout your application.

4.1.4.2. Leveraging the Unsigned 32-bit Representation of time_t

You may also activate the unsigned 32-bit representation of time_t without activating AEABI portability mode. Instead of setting the _AEABI_PORTABILITY_LEVEL macro, simply set the macro __TI_TIME_USES_64=0.

As long as variables of type time_t aren’t used globally, you may freely link object files built using __TI_TIME_USES_64=0 with those that do not since the actual time functions in the RTS are not changed.

Note

The epoch used for time_t functions is an implementation-defined property. For this reason, you should be cautious when attempting to link using time functions defined within a runtime library built using the TI proprietary ARM compiler (armcl) since that compiler does not define values for time_t using the POSIX epoch. You are responsible for ensuring that time_t is used consistently through your application.

4.1.5. 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.6. 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.7. 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.8. 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