Compiler/C2000-CGT: C2000-CGT-NN difference

                       C2000 C/C++ CODE GENERATION TOOLS
                            18.12.1.LTS Release Notes
                                   January 2019

================================================================================
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
2.7) 2011 version of the C language (C11)
2.8) Option to disable FPU errata workaround


-------------------------------------------------------------------------------
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) Long Term Support release
-------------------------------------------------------------------------------

The C2000 CGT v18.12.1.LTS release is a long term support (LTS) release. This
release will be supported for roughly 2 years with periodic bug fix updates.

-------------------------------------------------------------------------------
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.12.0.LTS compiler includes an update for fpu64 mode for prolog/epilog
save-on-entry register save/restore to be more optimal and to save/restore
64-bits only when needed.  18.9.0.STS always saved/restored 64-bits for all
save-on-entry registers.

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 <src_file> 

Compile and link:
  > cl2000 --abi=eabi <src_file> -z -l<lnk.cmd>

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 <stdlib.h>
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.


-------------------------------------------------------------------------------
2.8) Option to disable FPU errata workaround
-------------------------------------------------------------------------------
The compiler has below new option to allow enabling or disabling an FPU
silicon errata that newer devices are no longer impacted by: 
  --silicon_errata_fpu1_workaround=on,off 

NOTE: this is disabled by default if any of below options are set:
     --float_support=fpu64 
     --tmu_support 
     --vcu_support=vcu2|vcrc

Silicon errata details:
  A CPU-to-FPU register write cannot coincide with the execution phase of 
  FRACF32, F32TOUI32, or UI16TOF32 instructions. When this option is on, the 
  compiler will add five NOPs or non-conflicting instructions before these 
  instructions can be used.