error: unresolved symbols remain

TMS470 C/C++ CODE GENERATION TOOLS
Release 4.1.4 April 2006

NOTE: The code generated by default with this release is not compatible with 
previous versions of the compiler.  The convention used to label functions
has changed to support the ARM9/ARM11 BLX instruction and linker generated
veneers.  See item 3 for details.  This includes a description on how to 
achieve backwards compatibility.

================================================================================
Table of Contents
================================================================================

1.   New Application Binary Interface
2.   New ARM Processor Support
3.   New Compiler Switches
4.   C++ Exception Support
5.   List of Available RTS Libraries
6.   New CPSR intrinsics
7.   Default DWARF2 Debug Support
8.   Integer Division With Constant Divisor
9.   The MUST_ITERATE Pragma
10.  The UNROLL Pragma
11.  New linker command file operator, palign
12.  64-Bit Integer Support
13.  Static Stack Depth Analysis
14.  Improved -mn Switch
15.  Branch Chaining
16.  New Utility strip470
17.  Updated Utility: nm470
18.  Expanded Assembler Option -D (and -ad)
19.  Pragmas to Control Diagnostic Messages
20.  Filtering the Usage Information ("the help screen")
21.  Predefined Symbols for Tool Version Numbers
22.  TMS470_C_DIR and TMS470_A_DIR Environment Variables (also C_DIR & A_DIR)
23.  -ppd and -ppi Options Allow Optional Filename
24.  REMINDER: Calling Assembler Directly is Deprecated

================================================================================
New Features In Separate Readme Files
================================================================================
1.   New Object File Display Utility - see file ofd470_readme.txt
2.   Sharing C Header Files With Assembly Source - see file c_headers_asm.txt
3.   Linker-generated Copy Tables - see file linker_copy_tables.txt


================================================================================
1. New Application Binary Interface
================================================================================

TMS470 compiler versions 4.1.0 and later contain 2 different ABI's (Application 
Binary Interfaces).  An ABI defines manner in which an entire object file is
compiled.  It covers items including language specifics, calling conventions, 
or the object file format.  For the TMS470 compiler, these changes are limited
to the function naming convention and linking dual-mode code.  The changes
were made to take advantage of the new capabilities that are present, beginning
with the V5E architectures.

With compiler version 4.1.0 and later, the default ABI changes how function
names are generated.  There is now a uniform naming convention for a functions
regardless whether a module is compiled in 16-bit mode or 32-bit mode.  All
function name are prefixed with the '_' (underscore).  This change is due
to the change where the linker (lnk470) now controls any necessary mode
changes.  The linker will determine the mode of both the caller and callee and
generate the necessary code to make the call.  For example, if the compiler
is targeted for the V5E architecture, the linker will replace a BL instruction
with a BLX instruction.  If the target is V4, or the linker cannot determine
the mode of the caller, the linker will generate the necessary veneer code.
The code generator will no longer generate a veneer function in the assembly
file.

This means object code generated with earlier versions of the compiler will not 
correctly link with this new ABI.  Backward compatibility is available as 
described below.

The abi option is passed to the compiler through the --abi command-line switch. 
The available options are:

1. ti_arm9_abi             This option also disables the "-md" switch 
                           (dual-state). For ti_arm9_abi, the same code is 
                           generated with and without "-md" switch and hence 
                           this switch has no effect.

2. tiabi                   This is the old-style ABI where functions are 
                           prefixed depending on whether the function is 
			   compiled in 32-bit or 16-bit mode. Also, the 
			   code-generator generates the veneers explicitly. 
			   This option is valid only for ARM7 (-mv4) and is 
			   provided strictly for backward compatibility. 

NOTE: Necessary Changes For Hand-Written Assembly Code
------------------------------------------------------

1. A new pre-defined symbol has been added to the assembler. The symbol 
__TI_ARM9ABI_ASSEMBLER will be set to 1 if compiling for ti_arm9_abi and 0 
otherwise. If the code will be used under both ABI's (ti_arm9_abi and tiabi)
the assembly must use this predefined symbol to conditionaly set the correct
function names.  An example is given below.

2. Under the ti_arm9_abi, all 32-bit and 16-bit routines must be explicitly 
identified using the ".armfunc" and ".thumbfunc" assembler directives. These 
directives are required for the linker to properly generate dual mode code. 
Assembly code without these directives may result in compiler errors and 
possibly incorrect execution. 

Example: 
If function foo() is to be defined in 16-bit mode, the following is the 
desired assembly sequence:
        
        .if __TI_ARM9ABI_ASSEMBLER 
        .thumbfunc _foo 
        .endif 

.if __TIARM9ABI_ASSEMBLER 
_foo: 
.else 
$foo: 
.endif 


Generating Linknames
--------------------

The compiler transforms the names of externally visible identifiers when
creating their linknames. The algorithm used depends on the scope within
which the identifier is declared. For objects, an underscore ( _ ) is prepended
to the identifier name. For C code, this will take place for both 32-bit mode 
and 16-bit mode functions with the new ti_arm9_abi.  In the backward compatible
tiabi ABI, 32-bit mode functions have an underscore ( _ ) prepended to their 
names and 16-bit mode functions have a dollar sign ($) prepended. 

C++ functions have the same initial character ( _ ) for ti_arm9_abi (or 
(_ or $) for tiabi) prepended, but also have the function name further mangled. 
Mangling is the process of embedding a function's signature (the number and 
types of its parameters) into its name. The mangling algorithm used closely 
follows that described in The C++ Annotated Reference Manual (ARM). Mangling 
allows function overloading, operator overloading, and type-safe linking.


================================================================================
2.  New ARM Processor Support
================================================================================

V5E (ARM9) Architecture Support
-------------------------------

