-----------------------------------------------
TMS320C30 C COMPILER PACKAGE
Version 2.10
MS-DOS, PC-DOS Systems
-----------------------------------------------

This package contains release 2.10 of the Texas Instruments TMS320C30
C Compiler and Assembler Development Tools.  Please read these release notes
carefully before using the tools; it provides important information about the
latest release of the tools.  Especially important are the notes about
compatibility and differences between this version and earlier versions of the
tools.

Version 2.10 is a maintenance update to version 2.00, which was released in
June 1989 (no new functionality has been introduced).  This release contains
a new printed manual; the sections on invoking the compiler have been
significantly revised for the new shell program and interlist utility.  Also,
the PC versions of all tools now run under both DOS and OS/2.  Versions 2.00
and 2.10 differ significantly from earlier releases; if you have been using
version 1.30 or earlier, the changes are detailed below.

=======================================================================
HIGHLIGHTS OF RELEASES 2.00 AND 2.10
=======================================================================
The following list summarizes the important changes between this release of the
tools and the previous (v1.30) version:

   - The new CL30 compiler shell program allows you to compile and optionally
     link several programs at once.
   - The new C Source Interlist Utility inserts your C source statements in
     the assembly output of the compiler.
   - The compiler generates improved code in several specific cases (detailed
     below).

If you have been using version 1.10, you will find the following additional
features in this latest release of the compiler:

   - Partial paths are now allowed for #include files.
   - Wildcards are allowed on linker and archiver command lines (except VMS
     versions).
   - All the tools support filenames up to 256 characters long on command
     lines.
   - The tools run faster (up to 2x).
   - The documentation has been updated and printed.
   - A -m code generator option allows integer multiplies to use a single
     MPYI instruction.
   - The -x code generator option causes the compiler to work around the
     hardware bugs in early TMX320C30 devices.

=======================================================================
HOSTS
=======================================================================
The TMS320C30 compiler is available on the following host systems:

   host                          system                       part number
   ---------------------------   --------------------         --------------
   IBM PC, PC/AT or compatible   MS/DOS 2.1 or higher
                                 OS/2   1.1                   TMDS3243855-02
   VAX                           Ultrix 3.0 or higher         TMDS3243265-08
   VAX                           VMS    4.5 or higher         TMDS3243255-08
   Sun-3 Workstation             SunOS  3.5 or higher         TMDS3243555-08
   Macintosh or Macintosh II     MPW    3.0                   TMDS3243565-01

=======================================================================
PACKAGE CONTENTS
=======================================================================
The following is a list of the files contained in this package:

   File          Description
   -----------   --------------
   CPP30.EXE     C Preprocessor
   CC30.EXE      TMS320C30 C Parser
   CG30.EXE      TMS320C30 Code Generator

   CL30.EXE      TMS320C30 Compiler Shell Program
   CLIST.EXE     TMS320C30 C Source Interlist Utility

   ASM30.EXE     TMS320C30 Assembler
   LNK30.EXE     TMS320C30 COFF Linker
   ROM30.EXE     TMS320C30 ROM Utility
   AR30.EXE      TMS320C30 Archiver

   RTS.LIB       C Runtime Support Object Library
   RTS.SRC       C Runtime Support Source Library

   *.H           #include header files for RTS:
                     ASSERT.H    CTYPE.H    ERRNO.H    FLOAT.H
                     LIMITS.H    MATH.H     STDARG.H   STDDEF.H
                     STDLIB.H    STRING.H   TIME.H

   C.CMD         Sample link control file for linking C programs.
   README.1ST    On-line release bulletin.


====================================================================
COMPATIBILITY WITH EARLIER VERSIONS
====================================================================
OBJECT CODE

   With one exception, object code produced using the version 1.10 TMS320C30
   tools is compatible with the version 2.10 tools.  The exception is that any
   code compiled under v1.10 that calls a function compiled under v2.10 MUST BE
   RECOMPILED.  This is because the compiler uses a different convention for
   setting the condition flags on the result of a function call: formerly, the
   called function set the flags on its return value; now, the calling function
   must do it.

   Object code produced using version 2.10 of the compiler is completely
   compatible with version 1.30.

   The compiler now produces more efficient code, and all known problems in
   earlier versions of the tools have been fixed.  For these reasons, we
   recommend that you recompile all your source code using the new tools.

