C2000 C/C++ CODE GENERATION TOOLS 18.9.0.STS Release Notes September 2018 ================================================================================ Contents ================================================================================ 1) Support Information 2) New Features 2.1) Linker generated ECC option 2.2) Float support for 64-bit FPU hardware 2.3) Support for C2000 EABI 2.4) Support for TMU1 Instructions 2.5) Support for VCRC Device 2.6) Support for Integer Division Hardware Extension ------------------------------------------------------------------------------- 1. Support Information ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- 1.1) List of Fixed and Known Defects ------------------------------------------------------------------------------- As of the 16.12.0.STS release, the DefectHistory.txt file has been replaced with the two files Open_defects.html and Closed_defects.html. For open bugs, a status of Open or Accepted means that the bug has not been examined yet, whereas a status of Planned means that an evaluation or fix is in progress. ------------------------------------------------------------------------------- 1.2) Compiler Wiki ------------------------------------------------------------------------------- A Wiki has been established to assist developers in using TI Embedded Processor Software and Tools. Developers are encouraged to read and contribute to the articles. Registered users can update missing or incorrect information. There is a large section of compiler-related material. Please visit: http://processors.wiki.ti.com/index.php?title=Category:Compiler ------------------------------------------------------------------------------- 1.3) Compiler Documentation Errata ------------------------------------------------------------------------------- Errata for the "TI C2000 Optimizing Compiler User's Guide" and the "TI C2000 Assembly Language User's Guide" is available online at the Texas Instruments Embedded Processors CG Wiki: http://processors.wiki.ti.com/index.php?title=Category:Compiler under the 'Compiler Documentation Errata' link. ------------------------------------------------------------------------------- 1.4) TI E2E Community ------------------------------------------------------------------------------- Questions concerning TI Code Generation Tools can be posted to the TI E2E Community forums. The "Development Tools" forum can be found at: http://e2e.ti.com/support/development_tools/f/default.aspx ------------------------------------------------------------------------------- 1.5) Defect Tracking Database ------------------------------------------------------------------------------- Compiler defect reports can be tracked at the Development Tools bug database, SDOWP. The log in page for SDOWP, as well as a link to create an account with the defect tracking database is found at: https://cqweb.ext.ti.com/pages/SDO-Web.html A my.ti.com account is required to access this page. To find an issue in SDOWP, enter your bug id in the "Find Record ID" box once logged in. To find tables of all compiler issues click the queries under the folder: "Public Queries" -> "Development Tools" -> "TI C-C++ Compiler" With your SDOWP account you can save your own queries in your "Personal Queries" folder. ------------------------------------------------------------------------------- 1.6) Short Term Support release ------------------------------------------------------------------------------- The C2000 CGT v18.9.0.STS release is a short term support (STS) release. This release will be supported only until the next STS or LTS release. ------------------------------------------------------------------------------- 2. New Features ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- 2.1) Linker generated ECC option ------------------------------------------------------------------------------- In previous versions, linker generated ECC has been enabled via an ECC specifier on memory ranges in the linker command file. This makes it difficult for TI to provide linker command files with ECC specified because users need the ability to enable/disable the support. Starting with this version, users can enable/disable ecc support via the --ecc=[on|off] linker option. Existing users of ECC will need to specify --ecc=on to generate ECC from the linker. ------------------------------------------------------------------------------- 2.2) Float support for 64-bit FPU hardware ------------------------------------------------------------------------------- The 18.9.0.STS compiler generates code for C28x device with 64-bit FPU coprocessor. Users should use below options to generate code for FPU64: -v28 --float_support=fpu64 --abi=eabi The RTS libraries to be used with FPU64 are: rts2800_fpu64_eabi.lib (RTS without exception handling support) rts2800_fpu64_eabi_eh.lib (RTS with exception handling support) In FPU64 mode, the compiler uses specialized floating point instructions wherever possible, rather than calling RTS routines to perform float operations. This feature is being released to support early development. More details will be included in future releases. ------------------------------------------------------------------------------- 2.3) Support for C2000 EABI (Embedded Application Binary Interface) ------------------------------------------------------------------------------- The C2000 18.9.0.STS compiler supports a new ABI (Application Binary Interface), C2000 EABI, in addition to the current COFFABI. Most existing C2000 software does not currently support EABI, however, this feature is being released to support early development. 2.3.1) Features ------------- C2000 EABI is an ABI for the C2000 architecture based on the ELF object file format. The major features are: - ELF object format - DWARF4 debug format The advantage of EABI is that it provides a modern, well-documented ABI that is well-supported. Many newer C++ language features, such as template instantiation and "extern inline," can be implemented more effectively. Future development of TI's C2000 compiler will be primarily implemented within EABI. 2.3.2) Usage ---------- To compile using EABI, use the shell option --abi=eabi. Compile: > cl2000 --abi=eabi Compile and link: > cl2000 --abi=eabi -z -l When no RTS library is specified in the command line, the linker will choose the right RTS library, provided the RTS library search path environment variable (C2000_C_DIR) is set. 2.3.3) 64-bit "double" -------------------- In EABI mode, the C standard type "double" is 64 bits. In COFF ABI mode, the "double" type remains 32 bits. Because the C standard requires the compiler to treat unsuffixed floating-point constants as type "double," the compiler is required use double-precision arithmetic for expressions involving such constants. Programs which use such constants may run a little slower in EABI. This performance can be reclaimed by changing the constants to have the suffix "f". 2.3.4) Table-Driven Exception Handling ------------------------------------ C2000 compiler version 18.9.0.STS supports table-driven exception handling for ELF executables. Table-driven exception handling is more time-efficient than setjmp/longjmp support when exceptions are not thrown. The user interface is almost entirely the same as the COFFABI support; use the option --exceptions and link with an RTS which has exception handling enabled. For EABI only, if you have any 'extern "C"' functions which need to throw exceptions, you must use the option "--extern_c_can_throw". The underlying implementation is very different. No support will be provided for migrating assembly files generated using the COFF scheme to the EABI environment; such files should be recompiled from the original C++ files. 2.3.6) Migration from COFF to ELF ------------------------------- To take advantage of C2000 EABI, users must explicitly request it using the "--abi=eabi" command-line option. Object files generated with this option will not be compatible with object files generated for COFFABI. However, most C source files will not require modification, and most assembly source files will require only trivial modification. The major differences between EABI and COFFABI are: - Different name mangling - C++ names are mangled using IA64 name mangling scheme - Different C auto-initialization Users need to take specific steps to migrate their projects to EABI: - COFF objects and libraries are not compatible with EABI objects; programs and libraries must be recompiled from source. There is no COFF to ELF conversion utility. ------------------------------------------------------------------------------- 2.4) Support for TMU1 Instructions ------------------------------------------------------------------------------- The C2000 18.9.0.STS compiler supports two new instructions that are available in the latest revision of the Trigonometric Math Unit (TMU): LOG2F32 RaH, RbH ; RaH = log2(RbH) IEXP2F32 RaH, RbH ; RaH = 2^^-|RbH| To enable support for these two instructions, users must specify the "tmu1" argument to the --tmu_support compiler option. Specifically, if a user specifies --tmu_support=tmu1 on the compiler command line it enables all of the capabilities of the TMU0 plus the above two new instructions. You can access the two new TMU1 instructions in C/C++ source code via two new intrinsics: float __log2(float x); /* return log2(x) */ float __iexp2(float x); /* return 2^^-|x| */ If the user specifies --fp_mode=relaxed in combination with the --tmu_support=tmu1 option in the compiler command line, then the following RTS functions will make use of the new __log2 and __iexp2 intrinsics: float log2f(float x); float exp2f(float x); float logf(float x); float expf(float x); float powf(x, y); Files that are compiled with --tmu_support=tmu0 are object compatible with files that are compiled with --tmu_support-tmu1. An application that makes use of any of the new TMU1 capabilities must be run on a system which includes a TMU1. ------------------------------------------------------------------------------- 2.5) Support for VCRC Device ------------------------------------------------------------------------------- The C2000 18.9.0.STS compiler now supports the latest revision of the Viterbi, Complex Math, and CRC Unit (VCU) which supports all of the CRC instructions that have been made available on all previous versions of the VCU. Consequently, the instruction set supported by the new VCRC device is neither a proper subset nor a superset of the instructions supported on previous versions of the VCU device (VCU-I and VCU-II). available in the latest revision of the Trigonometric Math Unit (TMU): C2000 EABI, in addition to the current COFFABI. The new VCRC device supports the following instruction set: VMOV32 VCRC, mem32 VMOV32 mem32, VCRC VCRC8L_1 mem16 VCRC8H_1 mem16 VCRC16P1L_1 mem16 VCRC16P1H_1 mem16 VCRC16P2L_1 mem16 VCRC16P2H_1 mem16 VCRC32L_1 mem16 VCRC32H_1 mem16 VCRC32P2L_1 mem16 VCRC32P2H_1 mem16 VCRCCLR VSETCRCMSGFLIP VCLRCRCMSGFLIP VCRC24L_1 mem16 VCRC24H_1 mem16 VMOVZI VCRCPOLY, #imm16 VMOVIX VCRCPOLY, #imm16 VMOV16 VCRCDSIZE, mem16 VMOV16 VCRCPSIZE, mem16 VSETCRCSIZE #imm5:#imm3 VCRCL mem16 VCRCH mem16 VSWAPCRC VMOV32 VCRCPOLY, mem32 VMOV32 VCRCSIZE, mem32 VMOV32 mem32, VCRCPOLY VMOV32 mem32, VCRCSIZE VNOP VMOV32 loc32,*(0:16bitAddr) VMOV32 *(0:16bitAddr),loc32 VMOV32 VSTATUS, mem32 VMOV32 mem32, VSTATUS Please see the latest revision of the C28x Extended Instruction Sets Technical Reference Manual (spruhs1) for a detailed description of each of the above instructions. To build an application that is anticipated to run on a system which includes the VCRC device, the user must compile their source files with the --vcu_support=vcrc compiler option. Please note that object files built with --vcu_support=vcu0 or --vcu_support=vcu2 are not object compatible with object files that are built with --vcu_support=vcrc. The "vcrc" argument to the --vcu_support option enables support for some CRC instructions that are not available on either the VCU0 or VCU2 devices. Similarly, the "vcu0" and "vcu2" arguments to the --vcu_support option enables support for non-CRC instructions that are not available on the VCRC device. If a user attempts to link one or more VCU0 or VCU2 object files with VCRC object files, the linker will emit an object file compatibility failure message. If the user application is to be run on a system that includes a VCRC device, then all source files in the application must be compiled with either --vcu_support=vcrc or no --vcu_support option (an object file built without a --vcu_support option is compatible with an object file built with the --vcu_support=vcrc option). files during the ------------------------------------------------------------------------------- 2.6) Support for Integer Division Hardware Extension ------------------------------------------------------------------------------- There is a new ISA extension for C2000 that utilizes the FPU to perform integral divisions more quickly than prior methods. In addition, these new instructions can perform alternative euclidean and modulo divisions. More information, along with the signatures for all intrinsics, can be found in the user guide. 2.6.1) Support ------------- The compiler supports the generation of these divisions in one of three ways: - Intrinsics, declared in stdlib.h, which take a numerator and denominator and return a structure containing both the remainder and quotient - Operators, which will automatically be optimized - Standard library functions ldiv and lldiv, both found in stdlib.h Only the intrinsics support the alternative division types. Operators and the standard library functions will perform division according to the C standard. 2.6.2) Usage ------------- The option --idiv_support controls support for these division sequences. A value of 'none' implies no hardware support for the new instructions, and a value of 'idiv0' implies support for the current specification for the new instructions. The option is only valid when FPU32 or FPU64 is available (--float_support is set to fpu32 or fpu64) and when using the C2000 EABI (--abi is eabi). The --opt_for_speed (-mf) option controls whether the sequences themselves are generated inline in the assembly, or are calls to pre-generated sequences in the runtime support library. This is to assist in lowering code size, as these sequences can be anywhere from 8 to 32 instructions long. At the default level (-mf2) or higher, the sequences will be inlined. At lower levels (-mf0 and -mf1), the sequences will be calls to the runtime support library. This affects all three forms of support: intrinsics, operators, and the standard library. 2.6.3) Examples ------------- The following 3 example functions are equivalent, and will perform a signed 32 by signed 32-bit division and return the quotient: #include long do_divide_op(long numerator, long denominator) { return numerator / denominator; } long do_divide_intrinsic(long numerator, long denominator) { return __traditional_div_i32byi32(numerator, denominator).quot; } long do_divide_lib(long numerator, long denominator) { return ldiv(numerator, denominator).quot; } ------------------------------------------------------------------------------- 2.7) 2011 version of the C language (C11) ------------------------------------------------------------------------------- The compiler supports the 2011 version of the C language. Compiling with the --c11 option causes the compiler to conform to the ISO/IEC 9899:2011 C standard. The compiler supports some features of C11 in the default relaxed ANSI mode. C11 _Atomic, stdatomic.h and threads.h are not supported.