The V5E support is included in compiler versions 4.1.0 and later.  The V5E 
instruction set consists of all V4 (ARM7) instructions in addition to DSP 
extensions for performing saturated arithmetic, as well as new branch-and-link 
instructions.  Some of the DSP extensions such as SMULBB, SMLABB are generated 
by the compiler automatically wherever possible. Other instructions can be 
generated using in the intrinsics described below. 

The command-line option "--silicon_version=5e" or "-mv5e" should be passed to 
the compiler to compile for V5E. The only ABI currently supported for V5E is
ti_arm9_abi.  Hence the function naming style and veneer generation conform to 
ti_arm9_abi specification.

Intrinsics: 

The following are the intrinsics available to access V5E DSP extensions. Each 
intrinsic is described along with the arguments it takes and its corresponding
instruction.  Please refer instruction set reference manual for a description 
of these instructions.

1. Normalize floating point 
int dst = _norm(int src) 

CLZ dst, src 

2. Saturated add 
int dst = _sadd(int src1, int src2) 

QADD dst, src1, src2 

3. Saturated subtract 
int dst = _ssub(int src1, int src2)     

QSUB dst, src1, src2 

4. Saturated double-add 
int dst = _sdadd(int src1, int src2)   

QDADD dst, src1, src2 

5. Saturated double-subtract 
int dst = _sdsub(int src1, int src2)   

QDSUB  dst, src1, src2 

6. Saturated multiply 
int dst = _smpy(int src1, int src2)    

SMULBB dst, src1, src2 
QADD     dst, dst, dst 

7. Saturated multiply-accumulate 
int dst = _smac(int src1, src2)          

SMULBB tmp, src1, src2 
QDADD      dst, dst, tmp 

8. Saturated multiply-subtract 
int dst = _smsub(int src1, src)          

SMULBB  tmp, src1, src2 
QDSUB   dst, dst, tmp 

9. Signed multiply 
   a. bottom half-words  
      int dst = _smulbb(int src1, int  src2)   

      SMULBB dst, src1, src2 

   b. top and bottom half-words  
      int dst = _smultb(int src1, int src2) 

      SMULTB dst, src1,    src2 

   c. bottom and top half-words 
      int dst = _smulbt(int src1, int src2) 

      SMULBT dst, src1, src2 

   d. Top half-words  
      int dst = _smultt(int src1, int src2)  

      SMULTT dst, src1, src2 

10. Signed multiply-accumulate 
   a. bottom half-words  
      int dst = _smlabb(int src1, int src2, int acc)   

      SMLABB dst, src1, src2, acc 

   b. top and bottom half- words  
      int dst = _smlatb(int src1, int src2, int acc) 

      SMLATB dst, src1, src2, acc 

   c. bottom and top half-words 
      int dst = _smlabt(int src1, int src2, int acc) 

      SMLABT dst, src1, src2, acc 

   d. Top half-words  
      int dst = _smlatt(int src1, int src2, int acc)  
      
      SMULTT dst, src1, src2 

11. Signed multiply-long and accumulate 
   a. bottom half-words  
      long long dst = _smlalbb(int src1, int src2)   

      SMLALBB dstlo, dsthi, src1, src2 

   b. top and bottom half-words  
      long long dst = _smlaltb(int src1, int src2) 

      SMLALTB dstlo, dsthi, src1, src2 

   c. bottom and top half-words   
      long long dst = _smlalbt(int src1, int src2) 

      SMLALBT dstlo, dsthi, src1, src2 

   d. Top half-words  
      long long dst = _smlaltt(int src1, int src2)  

      SMULTT dstlo, dsthi, src1, src2 

12. Signed multiply word and half-word 
   a. Word and bottom-half  
      int dst = _smulwb(int src1, short src2)  

      SMULWB dst, src1, src2 

   b. Word and top-half       
      int dst = _smulwt(int src1, short src2)   

      SMULWT dst, src1, src2 

13. Signed multiply-accumulate word and half-word 
   a. Word and bottom-half  
      int dst = _smlawb(int src1, short src2, int acc)  

      SMLAWB dst, src1, src2, acc 

   b. Word and top-half       
      int dst = _smlawt(int src1, short src2, int acc)   

      SMLAWT dst, src1, src2, acc 

14. Subtract with carry 
    int dst = _subc(int src1, int src2)  
    
    SUBC dst, src1, src2 


V6 (ARM11) Architecture Support
-------------------------------

The V6 support is included in compiler versions 4.1.0 and later.  The support 
for V6 includes

- All new SIMD/media instructions through intrinsics.
- All new thumb instructions (automatically generated).
- Removal of restrictions for instructions such as MUL required for older 
architectures (ARM V4).

There is no support for the following features
- Unaligned reads and writes
- Mixed-endian mode and instructions

The compiler will automatically generate all the new thumb instructions 
wherever required.  It will also generate the new V6 32-bit mode sign-extension 
instructions wherever possible.

The command-line option "--silicon_version=6" or "-mv6" should be passed to 
the compiler to compile for V6. The only ABI currently supported for V6 is
ti_arm9_abi.  Hence the function naming style and veneer generation conform to 
ti_arm9_abi specification.

1. SIMD/Media extension instrinsics. 

The ARM11 processor supports provides a large set of media instructions.  The
intrinsics are classified as groups and described below.

a. Parallel add/subtract instructions. 

These instructions perform parallel halfword-wise and byte-wise addition and 
subtraction of general purpose registers.  These instructions are

ADD16, ADDSUBX, SUBADDX, SUB16, ADD8, SUB8. 

The different types of arithmetic (such as signed, unsigned, saturated etc) is 
specified using a prefix. The allowed prefixes are 