ARCHIVER

   Due to a bug in the 1.30 archiver, archive files built with the 1.30
   archiver are not compatible with the new tools.  To use a 1.30 archive
   file with the 2.10 tools:

       1) Use the 1.30 archiver to extract all files:
              ar30 x libname
       2) Use the 2.10 archiver to rebuild the archive:
              ar30 a libname *.*

   The 2.10 archiver IS compatible with the version 1.10 archiver.


====================================================================
SUMMARY OF CHANGES FROM EARLIER VERSIONS
====================================================================
C COMPILER - CHANGES SINCE v2.00

   o  The documentation has been updated and printed.  In addition to minor
      corrections and clarifications, the new shell program and interlist
      utility have been incorporated into the book.

   o  The PC versions of all the tools now run under both DOS and OS/2.

   o  The CL30 shell program returns a correct exit code to the operating
      system when it terminates.

   o  The following cases are now correctly handled:
         - Switch statements with large (>16 bits) case values.
         - Accesses to global structures using the big model.
         - Setting the status bits from the result of:
              a) assignments to pointer register variables.
              b) conditional expressions (? :).
         - Register allocation for expressions where both operands have
           multiple levels of indirection.
         - Using the -mx option to avoid using 3-operand instructions when
           both source operands are indirect and one or both use autoincrement.

CHANGES SINCE v1.30

   o  Two new tools have been added: the CL30 shell program, and the C Source
      Interlist Utility.  These are documented in the new TMS320C30 C Compiler
      Reference Guide.

   o  The compiler now correctly generates C interrupt functions, as described
      in section 4.6, page 4-23, of the Reference Guide.

   o  Handling of the following cases has been optimized or corrected:
         - A new function return sequence is between 2 and 4 cycles faster,
              but is still fully compatible.
         - Conditional expressions of the form a ? b : c are generated
              using load-conditional instructions where possible.
         - Returning structures from functions has been corrected.

CHANGES SINCE v1.10

   o  Handling of the following cases has been improved or optimized:
         - Autoincremented pointer expressions ("*p++" and "*++p") are
             performed in one instruction.
         - Switches on constant values are folded.
         - Multiplication by constants which are the sum or difference of
             powers of two are optimized.
         - Loops are rearranged to generate better code.
         - The compiler generates parallel instructions when it can.
         - The compiler uses the short immediate (16-bit) form for floating
           point constants when no loss of precision occurs.

   o  Partial paths are now supported for #include files.  If you specify
      pathname information in the name of an include file, the compiler
      searches the full path specified with -i or C_DIR by concatenating
      each path in the search list with the partial path in the #include
      statement.  This is differs from the previous operation, and from the
      description on page 3-4 of the C Compiler book.

   o  A new option (-m) has been added to the code generator that directs
      it to use the MPYI instruction for an integer multiply instead of a
      runtime support call.  The MPYI instruction only performs a 24x24 bit
      multiply, but is much faster if your application does not need full
      32x32 integer multiplication.

   o  Another code generator option (-x) has been added that causes it to
      generate workarounds for the known hardware bugs in early TMX320C30
      devices.  Specifically, if -x is used:
         - No simultaneous reads from the parallel bus resulting from
           three-operand or parallel instructions are generated.
         - 16-bit constants that have a 1 in the most significant bit are
           not used with AND or TSTB instructions.
         - No delayed branches are generated.
         - Calls to MPY_I are replaced by MPY_X, which has code to work around
           hardware problems in MPY_I.

   o  The symbol table size has been increased.  On virtual memory systems
      only (all except PC), the compiler now allows:
         - 6000 #defines, with a total maximum of 250000 bytes for
              macro definition storage.
         - 10000 symbols, including variables, structure names, structure
              members, and typedefs.
         - 1000 unnamed structures.
      In addition, the internal label table sizes have been increased.  These
      tables can expand to 10000 entries on virtual systems, and to 4000 on
      PCs.

   o  The following cases are now correctly handled:
         - Use of the big model (-b).
         - Indirect assignments to nested structures.
         - Right shift expressions.
         - Use of a function call in a conditional context (if (f() == 0)...).
         - Bit fields.
         - Initialization of large objects.
         - Initialization of a static object with a pointer to itself.
         - 'Register enum' declarations.
         - Passing a structure to a function as one of several arguments.
         - Switch statements with one-case "holes".
         - Comparison of two floating point constants.

   o  The compiler now correctly detects the following error conditions:
         - Floating point expressions in switch operands.
         - Redeclarations of functions.
         - Shifting by a negative constant.
         - A structure member with array or function type used as an lvalue.

   o  Fixed a problem where an extern that was declared twice in one block,
      then redeclared again later, was not accessed correctly.


