4.1. C and C++ Run-Time Support Libraries¶
The TI C29x compiler installation includes pre-built run-time support (RTS) libraries that provide all the standard capabilities. Separate libraries are provided for each supported variant. See Library Naming Conventions for information on the library file names and paths.
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.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 C28x compiler, which defines time_t as an unsigned 32-bit value using a TI-defined epoch of January 1, 1900. You do not need to take any special steps or define any macros to use the time_t implementation, just be sure to #include time.h and use the standard C time functions, which automatically map to 64-bit implementations.
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 by setting 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.
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() returns 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, which run-time-support library (see Invoking the Compiler) to link with is determined based on the command-line options used to compile your application, and you do not need to specify the RTS library to the linker.
The pre-built run-time support (RTS) libraries are as follows:
libc.a: C Standardlibc++.a: C++ Standardlibc++abi.a: C++ Supportlibsys.a: Common system-level library, such as file IO and time.libsysbm.a: Common system-level library, such as file IO and time. You may provide your own copy oflibsysbm.ato override the default IO and time functions. See Contents of the libsysbm.a Library for details.libclang_rt.builtins.a: Compiler supportlibclang_rt.profile.a: Instrumentation (code coverage)
The RTS libraries in the <root>/lib directory of the c29clang installation point to a library variant using the following path naming convention:
/lib/c29<subtarget>-ti-none-eabi<variant>
where the subtargets and variants are as follows:
<subtarget>:
.c0is currently the only subtarget.<variant>:
/f64is added to the directory path if the-mfpu=f64option is used, which causes native 32-bit and 64-bit floating-point hardware operations to be used. If no-mfpuoption or-mfpu=noneis used, no variant is added to the path; native 32-bit floating-point hardware operations are used, and 64-bit floating-point operations are emulated in software.
Variants of the libclang_rt.builtins.a and libclang_rt.profile.a libraries have /lib/clang/|lib_version_number| added prior to this path, where <version> is currently “16.0.0”.
For example, if you use no -mfpu option or the -mfpu=none option, the RTS libraries in the following locations are used:
/lib/c29.c0-ti-none-eabi/c/libc.a/lib/c29.c0-ti-none-eabi/c/libsysbm.a/lib/c29.c0-ti-none-eabi/libc++.a/lib/c29.c0-ti-none-eabi/libc++abi.a/lib/clang/<version>/lib/c29.c0-ti-none-eabi/libclang_rt.builtins.a/lib/clang/<version>/lib/c29.c0-ti-none-eabi/libclang_rt.profile.a
If you instead use the -mfpu=f64 option, the RTS libraries in the following locations are used:
/lib/c29.c0-ti-none-eabi/f64/c/libc.a/lib/c29.c0-ti-none-eabi/f64/c/libsysbm.a/lib/c29.c0-ti-none-eabi/f64/libc++.a/lib/c29.c0-ti-none-eabi/f64/libc++abi.a/lib/clang/<version>/lib/c29.c0-ti-none-eabi/f64/libclang_rt.builtins.a/lib/clang/<version>/lib/c29.c0-ti-none-eabi/f64/libclang_rt.profile.a
4.1.8.1. Contents of the libsysbm.a Library¶
The files in the <root>/lib/src directory contain the source code for functions that may be overridden. By default, libsysbm.a contains functions from the following source files:
add_device.cclose.chost_device.chostclock.chostclose.chostgetenv.chostlseek.chostopen.chostread.chostrename.chosttime.chostunlink.chostwrite.clseek.copen.cread.cremove.cremove_device.crename.ctime.ctime64.ctrgmsg.cunlink.cwrite.c