S, Q, SH, U, UQ, UH. 

Any of these prefixes can be combined with any of the above add/subtract 
operations. 

The intrinsics are 

int dst = _{s,sh,q,u,uq,uh}{add16,addsubx,subaddx,sub16,add8,sub8}
                                                           (int src1, int src2) 

 {S,SH,Q,U,UQ,UH}{ADD16, ADDSUBX, SUBADDX, SUB16, ADD8, SUB8} dst, src1, src2 

where the braces indicate a choice of any one of the comma-separated list. 

b. Halfword packing instructions 

int dst = _pkhbt(int src1, int src2, imm5 shift) 

PKHBT dst, src1, src2, LSL #shift 

int dst = _pkhtb(int src1, int src2, imm5 shift) 

PKHBT dst, src1, src2, LSL #shift 

c. Parallel half-word saturating instructions 

int dst = _ssat16(int src, imm5 satimm) 

SSAT16 dst, src, #satimm 

int dst = _usat16(int src, imm5 satimm) 

USAT16 dst, src, #satimm 

d. Selection instructions 

int dst = _sel16(int src1, int src2) 

SEL16 dst, src1, src2 

int dst = _sel8(int src1, int src2)   

SEL8 dst, src1, src2 

e. Sign/Zero-extend instructions 

int dst = _sunpk8to16(int src,imm5 rotamt)  

SUNPK8TO16 dst, src, ROR #rotamt 

int dst = _sunpk8to32(int src,imm5 rotamt)  

SUNPK8TO32 dst, src, ROR #rotamt 

int dst = _sunpk16to32(int src,imm5 rotamt)  

SUNPK16TO32 dst, src, ROR #rotamt 

int dst = _uunpk8to16(int src,imm5 rotamt)  

UUNPK8TO16 dst, src, ROR #rotamt 

int dst = _uunpk8to32(int src,imm5 rotamt)  

UUNPK8TO32 dst, src, ROR #rotamt 

int dst = _uunpk16to32(int src,imm5 rotamt)  

UUNPK16TO32 dst, src, ROR #rotamt 

f. Sign/Zero-extend and add instructions 

int dst = _sadd8to16(int src1, int src2, imm5 rotamt)  

SUNPK8TO16 dst, src1, src2, ROR #rotamt 

int dst = _sadd8to32(int src1, int src2, imm5 rotamt)  

SUNPK8TO32 dst, src1, src2, ROR #rotamt 

int dst = _sadd16to32(int src1, int src2, imm5 rotamt)  

SUNPK16TO32 dst, src1, src2, ROR #rotamt 

int dst = _uadd8to16(int src1, int src2, imm5 rotamt)  

UUNPK8TO16 dst, src1, src2, ROR #rotamt 

int dst = _uadd8to32(int src1, int src2, imm5 rotamt)  

UUNPK8TO32 dst, src1, src2, ROR #rotamt 

int dst = _uadd16to32(int src1, int src2, imm5 rotamt)  

UUNPK16TO32 dst, src1, src2, ROR #rotamt 

g. Signed multiply instructions 

operand acc is the value with which the product is accumulated 

int dst = _smlad(int src1, int src2, int acc)  

SMLAD dst, src1, src2, acc 

int dst = _smladx(int src1, int src2, int acc)  

SMLADX dst, src1, src2, acc 

int dst = _smlsd(int src1, int src2, int acc)  

SMLSD dst, src1, src2, acc 

int dst = _smlsdx(int src1, int src2, int acc)  

SMLSDX dst, src1, src2, acc 

int dst = _smmla(int src1, int src2, int acc)  

SMMLA dst, src1, src2, acc 

int dst = _smmlar(int src1, int src2, int acc)  

SMMLAR dst, src1, src2, acc 

int dst = _smmls(int src1, int src2, int acc)  

SMMLS dst, src1, src2, acc 

int dst = _smmlsr(int src1, int src2, int acc)  

SMMLSR dst, src1, src2, acc 

int dst = _smuad(int src1, int src2)  

SMUAD dst, src1, src2 

int dst = _smuadx(int src1, int src2)  

SMUADX dst, src1, src2 

int dst = _smusd(int src1, int src2)  

SMUSD dst, src1, src2 

int dst = _smusdx(int src1, int src2)  

SMUSDX dst, src1, src2 

int dst = _smmul(int src1, int src2)  

SMMUL dst, src1, src2 

int dst = _smmulr(int src1, int src2)  

SMMULR dst, src1, src2 

long long dst = _smlald(int src1, src2)  

SMLALD dstlo, dsthi, src1, src2 

long long dst = _smlaldx(int src1, src2)  

SMLALDX dstlo, dsthi, src1, src2 

long long dst = _smlsld(int src1, src2)  

SMLSLD dstlo, dsthi, src1, src2 

long long dst = _smlsldx(int src1, src2)  

SMLSLDX dstlo, dsthi, src1, src2 

h. Unsigned multiply-accumulate-accumulate long 

long long dst = _umaal(int src1, int src2)  

UMAAL dstlo, dsthi, src1, src2 

j. Unsigned sum-of-absolute differences 

int dst = _usad8(int src1, int src2)  

USAD8 dst, src1, src2 

int dst = _usada8(int src1, int src2, int acc)  

USADA8 dst, src1, src2, acc 


================================================================================
3. New Compiler Switches
================================================================================


-ab=<num>      	 Specify length of maximum branch chain 
	         for branch chaining optimization.


-abi=ti_arm9_abi,tiabi

	          This applies to any compiler version 4.1.0
		  and later.  In these compilers the application
		  binary interface has changed to support
		  a different function naming scheme and linker
		  generated veneers.  The default is the
		  ti_arm9_abi.  For backward compatibility,
		  for example to add the '$' prefix for thumb
		  functions, and '_' prefix far arm functions,
		  use tiabi.  See below for details.