=======================================================================
RUNTIME SUPPORT (rts.lib, rts.src)

The runtime support library has been updated to reflect the latest
specification in the Dec '88 draft ANSI C Standard.  All the ANSI functions
are provided except those that require an underlying operating system
(I/O, signals, etc.).  All known problems in the library have been fixed,
and many of the string functions have been rewritten to capitalize on the
compiler's improved handling of "*p++".

In addition, many of the run-time support functions had problems which have
been fixed:
   - A problem with mktime() when using 32-bit time values.
   - strtol() and strtoul() not terminating correctly.
   - Converting values of 0 ecvt() and fcvt().
   - Passing -1 (EOF) to the character classification functions
     (isupper(), ...)

All the functions in the library follow the ANSI draft specification.  There
are a few additional common C functions that are included but are not part of
the ANSI draft specification.

The runtime library was compiled with the -x code generator option, which
directs the compiler to avoid bugs in first pass TMX320C30 devices. If you are
using newer silicon you can recompile the library without the -x option,
allowing the code generator to produce slightly more efficient code.  To do
this:

   1) Extract the source files from rts.src:  ar30 x rts.src
   2) Recompile without the -x option:  cl30 *.c
   3) Replace the new files in rts.lib:  ar30 r rts.lib *.obj

Note that the source code for the trigonometric, hyperbolic, and exponential
math functions functions is not provided in the source library RTS.SRC for
licensing reasons.

=======================================================================
ASSEMBLER - CHANGES SINCE v1.30

   o  The PC versions of all the tools (assembler, linker, archiver, ROM
      utility) now run under both DOS and OS/2.

   o  Fixed problems in the following cases:
         - a .space directive with a size operand greater than 07FFFh.
         - assembling instructions of the form ADDI *+ARn(0),Rx,Ry.
         - labels declared in .asect sections being relocated.

CHANGES SINCE v1.10

   o  The search algorithm for .inlcude files and .copy files has been
      changed.  The assembler will now search the directories specified with
      -i or C_DIR for all included files, even if the name has partial path
      information.  (The partial path is concatenated with the directory names
      in the search path.)  This is different than described in the user's
      guide in section 4.3, page 4-4.

   o  Now allows section names without quotes to be used in .sect and
      .usect directives.

   o  The assembler now handles the following cases correctly:
         - the opcode for IACK is now correct.
         - a label on the same line as a macro invocation, when the macro
              is defined in a macro library.
         - assembling the floating point constant -0.0.
         - conditional expressions within macro definitions.

   o  The assembler now longer assumes 32-bit constant expressions.  For
      example, the expression ~1 can now be used as a 16-bit immediate
      operand.


=======================================================================
LINKER - CHANGES SINCE v2.00

   o  The linker now correctly handles zero-length GROUPs.

