TMS570LC4357: Request: Technical Docs for Texas Instruments Compiler v18.1.3.LTS

                       ARM C/C++ CODE GENERATION TOOLS
                           18.1.3.LTS Release Notes
                                  July 2018

================================================================================
Contents
================================================================================
1)  Support Information

2)  New Features

2.1) C++14 support
 
* Features Included from v17.9.0.STS:
2.2) C++ ABI Compatibility

2.3) Support for ARM C Language Extensions (ACLE)

* Features Included from v16.12.0.STS:
2.4) Improved stack usage with inline functions


-------------------------------------------------------------------------------
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 ARM Optimizing Compiler User's Guide" and the
"TI ARM 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 ARM CGT v18.1.0.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) C++ 2014 RTS support
--------------------------------------------------------------------------------

As of v18.1.0.LTS, the compiler uses the C++14 version of the C++ standard. 
Previously, C++03 was used. See the C++ Standard ISO/IEC 14882:2014. For a 
description of unsupported C++14 features, see Section 5.2 of the "TI ARM
Optimizing Compiler User's Guide".

The move to C++14 will break ABI compatibility with previous C++ RTS releases. 
Attempting to link old C++ object code with the new RTS will result in a 
link-time error. Suppressing this error will likely result in undefined symbols 
or undefined behavior during execution. 

C ABI compatibility will not be affected by this change.

In most cases, recompiling old source code with the new RTS should be safe.
However, due to the changes made in the language, some constructs will result
in syntax errors. Some common issues include:
- Macro expansion immediately adjacent to string literals may fail due to the
  inclusion of new string literals and literal suffixes.
  Ex: u8"def" will fail to compile if 'u8' is a macro
      "def"_x will fail to compile if '_x' is a macro
- New keywords: alignas, alignof, char16_t, char32_t, constexpr, decltype,
  noexcept, nullptr, static_assert, and thread_local
- The auto keyword has been repurposed and is no longer a valid storage class
  specifier. Similarly, the register keyword has been deprecated and will be
  removed in the future.

A full list can be found in Appendix C, section 2 of the C++14 standard.

-------------------------------------------------------------------------------
2.2) C++ ABI Compatibility
-------------------------------------------------------------------------------

v17.9.0.STS contains the first planned updates in preparation for the support
of C++14 (International Standard ISO/IEC 14882:2014(E)). As part of this
update, it is necessary to make changes which might cause errors when building
C++ projects containing C++ object files compiled with older versions of the
compiler.

These errors will usually include linktime errors involving undefined symbols.
If you see undefined symbol errors during a link, pass the "--no_demangle"
option to the compiler. If the undefined symbol's name starts with _Z or _ZVT,
then it's possible that there is a C++ object file or library built with an
older version of the tools being used. These will need to be compiled with the
v18.1.0.LTS tools to work properly.


-------------------------------------------------------------------------------
2.3) Support for ARM C Language Extensions (ACLE)
-------------------------------------------------------------------------------

Beginning with the ARM CGT v17.9.0.STS release, support for ARM C Language
Extensions (ACLE) as specified in the ACLE Release 2.0 document (Document
number: IHI 0053C, Date of Issue: 09/05/2014) has been added for the
applicable processor variants that are supported in the ARM CGT. This includes
support for new ACLE attributes, intrinsics, and pre-defined symbols as
detailed in the sub-sections below.


2.2.1) ACLE Attributes
----------------------

In addition to the attributes described in the ACLE specification that the
ARM CGT already supports (i.e. aligned, alias, common, nocommon, packed, 
section, visibility, and weak), the ARM CGT v17.9.0.STS release adds support
for the "target" attribute as follows:

  __attribute__((target("arm"))) void myfunc()
  
     when applied to a function, will force the generation of ARM state code. 
     This attribute will be interpreted as if the user had specified the
     already supported "#pragma CODE_STATE(myfunc, 32)" just in front of the
     definition of the function definition of "myfunc".

  __attribute__((target("thumb"))) void myfunc()
  
     when applied to a function, will force the generation of THUMB state code. 
     This attribute will be interpreted as if the user had specified the
     already supported "#pragma CODE_STATE(myfunc, 16)" just in front of the
     definition of the function definition of "myfunc".

The ARM CGT does not support the "pcs" ACLE attribute.


2.2.2) ACLE Intrinsics
----------------------

A new header file, arm_acle.h, has been added to the ARM CGT include
subdirectory which provides declarations and/or declarations of all of the
ACLE intrinsics that are now supported beginning with the v17.9.0.STS 
release.

The majority of ACLE intrinsics that are newly supported in this release
are implemented by already supported intrinsics that may have a slightly
different name. For example, the ACLE "__smulbb" intrinsic is implemented 
in terms of the already supported "_smulbb" intrinsic as follows:

  int32_t __BUILTIN _smulbb(int32_t x, int32_t y);
  #define __smulbb  _smulbb

The only difference being that the ACLE "__smulbb" intrinsic name has
a prefix of two underscores as opposed to the name of the already
supported "_smulbb" intrinsic name which has a prefix of 1 underscore.

The ARM CGT v17.9.0.STS release does not support all of the ACLE intrinsics
that are included in the ACLE specification. For example, the __cls, __clsl,
and __clsll ACLE intrinsics are not supported since the CLS instruction is
not available on the Cortex-M or Cortex-R architectures.