--align_structs=<n>   

                  Structure alignment can be forced to a minimum
	          "n" byte boundary where "n" is a power of 2 
		  with this switch.  To align all structs to a 
		  word boundary use:

	          cl470 --align_structs=4

	          All structs in the file will contain that 
		  minimum alignment, including nested structs.
		  This will only set a minimum alignment, this
		  does not "pack" data structures.  This can 
		  also break a program if one file is compiled 
		  with this switch and another is not, or a 
		  different alignment is used.  The offsets of a 
		  nested switch could be incorrect in such a case.


-args=size        Set C argc/argv memory size.  See section 7.4.3 in
                  the Assembly Language Tools User's Guide.


--code_state=16,32    

                  Set the TMS470 compilation mode.  If set
	          to 32, the compiler will generate 32-bit
		  code.  This is the default setting.  If
		  set to 16, the compiler will generate 16-bit
		  code.  The switch --code_state=16 and the
		  -mt switch are equivalent.


--default_order   The default linker algorithm to allocate sections not 
                  listed in a linker command file changed with version 2.52.  
		  The new algorithm is a sized-based algorithm.  This 
		  meant applications relying on the old behavior encountered 
                  linker errors.  The old behavior found in version 2.51 
		  and earlier is available with a new linker switch, 
		  --default_order. For example:

                  cl470 file.c -z --default_order lnk.cmd ...

                  or 

                  lnk470 --default_order file.obj lnk.cmd ...


--disable_branch_chaining  	

                  Disable branch chaining optimization


--endian=big,litte     

                  Set the endianness of the compiled code.
	          The default is big-endian.  The switch
		  --endian=litte and the -me switch are
		  equivalent.


--exceptions      Enable C++ exception handling


-mv=4,5e,6        This applies to any compiler version 4.1.0 and
	          later.  Set the target ARM architecture for 
		  the compiler.  Use 4 for ARM version 4 
		  architectures.  Use 5e for ARM version 5E
		  architectures.  Use 6 for ARM version 6
		  architectures.  Without this switch, the
		  target architecture is version 4.  See below 
		  for details on targeting the compiler for 
		  versions 5E and 6.


--plain_char=signed,unsigned

	          Specify how plain char data types will
		  be compiled.  The char data type is
		  treated as unsigned by default.


--static_template_instantiation

                  This arm release contains an updated shell tool, 
		  cl470.exe, with the following new switch:

                  --static_template_instantiation

                  For example: 
		  
		  cl470 --static_template_instantiation aa.cpp

                  With this switch all template entities are instantiated 
		  as needed in that file by the parser.  These 
		  instantiations are also given internal linkage.


--verbose         Display the banner while compiling.  This includes the 
                  compiler version number and copyright.  For example:

		  cl470 --vebose file.c

		  TMS470 C/C++ Compiler             Version 3.00
		  Tools Copyright (c) 1996-2003 Texas Instruments Incorporated
			     "file.c"   ==> main

			   
-version          Print the version number for each tool in the compiler.  
                  No compiling will take place.  For example:

		  cl470 --version

		  TMS470 C/C++ Compiler             Version 3.00
		  Build Number 1DK2N-8A0FEEH-UASQC-VAV-DZAZE_T_QQ_1S
		  TMS470 C/C++ Parser               Version 3.00
		  Build Number 1DK2N-8A0FEEH-UASQC-VAV-DZAZE_T_QQ_1S
		  TMS470 C/C++ Optimizer            Version 3.00
		  Build Number 1DK2N-8A0FEEH-UASQC-VAV-DZAZE_T_QQ_1S
		  TMS470 C/C++ Codegen              Version 3.00
		  Build Number 1DK2N-8A0FEEH-UASQC-VAV-DZAZE_T_QQ_1S
		  TMS470 COFF Assembler             Version 3.00
		  Build Number 1DK2N-8A0FEEH-UASQC-VAV-DZAZE_T_QQ_1S
		  TMS470 COFF Linker                Version 3.00
		  Build Number 1DK2N-8A0FEEH-UASQC-VAV-DZAZE_T_QQ_1S


--xml_link_info=file    

                  Produce detailed link information data-base in 
                  <file>.  See section 7.4.21 in the Assembly
	          Language Tools User's Guide.


================================================================================
4. C++ Exception Support
================================================================================

The --exceptions switch will enables C++ exception handling. The compiler 
will generate code to handle try/catch/throw statements in C++ code.  It
is necessary to use a run-time library that contains the necessary functions 
that control exception handling.  This code is not included in the standard 
TMS470 libraries.  To link code compiled with exceptions use one of the 
following libraries:

  16-bit mode, big endian
  -----------------------
  rts16_eh.lib      
  rts16arm9_eh.lib  
  rts16tiabi_eh.lib   

  16-bit mode, little endian
  -----------------------
  rts16e_eh.lib     
  rts16earm9_eh.lib   
  rts16etiabi_eh.lib  

  32-bit mode, big endian
  -----------------------
  rts32_eh.lib      
  rts32earm9_eh.lib
  rts32arm9_eh.lib  

  32-bit mode, little endian
  -----------------------
  rts32etiabi_eh.lib
  rts32e_eh.lib     
  rts32tiabi_eh.lib

For details on the TMS470 run-time libraries, see next section.


================================================================================
5. List of Available RTS Libraries
================================================================================

Separate libraries are provided for each mode, big and little endian, 
each abi, v4 and v5e architectures, and with C++ exception support.  


16-bit Mode Libraries
---------------------

Library Name           Arch           ABI          Endianness       C++ 
                       Version                                    Exceptions