CHANGES SINCE v1.10

   o  Now allows wildcard characters for filename specifications on the
      command line (except VMS versions).

   o  You can now use the -l option to cause the linker to search its directory
      search path for ANY input file.  This way, any file specified with -l
      including object and command files as well as libraries can be located
      anywhere along the search path specified with the -i option or the C_DIR
      environment variable.

   o  Fixed a problem with the GROUP directive causing allocation failures
      when used with no page number specified.

   o  Fixed an allocation problem where an STYP_DSECT section that was last
      to be allocated (usually .cinit when using the -cr option) would not get
      written to the output file.

   o  Corrected a rare symbol hashing problem.

   o  Changed how the linker allocates zero-length sections.  In previous
      versions, a zero-length section in a SECTIONS directive would
      be allocated at the END of other sections in the same memory area:
         SECTIONS
         {
            .text   : {} > ROM      /* length = 100, allocated at 0 */
            endmark : {} > ROM      /* length = 0, allocated at 100 */
         }
      In previous versions, this could be used to define a pointer to the end
      of a program or data area for example.

      However, zero-length sections are now allocated at the BEGINNING of their
      memory area.  (This change was made to preserve the linker's best-fit
      allocation algorithm.)  In the example above, both .text and endmark
      will now be allocated at address 0.

      You can use the GROUP directive to force the linker to allocate sections
      contiguously and in order.  In the example above, the correct way to
      specify that the zero-length section follow .text is:
         SECTIONS
         {
            GROUP:
            {
               .text   : {}         /* length = 100, allocated at 0 */
               endmark : {}         /* allocated right after .text  */
            } > ROM
         }

=======================================================================
ARCHIVER - CHANGES SINCE v1.10

   o  Now allows wildcard characters for filename specifications on the
      command line (except VMS versions).

   o  The archiver and linker now fully support files with opposite
      byte-ordering from the host system on which the tools are running.
      This applies to both object files and archive libraries.  This means
      that you can build objects or archives on one system, then tranfser
      them to and use them on a host with opposite byte-ordering.

   o  An undocumented option allows you to list a table of the symbols
      defined in an archive.  Use the -a (add) option with no object files,
      together with the -s (list symbols) option:

         ar30 -as func.lib

=======================================================================
ROM UTILITY - CHANGES SINCE v1.10

   o  Now outputs all 32 bits of the input data.  Using byte conversion
      formats (-x and -i), the utility outputs four hex files:
          xxx.B0  - least significant byte
          xxx.B1
          xxx.B2
          xxx.B3  - most significant byte

   o  Changed the output hex format to use all uppercase characters.


=======================================================================
KNOWN SOFTWARE AND DOCUMENTATION ERRORS
=======================================================================
ASSEMBLY LANGUAGE TOOLS USER'S GUIDE

o The description of the -h linker option in section 9.3.5 (page 9-7) is
  incorrect.  The -h option makes OUTPUT global symbols static, not INPUT
  global symbols.  This is useful when you are using partial linking to
  link related object files into self-contained modules, then relinking the
  modules together into a final system.  If there are global symbols in
  one module that have the same name as global symbols in other modules, but
  you want to treat them as separate symbols, use the -h option when building
  the modules.  The global symbols in the module, which would normally be
  visible to the other modules and cause possible redefinition problems in the
  final link, are made static so they are not visible to the other modules.

o A correction to table A-3 on page A-5, Optional File Header Contents:

    bytes    type     description
    -----    -----    -------------------------
    16-19    long     Entry point address of the program
    20-24    long     First address of exectable code

o IMPORTANT NOTE ON INSTALLATION:
  Section 2.2 Installation for VAX/VMS, the following line should be omitted:

                $init/den=1600    TAPE:C30

  The following line:

                $backup TAPE:ASM30.BCK DEST[:directory]

  should read for installing the C compiler:

                $backup TAPE:C30.BCK/SELECT=[MASTER.C30C...] DEST:[DIRECTORY...]

  and should read for installing the Assembly Language Tools:

                $backup TAPE:C30.BCK/SELECT=[MASTER.C30A...] DEST:[DIRECTORY...]




