Please see the arm_acle.h file for more details about exactly which ACLE
intrinsics are supported and which are not. Where applicable, the declarations
of ACLE intrinsics that are not supported are enclosed in comments along with
a brief explanation of why the intrinsic is not supported and a reference to
the appropriate section in the ACLE specification where the intrinsic is
described.


2.2.3) ACLE Pre-Defined Symbols
-------------------------------

The ARM CGT v17.9.0.STS compiler will now define the following ACLE 
pre-defined symbols:

__ARM_ACLE		  - defined to '200' for all Cortex-M and Cortex-R
			    processor variants supported by the ARM CGT, not
			    defined otherwise

__ARM_ARCH		  - indicates which ARM architecture the compiler
			    is generating code for:
			  
			    value	selected processor
			    -----	------------------
			    '4'	-mv4
			    '5'	-mv5e
			    '6'	-mv6, -mv6m0
			    '7'	-mv7a8, -mv7m3, -mv7m4, -mv7r4, -mv7r5
			 
__ARM_32BIT_STATE	  - defined to 1 if compiler is generating code for
			    an ARM 32-bit processor variant, otherwise
			    undefined

__ARM_ARCH_ISA_ARM	  - defined to 1 if compiler is generating code for
			    a processor variant that supports the ARM 
			    instruction set; otherwise undefined (not
			    defined when compiling for Cortex-M processor,
			    for example)

__ARM_ARCH_ISA_THUMB	  - defined to 1 if compiler is generating code for
			    a processor variant that supports the THUMB-1
			    instruction set; defined to 2 if compiler is 
			    generating code for a processor variant that 
			    supports the THUMB-2 instruction set; otherwise
			    undefined

__ARM_BIG_ENDIAN	  - matches endian-ness specified with compiler
			    command-line: 1 (big-endian; default), 
			    0 (little-endian; -me option)

__ARM_FEATURE_CLZ	  - defined to 1 if compiler is generating code for
                            a processor variant that supports the CLZ 
			    instruction; otherwise undefined

__ARM_FEATURE_DSP	  - defined to 1 if compiler is generating code for
			    a Cortex-M or Cortex-R processor that supports
			    DSP instructions/intrinsics; otherwise undefined

__ARM_FEATURE_SAT	  - defined to 1 if compiler is generating code for
			    a processor variant tha supports SSAT/USAT 
			    instructions/intrinsics; otherwise undefined

__ARM_FEATURE_SIMD32 	  - defined to 1 if compiler is generating code for
			    a processor variant that supports all SIMD
			    instructions/intrinsics; otherwise undefined

__ARM_FEATURE_UNALIGNED   - defined to 1 if compiler is generating code for
			    a processor variant that supports unaligned access
			    to memory; otherwise undefined

__ARM_PCS		  - defined to 1 if the compiler can assumes that
			    the default procesude calling standard for a 
			    translation unit conforms to the "base procedure
			    call standard" as prescribed in the ARM 
			    Architecture Procedure Call Standard specification;
			    otherwise undefined

__ARM_SIZEOF_MINIMAL_ENUM - smallest possible enum type size (1 byte
			    for 'packed', 4 bytes for 'int' (mirroring the
			    --enum_type=[packed|int] option where packed is
			    the default)

__ARM_SIZEOF_WCHAR_T	  - size of wchar_t type: 16- (default) or 32-bits

__ARM_FP		  - defined to a non-zero value if the compiler can
			    assume that floating-point hardware support is
			    available when compiling a translation unit. The
			    value will be a combination of:

			    bit  value  precision
                            ---  -----  ---------
			     1    0x2    16-bit
			     2    0x4    32-bit
			     3    0x8    64-bit

			    For example, if --float_support=fpv4spd16 is
			    selected, then __ARM_FP will have a value of
			    0x6 since fpv4spd16 supports 32-bit and 16-bit
			    floating-point hardware.

			    If no floating-point hardware support is enabled,
			    then __ARM_FP will be undefined.

__ARM_FP16_ARGS		  - defined to 1 if a 16-bit float type can be used
			    for an argument and/or result; otherwise undefined

__ARM_FP16_FORMAT_IEEE	  - defined to 1 if the IEEE format for 16-bit
			    floating-point (according to IEEE 754-2008
			    standard) is used; otherwise undefined

__ARM_PCS_VFP		  - defined to 1 if the default procedure calling 
			    convention is to pass floating-point arguments /
			    return values in hardware floating-point 
			    registers

The ARM CGT v17.9.0.STS release does not support all of the ACLE pre-defined
symbols that are included in the ACLE specification. For example, the 
__ARM_FEATURE_CRYPTO pre-defined symbol is associated with support for 
CRYPTO instructions which are not supported on any of the processor variants
that the ARM CGT v17.9.0.STS release supports. If an ACLE pre-defined symbol
in the ACLE specification is not included in the above list, then it will
not be defined by the ARM CGT compiler.


-------------------------------------------------------------------------------
2.4) Improved stack usage with inline functions
-------------------------------------------------------------------------------

The new compiler improves stack usage by sharing aggregate data originally
defined in inline functions. Example:

struct ARGS { int f1,f2,f3,f4,f5; };

static inline void func1()
{
   struct ARGS a = {1, 2, 3, 4, 5};
   foo(&a);
}

static inline void func2()
{
   struct ARGS b = {1, 2, 3, 4, 5};
   foo(&b);
}

void func3()
{
   func1();
   func2();
}


In previous compilers, if func1 and func2 are inlined, the structs a
and b would not share the same stack location. This version of the
compiler will now share stack memory for local aggregates defined in
inline functions.