-------------------------------------------------------------------------------
rts16.lib          |    V4    |    ti_arm9_abi    | big          |   No
-------------------------------------------------------------------------------
rts16e.lib         |    V4    |    ti_arm9_abi    | little       |   No
-------------------------------------------------------------------------------
rts16arm9.lib      |    V5E   |    ti_arm9_abi    | big          |   No
-------------------------------------------------------------------------------
rts16earm9.lib     |    V5E   |    ti_arm9_abi    | little       |   No
-------------------------------------------------------------------------------
rts16_eh.lib       |    V4    |    ti_arm9_abi    | big          |   Yes
-------------------------------------------------------------------------------
rts16e_eh.lib      |    V4    |    ti_arm9_abi    | little       |   Yes
-------------------------------------------------------------------------------
rts16arm9_eh.lib   |    V5E   |    ti_arm9_abi    | big          |   Yes
-------------------------------------------------------------------------------
rts16earm9_eh.lib  |    V5E   |    ti_arm9_abi    | little       |   Yes
-------------------------------------------------------------------------------
rts16tiabi.lib     |    V4    |    tiabi          | big          |   No
-------------------------------------------------------------------------------
rts16etiabi.lib    |    V4    |    tiabi          | little       |   No
-------------------------------------------------------------------------------
rts16tiabi_eh.lib  |    V4    |    tiabi          | big          |   Yes
-------------------------------------------------------------------------------
rts16etiabi_eh.lib |    V4    |    tiabi          | little       |   Yes


32-bit Mode Libraries
---------------------

Library Name           Arch           ABI          Endianness       C++ 
                       Version                                    Exceptions
-------------------------------------------------------------------------------
rts32.lib          |    V4    |    ti_arm9_abi    | big          |   No
-------------------------------------------------------------------------------
rts32e.lib         |    V4    |    ti_arm9_abi    | little       |   No
-------------------------------------------------------------------------------
rts32arm9.lib      |    V5E   |    ti_arm9_abi    | big          |   No
-------------------------------------------------------------------------------
rts32earm9.lib     |    V5E   |    ti_arm9_abi    | little       |   No
-------------------------------------------------------------------------------
rts32_eh.lib       |    V4    |    ti_arm9_abi    | big          |   Yes
-------------------------------------------------------------------------------
rts32e_eh.lib      |    V4    |    ti_arm9_abi    | little       |   Yes
-------------------------------------------------------------------------------
rts32arm9_eh.lib   |    V5E   |    ti_arm9_abi    | big          |   Yes
-------------------------------------------------------------------------------
rts32earm9_eh.lib  |    V5E   |    ti_arm9_abi    | little       |   Yes
-------------------------------------------------------------------------------
rts32tiabi.lib     |    V4    |    tiabi          | big          |   No
-------------------------------------------------------------------------------
rts32etiabi.lib    |    V4    |    tiabi          | little       |   No
-------------------------------------------------------------------------------
rts32tiabi_eh.lib  |    V4    |    tiabi          | big          |   Yes
-------------------------------------------------------------------------------
rts32etiabi_eh.lib |    V4    |    tiabi          | little       |   Yes


================================================================================
6. New CPSR intrinsics
================================================================================

The following intrinsics have been added to get/set the CPSR register 
and to enable/disable interrupts:

Intrinsic prototypes:

a) To set the CPSR register:

   void _set_CPSR(uint src)
   void _restore_interrupts(uint src) --> MSR CPSR,src

b) To set the CPSR flag bits (the src is rotated by the intrinsic):

   void _set_CPSR_flg(uint src) --> MSR CPSR_FLG,src

c) To get the CPSR register:

   dst = uint _get_CPSR() --> MRS dst,CPSR

d) To call a software interrupt (src must be an immediate):

   void _call_swi(uint src) --> SWI $src

e) To enable/disable IRQ interrupts and return previous CPSR value:

   dst = uint _enable_IRQ() --> MRS dst,CPSR
                                BIC tmp,dst,#0x80
			        MSR CPSR,tmp

   dst = uint _disable_IRQ() --> MRS dst,CPSR
                                 ORR tmp,dst,#0x80
			         MSR CPSR,tmp

f) To enable/disable FIQ interrupts and return previous CPSR value:

   dst = uint _enable_FIQ() --> MRS dst,CPSR
                                BIC tmp,dst,#0x40
			        MSR CPSR,tmp

   dst = uint _disable_FIQ() --> MRS dst,CPSR
                                 ORR tmp,dst,#0x40
			         MSR CPSR,tmp

g) To enable/disable all interrupts and return previous CPSR value:

   dst = uint _enable_interrupts() --> MRS dst,CPSR
                                       BIC tmp,dst,#0xc0
			               MSR CPSR,tmp

   dst = uint _disable_interrupts() --> MRS dst,CPSR
                                        ORR tmp,dst,#0xc0
			                MSR CPSR,tmp


================================================================================
7. Default DWARF2 Debug Support
================================================================================

The TMS470 C/C++ Code Generation Tools support the generation of DWARF
symbolic debug information in the output object code.  The DWARF debug output
contains detailed type information about objects and functions used in an
application.  This is the default debug information generated with the -g
shell switch.  The compiler will normally generate some amount of DWARF debug
information, even without the -g switch.  This may include information on
functions, files, and global variables.  This information does not hinder
any optimizations.

It is possible to disable the generation of all symbolic debugging with the
use of the -gn shell switch.

Previous releases of the compiler generated STABS debug information by
default.  The compiler can still generate STABS if necessary.  This
is available with the -gt shell switch.

Debug type merging and type checking are performed by default in the linker.
Any type inconsistencies in the uses of symbols from different object files
are now reported.  This feature can be turned off by passing the -b switch to
the linker.


================================================================================
8. Integer Division With Constant Divisor
================================================================================

The optimizer will attempt to rewrite integer divide operations with constant
divisors.  The integer divides are rewritten as a multiply with the reciprocal
of the divisor.  This occurs at level -o2 and higher.  It is also necessary to 
use the compile-for-speed shell switch: -mf.


================================================================================
9. The MUST_ITERATE Pragma
================================================================================

Two pragmas have been added in this release that aid the user in unrolling
loops.  It is necessary to use optimization level -o1 or higher for these
pragmas.

The MUST_ITERATE pragma specifies to the compiler certain properties of
a loop. Through the use of the MUST_ITERATE pragma, you can guarantee
that a loop executes a certain number of times. The pragma can help the
compiler eliminate unnecessary code.

Any time the UNROLL pragma is applied to a loop, MUST_ITERATE should
be applied to the same loop. In this case, the MUST_ITERATE pragma's third
argument, multiple, should always be specified.

No statements are allowed between the MUST_ITERATE pragma and the for,
while, or do-while loop to which it applies. However, other pragmas, such as
UNROLL, can appear between the MUST_ITERATE pragma and the loop.

The syntax of the pragma for C and C++ is:

#pragma MUST_ITERATE ( min, max, multiple) [;]

The arguments min and max are programmer-guaranteed minimum and maximum
trip counts. The trip count is the number of times a loop iterates. The trip
count of the loop must be evenly divisible by multiple. All arguments are
optional. For example, if the trip count could be 5 or greater, you can specify
the argument list as follows:

#pragma MUST_ITERATE(5);

However, if the trip count could be any nonzero multiple of 5, the pragma would
look like this:

#pragma MUST_ITERATE(5, , 5); /* A blank field for max*/

It is sometimes necessary for you to provide min and multiple in order for the
compiler to perform unrolling. This is especially the case when the compiler
cannot easily determine how many iterations the loop will perform (i.e., the
loop has a complex exit condition).

When specifying a multiple via the MUST_ITERATE pragma, results of the
program are undefined if the trip count is not evenly divisible by multiple. 
Also, results of the program are undefined if the trip count is less than the 
minimum or greater than the maximum specified.

If no min is specified, zero is used. If no max is specified, the largest 
possible number is used. If multiple MUST_ITERATE pragmas are specified for the
same loop, the smallest max and largest min are used.

================================================================================
Using MUST_ITERATE to Expand Compiler Knowledge of Loops
================================================================================

Through the use of the MUST_ITERATE pragma, you can guarantee that a
loop executes a certain number of times. The example below tells the compiler
that the loop is guaranteed to run exactly 10 times:

#pragma MUST_ITERATE(10,10);
for(i = 0; i < trip_count; i++) { ...

If the MUST_ITERATE pragma is not specified for a loop such as this, the 
compiler generates code to bypass the loop, to account for the possibility of 0 
iterations. With the pragma specification, the compiler knows that the loop 
iterates at least once and can eliminate the loop-bypassing code.

MUST_ITERATE can specify a range for the trip count as well as a factor of
the trip count. For example:

#pragma MUST_ITERATE(8,48,8);
for(i = 0; i < trip_count; i++) { ...

This example tells the compiler that the loop executes between 8 and 48 times
and that the trip_count variable is a multiple of 8 (8, 16, 24, 32, 40, 48). The
multiple argument allows the compiler to unroll the loop.

You should also consider using MUST_ITERATE for loops with complicated
bounds. In the following example:

for(i2 = ipos[2]; i2 < 40; i2 += 5) { ...

the compiler would have to generate a divide function call to determine, at 
run-time, the exact number of iterations performed. The compiler will not do 
this.  In this case, using MUST_ITERATE to specify that the loop always 
executes 8 times allows the compiler to generate a hardware loop:

#pragma MUST_ITERATE(8,8);
for(i2 = ipos[2]; i2 < 40; i2 += 5) { ...


================================================================================
10. The UNROLL Pragma
================================================================================

The UNROLL pragma specifies to the compiler how many times a loop should
be unrolled. The optimizer must be invoked (use -o1, -o2, or -o3) in order for
pragma-specified loop unrolling to take place. The compiler has the option of
ignoring this pragma.

No statements are allowed between the UNROLL pragma and the for, while,
or do-while loop to which it applies. However, other pragmas, such as
MUST_ITERATE, can appear between the UNROLL pragma and the loop.
The syntax of the pragma for C and C++ is:

#pragma UNROLL ( n) [;]

If possible, the compiler unrolls the loop so there are n copies of the original
loop. The compiler only unrolls if it can determine that unrolling by a factor 
of n is safe. In order to increase the chances the loop is unrolled, the 
compiler needs to know certain properties:

   * The loop iterates a multiple of n times. This information can be specified      
     to the compiler via the multiple argument in the MUST_ITERATE pragma.
   * The smallest possible number of iterations of the loop.
   * The largest possible number of iterations of the loop.

The compiler can sometimes obtain this information itself by analyzing the
code. However, the compiler can be overly conservative in its assumptions
and may generate more code than is necessary when unrolling. This can also
lead to not unrolling at all.

Furthermore, if the mechanism that determines when the loop should exit is
complex, the compiler may not be able to determine these properties of the
loop. In these cases, you must tell the compiler the properties of the loop by
using the MUST_ITERATE pragma.

The following pragma specification:

#pragma UNROLL(1);

asks that the loop not be unrolled. Automatic loop unrolling also is not
performed in this case.

If multiple UNROLL pragmas are specified for the same loop, it is undefined
which UNROLL pragma is used, if any.


================================================================================
11. New linker command file operator, palign 
================================================================================

The linker will now support the use of a "palign" operator in the 
linker command file. Details are found in the CGTLinker.txt document.


================================================================================
12. 64-bit Integer Support
================================================================================

The TMS470 Compiler now supports the following new data types. The range values
are available as standard macros in the header file limits.h.

-------------------------------------------------------------------------------
Type                Size     Representation    Minimum             Maximum 
                                               Value               Value
-------------------------------------------------------------------------------
long long        
signed long long    64bits   2's        -9223372036854775808 9223372036854775807
                             complement  

unsigned long long  64bits   Binary             0           18446744073709551615
-------------------------------------------------------------------------------

The long long data types are stored in register pairs. In memory they are 
stored as 64-bit objects at word (32-bit) aligned addresses. The ordering of 
the bytes in the 64-bit object depends on the endianness of the target. For 
example in big endian target the value 0x0011223344556677 will be stored as
follows:

	Address x 	00112233
	Address x+4	44556677

long long integer constant can have an "ll" or "LL" suffix. Without the suffix
the value of the constant will determine the type of the constant. 

The formatting rules for long long in C I/O require "ll" in the format string.
For example:

printf("%lld", 0x0011223344556677);
printf("%llx", 0x0011223344556677);

The following new library functions are added:
llabs(), strtoll() and strtoull().


================================================================================
13. Static Stack Depth Analysis
================================================================================

The static stack depth profiler will provide information to the user about the 
maximum stack depth requirements of their application based on the static 
information available to it in the output file generated by the linker.

The profiler is implemented as a stand-alone application called sdp470.  The 
profiler will take a linked output file as input and produce a listing that 
details the stack usage of all of the functions defined in the application.  If 
an application contains indirect calls and/or reentrant procedures, then a 
configuration file should also be provided as input to the profiler.

The syntax for invoking the static stack depth profiler is as follows:

		sdp470 [-c config] out-file

-c config	Identifies a configuration file to be used by the profiler to 
supply information about indirectly called functions and reentrant procedures.

out-file	Identifies linked output file for an application to be analyzed 
by the profiler.  This file will contain debug information about all functions 
included in the final link of an application.

Details of the static stack depth profiler are provided in a separate document,
sdprof.htm (unix platforms) or sdprof.doc (PC platforms).


================================================================================
14. Improved -mn Switch
================================================================================

The existing -mn shell switch is documented as reenabling optimizations 
disabled by the -g option. In previous releases there existed some 
optimizations that were still disabled under -mn. This is no longer the case; 
equivalent code should now be produced with "-g -mn" as compared to when those 
switches are omitted. Note that if only the -g switch is used, a variety of 
optimizations may be disabled to ensure the maximum debugging support possible.


================================================================================
15. Branch Chaining
================================================================================

Support for branch chaining, in 16-BIS mode only, has been added.

a. What is Branch Chaining?

Consider the following code sequence

LAB1:	BR  L10
	....

LAB2:	BR L10
	....
	....
L10:

If L10 is far away from LAB1 (large offset), the assembler would convert BR into
a sequence of branch around and unconditional branch, resulting in a sequence of
2 instructions that are either 4 or 6 bytes long. Instead, if the branch at LAB1
can jump to LAB2, and LAB2 is close enough so that BR can be replaced by a
single, short branch instruction, the resulting code is smaller as the BR in
LAB1 would be converted into one instruction that is 2 bytes long. This method
of branching to branches that jump to the desired target is known as "branch
chaining". Note that LAB2 can in turn jump to another branch if L10 is too far
away from LAB2. Thus, branch chaining can be extended to arbitrary depths.

b. How does it work?

The codegen generates the following (new pseduo) instructions

1. BTcc instead of BRcc
Format: BTcc target,#depth

The #depth is an optional argument and if not specified, is set to the default
branch chaining depth. If specified, the chaining depth for this branch
instruction is set to #depth. The assembler issues a warning if #depth is less
than zero and sets the branch chaining depth for this instruction to zero.

2. BQcc instead of Bcc
Format: BQcc target,#depth

The #depth argument is similar to the one in BT instruction.

The BT pseudo instruction replaces BR (pseduo branch) instruction. Similarly, BQ
replaces B. The assembler performs branch chain optimizations for these
instructions, if branch chaining is enabled. The assembler replaces the BT and
BQ jump targets with the offset to the branch to which these instructions jump.

The default branch chaining is 10 (to prevent longer branch chains from impeding
performance).

c. How to control branch chaining?

The shell supports the  command-line argument "-ab num" that controls the depth
of branch chaining. num is the depth of branch chaining. A value of zero
indicates that no branch chaining should be performed (branch chaining
disabled). A negative value for num results in an assembler warning and the
branch chaining depth is taken as zero.

Alternatively, the argument "--max_branch_chain num" can be  passed to the
assembler directly.

Note that the pseudo instructions for branch chaining are generated only if
compiling in thumb mode and compiling for code size. In all other cases, these
instructions (BT and BQ) are not generated.

Assembly language programmers can use the BT and BQ instructions to enable the
assembler to perform branch chaining. The programmer can control the branch
chaining depth for each instruction using the second (optional) argument.
Assembly programmers must use the BR and B instructions if they wish to prevent
branch chaining for those branches

Branch chaining can be turned off by using the --disable_branch_chaining switch.

================================================================================
16. New Utility strip470
================================================================================

The strip utility, strip470, is used to remove symbol table and debugging
information from object files.

The following command invokes the strip utility:

    strip470 [-options] <input filename> [ <input filename> ... ]

    <input filename> is a COFF object file (.obj) or an executable file (.out).

The options are as follows:

       -p   Remove all information not required for execution. This option
            causes more information to be removed than the default behavior,
	    but the object file is left in a state that cannot be linked. This
	    option should only be used with executable (.out) files.

When strip470 is invoked, it will replace the input files with their stripped
versions.

================================================================================
17. Updated Utility: nm470
================================================================================
The name utility, nm470, is used to print the list of names defined and
referenced in a COFF object file (.obj), an executable file (.out), or an
archive library (.lib). The value associated with the symbol and an indication
of the kind of symbol is also printed.

The following command invokes the name utility:

   nm470 [-options] <input filename> [ <input filename> ... ]

<input filename> is a COFF object file (.obj), an executable file (.out), or an
archive library (.lib).

The name utility options are as follows:

      -a        List all symbols
      -c        Include C NULL symbols in listing
      -l        Lists symbol information from an object or archive library 
                using a longer, more detailed format
      -d        Include debug symbols in listing
      -f        Prepend file name to each symbol
      -g        List global symbols only
      -h        Display a help message that includes usage and option 
                information
      -n        Sort symbols by value rather than alphabetically
      -o <file> Prints the listing to <~Ale> rather than to stdout
      -p        Do not sort symbols
      -q        Quiet
      -r        Sort symbols in reverse order
      -t        Include tag info symbols in listing
      -u        List undefined symbols only

================================================================================
18. Expanded Assembler Option -D (and -ad)
================================================================================
Previously the -D option (and -ad option) could be used to equate a symbol to a
constant numeric value acting as the equivalent of a .set directive.  This
option has been extended to allow a symbol to be equated to a string, the option
acting as the equivalent of an .asg directive.  The syntax of this option
remains the same, -Dname=[value], except that when 'value' is a non-numeric
string, the new form is invoked.  Note that when 'value' is empty, 1 is used as
the default operand.


================================================================================
19. Pragmas to Control Diagnostic Messages
================================================================================
The following pragmas may be used to control diagnostic messages in the same
ways as the corresponding command line options:

  pragma                     option      meaning

  #pragma diag_suppress id   -pds=id     Suppress diagnostic <id>
  #pragma diag_remark   id   -pdsr=id    Treat diagnostic <id> as a remark
  #pragma diag_warning  id   -pdsw=id    Treat diagnostic <id> as a warning
  #pragma diag_error    id   -pdse=id    Treat diagnostic <id> as an error

  #pragma diag_default  id   N/A         Use default severity of the diagnostic

The pragma syntax is the following:
  #pragma diag_xxx [=] error_number_or_tag, error_number_or_tag ... 

The diagnostic affected is specified using either an error number or an error
tag name. The "=" is optional. Any diagnostic may be overridden to be an error,
but only diagnostics with a severity of discretionary error or below may have
their severity reduced to a warning or below, or be suppressed. The
diag_default pragma is used to return the severity of a diagnostic to the one
that was in effect before any pragmas were issued (i.e., the normal severity of
the message as modified by any command-line options).

The diagnostic identifier number is output along with the message when the
-pden command line option is specified.


================================================================================
20. Filtering the Usage Information ("the help screen")
================================================================================
The cl470 help option, -h or --help, normally displays the syntax for invoking
cl470 and the list of available options.  When this option is followed by 
another option or phrase it will display detailed information about the option 
or will display options related to the phrase.  For example to see information 
about options associated with debugging use 'cl55 -h debug'.

================================================================================
21. Predefined Symbols for Tool Version Numbers
================================================================================
The format of the tool versions numbers has changed to include three levels of
qualification.  The compiler and assembler each predefine a symbol that
represents the version number of the tools.  These symbols are integer values
with three digits for each level of qualification.  Version x.y.z is mapped to
the integer 1000000*x + 1000*y + z.  Thus version 4.1.2 is represented by the
integer 004001002.  The compiler predefined symbol is __TI_COMPILER_VERSION__.
This symbol existed in previous versions but was encoded differently.  The new
encoding still has the property that this version has a larger value than the
value for any preceding version.  New in this release, the assembler predefines
the symbol __TI_ASSEMBLER_VERSION__.


================================================================================
22. TMS470_C_DIR and TMS470_A_DIR Environment Variables (also C_DIR & A_DIR)
================================================================================
As described in existing documentation these environment variables may be used
to supply a list of pathnames for directories to be searched by the compiler,
assembler or linker for such things as include files, macro libraries, and
object libraries.  The specification of the exact format of the values to be
assigned to these variables has been tightened up to avoid various ambiguities
that occur when spaces are allowed in pathnames.

Semicolons are now the ONLY legal separators.  Spaces before and after
semicolons, at the beginnings and ends of pathnames are ignored.  Other spaces
are considered to be part of the pathnames.  This holds for all platforms.  This
matches the convention which was previously supported on Windows PC hosts.

As far as search order goes, the assembly parser and assembler check A_DIR
directories and then C_DIR directories.  The linker checks C_DIR and then A_DIR.
The C/C++ compiler checks C_DIR only.


================================================================================
23. -ppd and -ppi Options Allow Optional Filename
================================================================================
The -ppd and -ppi options used to generate dependency lists may specify an
optional filename.  As before the file <sourcefile>.pp is used if no filename is
specified.  The syntax is -ppd[=filename] and -ppi[=filename].


================================================================================
24. REMINDER: Calling Assembler Directly is Deprecated
================================================================================
This reminder is primarily a "heads up" to users moving from Code Composer
Studio versions 2.0x and 2.1x to this version of the tools.

Direct invocation of (asm470) assembler has been deprecated in favor of 
invocation via cl470.  cl470 considers any file with the extension .asm
to be an assembly file and will call the assembler. 

For the most part existing options continue to be supported by asm470, but all 
new options are available only through cl470.