Home

"TMS320C3x/C4x Optimizing C Compiler User's Guide"

1. typedef unsigned size_t if _INLINE define _ INLINE static inline Declaration when inlining else define __INLINE No declaration when not inlining endif __ INLINE void memcpy void _sl const void _s2 size_t _n if _INLINE Declare the inlined function static inline void memcpy void to const void from size_t n register char rto char to register char rfrom char from register size_t rn for rn 0 rn lt n n rtot rfromt return to endif _INLINE undef __ INLINE KK KR A RR RA RAR AR AR AAA AAR AR A AAR A A A A A IR I I I MEMCPY C rtsxx lib A KKK KR RR A A A A A AR A RAR A RA A A RAR A RAR A A A A A I IA I I undef _INLINE Turn off so code will be generated include lt string h gt void memcpy void to const void from size_t n register char rto char to register char rfrom char from register size_t rn For fn 07 rn lt ny xnt rbot rfrom return to There are two definitions of the memcpy function The first in the header file is an inline definition Note how this definition is
2. PUSH AR4 R2 assigned to variable sum LDI QCONST 0 AR4 LDI CONST 1 AR2 PYF AR2 AR4 RO RPTS 8 ADDF RO R2 PYF AR2 AR4 RO ADDF RO R2 LDF R2 RO EPIO_1 POP AR4 RETS globl _a bss _a 10 globl _b bss _b 10 DEFINE CONSTANTS bss CONST 2 Sect cinit word 2 CONST word _a word _b end if a2 opt a2 asm a2 tmp 30 AR3 RO Description of Compiler Optimizations A 5 Description of Compiler Optimizations Conditional instructions The load instructions in the TMS320C3x C4x can be executed conditionally For simple assignments such as a condition exprl expr2 or if condition a b the compiler can use conditional loads to avoid costly branches Delayed branches The TMS320C3x C4x provides delayed branch instructions that can be inserted three instructions early in an instruction stream avoiding costly pipeline flushes associated with normal branches The compiler uses unconditional delayed branches wherever possible and conditional delayed branches for counting loops See Example A 3 Example A 3 TMS320C3x C4x Delayed Branch Instructions wait volatile int p for if p amp 0x08 p OxFO KKK KKK KR KKK KKK
3. i UNDEFINED REFERENCES ia globl _call end Description of Compiler Optimizations Description of Compiler Optimizations J Cost based register allocation The optimizer when enabled allocates registers to user variables and compiler temporary values according to their type use and frequency Vari ables used within loops are weighted to have priority over others and those variables whose uses don t overlap may be allocated to the same register Variables with specific requirements are allocated into registers that can accommodate them For example the compiler tries to allocate loop counters into RC The allocation algorithm also minimizes pipeline conflicts that can result from performing calculations using address generation registers in the vicinity of indirection J Passing arguments in registers The compiler supports a new optional calling sequence that passes arguments to registers rather than pushing them onto the stack This can result in significant improvement in execution performance especially if calls are importa
4. FUNCTION DEF _add3 _add3 PUSH FP LDI SP FP R2 assigned to variable sum LDI FP 2 AR2 LDI O R2 ADDI AR2 R2 ADDI AR2 R2 ADDI AR2 R2 LDI R2 RO0 EPIO_1 LDI FP 1 R1 BD RI LDI FP FP OP SUBI 27 SP ERE B R1 BRANCH OCCURS end i lt 3 i sum a i Version X XX A 14 Description of Compiler Optimizations Loop rotation The compiler evaluates loop conditionals at the bottom of loops saving a cost ly extra branch out of the loop In many cases the initial entry conditional check and the branch are optimized out Loop invariant code motion This optimization identifies expressions within loops that always compute the same value The computation is moved in front of the loop and each occur rence of the expression in the loop is replaced by a reference to the precomputed value See Example A 8 Inline function expansion The special keyword inline directs the compiler to replace calls to a function with inline code saving the overhead associated with a function call as well as providing increased
5. extern int my_open char path unsigned flags int fno extern int my_close int fno extern int my_read int fno char buffer unsigned count extern int my_write int fno char buffer unsigned count extern int my_lseek int fno long offset int origin extern int my_unlink char path extern int my_rename char old_name char new_name main FILE fid add_device mydevice _MSA my_open my_close my_read my_write my_lseek my_unlink my_rename fid fopen mydevice test w fprintf fid Hello world n fclose fid 5 24 Syntax Defined in Description Syntax Defined in Description Example Alphabetical Summary of Runtime Support Functions asctime asin Internal Time to String include lt time h gt char asctime struct tm timeptr asctime c in rts src The asctime function converts a broken down time into a string with the following form Mon Jan 11 11 18 36 1988 n O The function returns a pointer to the converted string For more information about the functions and types that the time h header declares refer to subsection 5 2 13 page 5 11 Arc Sine include lt math h gt double asin double x asin c in rts src The asin function returns the arc sine of a floating point argument x x must be in the range 1 1 The return value is
6. FUNCTION DEF _blkcpy KKKKKKKK KKK KK KKK KKK KK KKK KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKKKK KKK KKK KK _blkcpy PUSH AR4 R3 assigned to parameter n AR2 assigned to parameter to AR4 assigned to parameter from LDI R2 AR4 CMP I 0 R3 BLE EPIO_1 LDI R3 RC SUBI 1 RC RPTB L5 LDI AR4 R0 LS STI RO AR2 EPIO_1 POP AR4 RETS globl _initstr KKKKKKKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKKKKKKK KKK KKK KKK KK KK FUNCTION DEF _initstr _initstr PUSH AR4 AR2 assigned to parameter ps AR2 assigned to variable to AR4 assigned to parameter to AR4 assigned to variable from LDI R2 AR4 D gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt gt ENTERING blkcpy LDI AR4 R0 RPTS 10 STI RO AR2 LDI AR4 R0 STI RO AR2 EPIO_2 POP AR4 RETS end Appendix B The C I O Functions Some of the tasks that a C program performs such as
7. The DATA_SECTION pragma is useful if you have data objects that you want to link into an area separate from the bss section If you use a section name longer than eight characters you must use COFF2 Example 3 3 demonstrates the use of the DATA_SECTION pragma Example 3 3 Using the DATA_SECTION Pragma a C source file pragma DATA_SECTION bufferB my_sect char bufferA 512 char bufferB 512 b Assembly source file global _bufferA bss _bufferA 512 global _bufferB _bufferB usect my_sect 512 1 3 5 3 The FUNC_CANNOT_INLINE Pragma The FUNC_CANNOT_INLINE pragma instructs the compiler that the named function cannot be expanded inline Any function named with this pragma overrides any inlining you designate in any other way such as using the inline keyword The pragma must appear before any declaration or reference to the function that you want to keep The syntax of the pragma is pragma FUNC_CANNOT_INLINE func The argument func is the name of the C function that cannot be inlined For more information see Section 2 5 Function Inlining on page 2 43 TMS320C3x C4x C Language 3 13 Pragma Directives 3 5 4 The FUNC_EXT_CALLED Pragma When you use the pm option the compiler uses program level optimization When you use this type of optimization the compiler removes any function that is not called directly or indirectly by main You might
8. 005 2 6 2 Using the Interlist Utility With the Optimizer 000200 00s How the Compiler Handles Errors 00 0 e cece eee eee eee 2 7 1 Treating Code E Errors as Warnings pe Option 2 7 2 Suppressing Warning Messages pw Option 2 2 0000 ee 2 7 3 An Example of How You Can Use Error Options pp INMINSICS d2cicvataddnwheecreecte dee rhein d ooebeawele aan a Ss eeadaaiied Invoking the Tools Individually i 2 9 1 Invoking the Parser ss dria 2 9 2 Optimizing Parser Output 0 0000 2 9 3 Invoking the Code Generator i 2 9 4 Invoking the Interlist Utility et Linking C Goode ps erie aa a a eared nue oe eaa aoa ea Beare 2 10 1 Invoking the Linker a 2 10 2 Using the Shell to Invoke the Linker z Option 00 2 10 3 Controlling the Linking Process pp TMS320C3x C4x C Language pe Discusses the specific characteristics of the TMS320C3x C4x C compiler as they relate to the ANSI C specification 3 1 3 2 3 3 3 4 3 5 3 6 3 7 3 8 3 9 3 10 3 11 Characteristics of TMS320C3X C4XC ec teens 3 2 Data Types sn i ed sddeeus Gr EN i afaa Cidade R ETEA 3 4 32 1 The Long Double Data Type ere 3 5 KeywWords esis sad SL ve ee ene ee er awe este 3 7 3 3 1 The cregister Keyword sn 3 7 3 3 2 The near and far Keywords i Register Variables oscinina ninasi iiie iaai ent a i 3 10 Pragma DiecnVes so iritan Shea a a AEE ai 3 11 3 5 1 The CODE SECTION Pragma
9. VXX zZ Shell Option ma mf ol0 ol1 ol2 oisize op1 op2 op3 Function assume variables are aliased force indirect access to externals specify that this file alters a standard library function 03 only specify that this file defines a standard library function 03 only specify that this file does not define or alter library functions 03 only set automatic inlining size 03 only allow K amp R compatibility enable short multiply C3x only do not produce information file produce information file produce verbose information file level 0 register optimization level 1 level 0 local optimization level 2 level 1 global optimization level 3 level 2 file optimization specify that callable functions and or modifiable variables are used in this module specify that no callable functions are used in this module default specify that no modifiable variables or call able functions are used in this module specify that no modifiable variables are used in this module but modifiable func tions may be used suppress progress messages quiet use register argument runtime model interlist optimizer comments allow zero overhead loop operations specify processor xx 30 31 32 40 or 44 default is v30 optimize primarily to reduce size then to improve speed C Compiler Description 2 61 Invoking the Tools Individually 2 9 3 2 62 In
10. stdlib h header string h header time h header heap 4 4 reserved space heap linker option heap16 linker option heap8 linker option hex conversion utility HUGE_VAL hyperbolic cosine 5 34 hyperbolic math function hyperbolic sine hyperbolic tangent 5 75 i compiler option i linker option VO adding a device B 5 definitions low level described 5 5 B 2 functions CLOSE B 7 flush buffer implementation overview I O functions identifiers C language idir compiler option if extension 2 57 implementation errors implementation defined behavior 3 2 8 3 include files adding a directory to be searched include preprocessor directive 5 4 initialization 2 69 initialized sections const text 4 2 Cinit Index 5 Index initializing global variables C language initializing static variables C language 3 18 _ INLINE 2 31 2 46 inline assembly construct asm 4 28 inline assembly language 4 28 inline functions 2 44 input output definitions 5 5 integer division interfacing C and assembly language 4 24 asm engl interlist utility REH options eT using with optimizer 2 40 intermediate file 2 57 2 59 interrupt handling 4 3d 4 31 INTERRUPT pragma intrinsic operators 2 45 inverse tangent of y x invoking the C compiler C compiler tools individually code generator interlist utili
11. O O O O O O O O O L The arguments func and symbol must have file scope that is you cannot define or declare them inside the body of a function You must specify the pragma outside the body of a function and it must occur before any declara tion definition or reference to the funcor symbolargument If you do not follow these rules the compiler issues a warning TMS320C3x C4x C Language 3 11 Pragma Directives 3 5 1 The CODE_SECTION Pragma The CODE_SECTION pragma allocates space for the symbol in a section named section name The syntax of the pragma is pragma CODE_SECTION symbol section name The section will be declared by the compiler with the sect assembler directive If you use a section name longer than eight characters you must use COFF2 The CODE_SECTION pragma is useful if you have code objects that you want to link into an area separate from the bss section Example 3 2 demonstrates the use of the CODE_SECTION pragma Example 3 2 Using the CODE_SECTION Pragma a C source file pragma CODE_SECTION fn my_sect int fn int x return c b Assembly source file Sect my_sect global _fn 3 12 Pragma Directives 3 5 2 The DATA_SECTION Pragma The DATA_SECTION pragma allocates space for the symbol in a section named section name The syntax of the pragma is pragma DATA_SECTION symbol section name
12. fclose fid B 6 CLOSE Syntax Description Return Value LSEEK Syntax Description Return Value Alphabetical Summary of C I O Functions CLOSE LSEEK Close File or Device For I O int CLOSE int file_descripton The CLOSE function closes the device or file associated with file_descriptor The file_descriptor is the stream number assigned by the low level routines that is associated with the opened device or file The function returns one of the following values 0 if successful 1 if fails Set File Position Indicator long LSEEK int file_descriptor long offset int origin The LSEEK function sets the file position indicator for the given file to origin offset The file position indicator measures the position in characters from the beginning of the file The file_descriptor is the stream number assigned by the low level routines that the device level driver must associate with the opened file or device The offset indicates the relative offset from the origin in characters The origin is used to indicate which of the base locations the offset is measured from The origin must be a value returned by one of the follow ing macros SEEK_SET 0x0000 Beginning of file SEEK_CUR 0x0001 Current value of the file position indicator SEEK_END 0x0002 End of file The function returns one of the following values new value of the file position indicator if successful EOF if
13. SUSPM 2 220 nasa strstr strtod strtok strtol strtoul strxfrm tmpfile tmpnam toascii tolower toupper ungetc va_arg va_end va_start vVfprintf vprintf vsprintf Runtime Support Functions 5 21 abort abs labs acos Alphabetical Summary of Runtime Support Functions Syntax Defined in Description abs labs Syntax Defined in Description Example Syntax Defined in Description Example 5 22 Abort include lt stdlib h gt void abort void exit c in rts src The abort function usually terminates a program with an error code The TMS320C3x C4x implementation of the abort function calls the exit function with a value of 0 and is defined as follows void abort exit 0 This makes the abort function equivalent to the exit function Absolute Value include lt stdlib h gt int abs int j long int labs long int k abs c in rts src The C compiler supports two functions that return the absolute value of an integer The abs function returns the absolute value of an integer j The labs function returns the absolute value of a long integer k Since int and long int are functionally equivalent types in TMS320C3x C4x C the abs and labs functions are also functionally equivalent The abs and labs functions are expanded inline unless the x0 option is used int x
14. include lt stdlib h gt void qsort void base size_t n size_t size int compar void qsort c in rts src The qsort function sorts an array of n members Argument base points to the first member of the unsorted array argument size specifies the size of each member This function sorts the array in ascending order Argument compar points to a function that compares key to the array elements The comparison function should be declared as int cmp void ptrl void ptr2 The cmp function compares the objects that ptr1 and ptr2 point to and returns one of the following values lt 0 if ptr1 is less than ptr2 0 if ptr1 is equal to ptr2 gt 0 if ptr1 is greater than ptr2 The array sort will not work correctly if the CMP function fails to return the cor rect values for all three conditions In the following example a short list of integers is sorted with qsort include lt stdlib h gt int listi 3 Iip 4 1 5 9 2 623 int idiff const void const void main qsort list 8 1 idiff after sorting list 1 1 2 3 4 5 6 9 int idiff const void il const void i2 return int il int 1i2 Syntax Defined in Description Syntax Defined in Description Alphabetical Summary of Runtime Support Functions rand srand realloc Random Integer include lt stdlib h gt int rand void void srand unsigned int seed rand c in rts sr
15. must not cross any 64K boundaries memory model E bss section fits within a single page bss must be smaller than 64K words and the directory in which rts lib is add a i lt directory gt line to this nvironment variable C_DIR to path for libraries be sure 2y O LINK USING C CONVENTIONS af stack 0x400 1K STACK hf heap 0x400 1K HEAP xf lrts40 lib GET RUN TIME SUPPORT my SPECIFY THE SYSTEM MEMORY MAP MEMORY ROM org 0x000000 len 0x1000 INTERNAL ROM RAMO org 0x2FF800 len 0x400 RAM BLOCK 0 7 RAM1 org 0x2FFC00 len 0x400 RAM BLOCK 1 A LOCAL org 0x300000 len 0x7D00000 LOCAL BUS GLOBAL org 0x8000000 len 0x8000000 GLOBAL BUS SPECIFY THE SECTIONS ALLOCATION INTO MEMORY SECTIONS text gt LOCAL CODE x7 Cinits gt LOCAL INITIALIZATION TABLES const gt LOCAL CONSTANTS y stack gt RAMO SYSTEM STACK 4 Sysmem gt RAM DYNAMIC MEMORY HEAP bss gt LOCAL block 0x10000 VARIABLES C Compiler Description 2 73 L
16. 5 int y abs x abs returns 5 Arc Cosine include lt math h gt double acos double x acos c in rts src The acos function returns the arc cosine of a floating point argument x x must be in the range 1 1 The return value is an angle in the range 0 7 radians double realval radians realval 0 03 radians acos realval acos return 1 2 return radians Syntax Defined in Description Parameters Return Value Alphabetical Summary of Runtime Support Functions add_device Add Device to Device Table include lt stdio h gt int add_device char name lowlev c in rts src unsigned flags int dopen int dclose int dread int dwrite int diseek int dunlink int drename Adds a device record to the device table allowing that device to be used for input output from C The first entry in the device table is predefined to be the host device on which the debugger is running The function add_device finds the first empty position in the device table and initializes the fields of the structure that represent a device To open a stream on a newly added device use fopen with a string of the for mat devicename filename as the first argument name flags dopen dclose dread dwrite dlseek dunlink drename 0 if successful 1 if it fails Character string denoting the device name Device characteristics The flags denote
17. where constant cl1 in the bss holds the address of the function By default the compiler generates small memory model code which means that every function call is handled as if it were declared near unless it is actu ally declared far The default changes however when options ml mf or mb are used Summary of Updates in This Document D 5 Summary of Updates in This Document Page 4 31 D 6 Change the last four lines of the EXIT code example Change or Add Exit POP AR4 POPF R4 POP R4 POPF R3 g POP R3 7 SUBI 2 SP POP FP POP ST reti Cut the second bullet for the restore AR4 restore upper 32 restore lower 32 restore upper 32 restore lower 32 deallocate local bits bits bits bits frame restore Frame Pointer restore STatus register of of of Of Using the I O Functions section R4 R4 R3 R3 Change or Add Summary of Updates in This Document The following is the list of known bugs fixed for this release R5 10 Please refer to the ap propriate contact on the If You Need Assistance page of this manual for more information Bug number SDSsq02943 SDSsq03255 SDSsq03762 SDSsq03767 SDSsq03797 SDSsq03799 SDSsq03814 SDSsq03879 SDSsq03888 SDSsq03890 SDSsq03897 SDSsq03908 SDSsq03910 SDSsq03921 SDSsq03982 SDSsq03985 SDSsq03988 SDSsq03993 SDSsq04019 SDSsq04024 SDSsq04084 Description How should the SET COND bit be set in the C4x ST
18. Describes general optimizations that improve any C code and specific optimizations designed especially for the TMS320C3x C4x architecture The C UO Functions 00000 se Describes the C I O library included with the C compiler Bt Using the I O Functions 0c teens B 2 B 2 Overview of Low Level I O Implementation i B 3 B3 Adding a Device For C O ss cnet eee A B 5 GIOSSANY iets vice Shae seater denen vba G E EE E dak h OTa ee ee ime C 1 Defines terms and acronyms used in this book Summary of Updates in This Document pp Provides a summary of the updates in this version of the document Bit KONOS nm i esl es a de BOG Ree AA EN D 3 3 1 1 Thecregister Keyword ss D 3 3 3 2 The near and far Keywords pp D 4 Figures TMS320C3x C4x Software Development Flow The cl30 Shell Program Overview pp Compiling a C Program with the Optimizer Compiler Overview pp Sample Linker Command File for TMS320C3x C Programs Sample Linker Command File for TMS320C4x C Programs Stack Use During a Function Call Register Argument Conventions i Format of Initialization Records in the cinit Section RAM Model of Autoinitialization ROM Model of Autoinitialization 0 Interaction of Data Structures in I O Functions The First Three Streams in the Stream Table Contents XV Tables Ct tee oe Me oOMHNOOR ODM 4 3 xvi Compiler Options Summary Table i 2 6 Predefined Macro Names i 2 31 Supported Intrinsic Functions ot 2 54 Parser Opti
19. Syntax Defined in Description Syntax Defined in Description Raise to a Power include lt math h gt double pow double x double y pow c in rts src The pow function returns x raised to the power y A domain error occurs if x 0 and y lt 0 or if x is negative and y is not an integer A range error may occur if the result is too large to represent double x Y Z x 2 0 y 3 0 Z pow x y return value 8 0 Write to Standard Output include lt stdio h gt int printf const char format printf c in rts src Writes to the standard output device How to write the stream is described by a string pointed to by format Write Character include lt stdio h gt int putc int x FILE p fputc c in rts src Writes a character to a stream The stream is pointed to by p Alphabetical Summary of Runtime Support Functions putchar puts PMC Write Character to Standard Output Syntax include lt stdlib h gt int putchar int x Defined in fputc c in rts src Description Writes a character to the standard output device icm Write to Standard Output Syntax include lt stdlib h gt int puts const char ptr Defined in fputs c in rts src Description Writes a string to the standard output device The string is pointed to by ptr Runtime Support Functions 5 55 qsort Alphabetical Summary of Runtime Support Functions Syntax Defined in Description Example Array Sort
20. The stdlib h header also declares many of the common library functions D String conversion functions that convert strings to numeric representations D Searching and sorting functions that allow you to search and sort arrays Sequence generation functions that allow you to generate a pseudorandom sequence and allow you to choose a starting point for a sequence Header Files Program exit functions that allow your program to terminate normally or abnormally Integer arithmetic that is not provided as a standard part of the C language 5 2 12 String Functions string h The string h header declares standard functions that allow you to perform the following tasks with character arrays strings Lj Lj Lj m Move or copy entire strings or portions of strings Concatenate strings Compare strings Search strings for characters or other strings Find the length of a string In C all character strings are terminated with a 0 null character The string functions named strxxx all operate according to this convention Additional functions that are also declared in string h allow you to perform corresponding operations on arbitrary sequences of bytes data objects where a 0 value does not terminate the object These functions have names such as memxxx When you use functions that move or copy strings be sure that the destination is large enough to contain the result 5 2 13 Time Functions time h The time header d
21. div i j result quot 3 result rem 1 Runtime Support Functions 5 35 exit exp fabs Alphabetical Summary of Runtime Support Functions Syntax Defined in Description Syntax Defined in Description Example Syntax Defined in Description Example Normal Termination include lt stdlib h gt void exit int status exit c in rts src The exit function terminates a program normally All functions registered by the atexit function are called in reverse order of their registration You can modify the exit function to perform application specific shutdown tasks The unmodified function simply runs in an infinite loop until the system is reset Note that the exit function cannot return to its caller Exponential include lt math h gt double exp double x exp c in rts src The exp function returns the exponential function of x The return value is the number e raised to the power x A range error occurs if the magnitude of x is too large double x y x Y 207 exp x y 7 38905 which is e 2 Absolute Value include lt math h gt double fabs double x fabs c in rts src The fabs function returns the absolute value of a floating point number x The fabs function is expanded inline unless the x0 option is used double x y SDT Dy x y fabs x return value 57 5 Alphabetical Summary of Runtime Support Functions fclose feof ferror ffl
22. size_t strespn char s1 char s2 strcspn c in rts src The strespn function returns the length of the initial segment of s1 which is made up entirely of characters that are not in s2 lf the first character in st is in s2 the function returns 0 char stra who is there char strb abcdefghijklmnopgqrstuvwxyz char strc abcdefg size_t length length strespn stra strb length 0 length strespn stra strc length 9 Runtime Support Functions 5 65 strerror strftime Alphabetical Summary of Runtime Support Functions EX String Error Syntax include lt string h gt char strerror int errnum Defined in strerror c in rts src Description The strerror function returns the string error This function is supplied to pro vide ANSI compatibility EMC Format Time Syntax include lt time h gt size_t strftime char s size_t maxsize char format struct tm timeptr Defined in stritime c in rts src Description The strftime function formats a time pointed to by timeptr according to a format string and returns the formatted result in the string s Up to maxsize characters can be written to s The format parameter is a string of characters that tells the strftime function how to format the time The following list shows the valid characters and describes what each character expands to Character is replaced by sa the abbreviated weekday name Mon Tue A t
23. specify processor TMS320Cxx v30 v32 v40 v44 Effect K amp R compatible compatible with previous C standards suppress warning messages enable trigraph expansion Effect level 0 register optimization level 1 level 0 local optimization level 2 level 1 global optimization level 3 level 2 file optimization defines _INLINE invokes optimizer at level 2 Effect default inlining level defines _INLINE invokes optimizer at level 2 Effect assumes aliased variables big memory model fast float to int conversion far pointers avoid RPTS loops runtime support assembly calls use far calls use MPYI for multiply enables optimization disabled by g perform speed optimizations at cost of increased code size register argument conventions assume all memory accessible when optimizing generate Ada compatible frame structure generate Tartan LAJ compatible function prolog Type Checking Options tf tp Assembler Options as Options Summary Effect relax prototype checking relax pointer combination checking Effect keep labels as symbols Library Build Utility 6 5 Appendix A Description of Compiler Optimizations The TMS320C3x C4x C compiler uses a variety of optimization techniques to improve the execution speed of your C programs and to reduce their size Optimization occurs at various levels throughout the compiler Most of the optimizations described here are performed by the separate opt
24. 0x2000 I O BUS x RAMO org 0x809800 len 0x400 RAM BLOCK 0 xy RAM1 org 0x809c00 len 0x400 RAM BLOCK 1 EXT1 org 0x80a000 len 0x7f6000 EXTERNAL MEMORY SPECIFY THE SECTIONS ALLOCATION INTO MEMORY SECTIONS text gt EXTO CODE oe na te gt EXTO INITIALIZATION TABLI const gt EXTO CONSTANTS Stack gt RAMO SYSTEM STACK k sysmem gt RAM1 DYNAMIC MEMORY HEAF bss gt EXT1 block 0x10000 VARIABLES 2 72 Linking C Code Figure 2 5 Sample Linker Command File for TMS320C4x C Programs 8K IR RR AR AA RA RA AIA AAA RA AA A A AA A A A A A A A A A A ak a f JE f C40 CMD Usage Descr Notes v4 60 iption lL COMMAND FILE FOR LINKING C40 C PROGRAMS lnk30 lt obj files gt o lt out file gt m lt map file gt c40 cmd This file is a sample command file that can be used for linking programs built with the TMS320C40 C Compiler Use it a guideline you may want to change the allocation scheme according to the size of your program and the memory layout of your target system Be sure to us th right library Use a library that matches the runtime model you are using You must speci located Eith fy er file or use t specify a sear When using the he system ch small that the ENTIR To satisfy thi S default
25. 1 if fails Write Characters to Buffer int WRITE int file_descriptor char buffer unsigned count The WRITE function writes the number of characters specified by count from the buffer to the device or file associated with file_descriptor The file_descriptor is the stream number assigned by the low level routines that is associated with the opened file or device D The buffer is the location of the buffer where the write characters are placed The count is the number of characters to write to the device or file The function returns one of the following values number of characters written is successful 1 if fails Appendix C Glossary aliasing amethod of accessing asingle data object in more than one way as when a pointer points to a named object The optimizer has logic to detect aliasing but aliasing can cause problems for the optimizer allocation A process in which the linker calculates the final memory addresses of output sections archive library A collection of individual files that have been grouped into a single file archiver A software program that allows you to collect several individual files into a single file called an archive library The archiver also allows you to delete extract or replace members of the archive library as well as to add new members assembler A software program that creates a machine language program from a source file that contains assembly language instr
26. Convert Long Integer to ASCII include lt stdlib h gt int Itoa long n char buffer Itoa c in rts src The ltoa function converts a long integer n to the equivalent ASCII string and writes it into buffer with a null terminator If the input number n is negative a leading minus sign is output The ltoa function returns the number of characters placed in the buffer not including the terminator int 1 char s 10 i ltoa 92993L s i 6 s 92993 Runtime Support Functions 5 47 malloc Alphabetical Summary of Runtime Support Functions Syntax Defined in Description Example Allocate Memory include lt stdlib h gt void malloc size_t size void malloc8 amp size_t_ size void malloc16 size_t_ size memory c in rts src The malloc function allocates space for an object of size bytes and returns a pointer to the space If malloc cannot allocate the packet that is if it runs out of memory it returns a null pointer 0 This function does not modify the memory it allocates The memory that malloc uses is in a special memory pool or heap defined in an uninitialized named section called sysmem in memory c The linker sets the size of this section from the value specified by the heap option Default heap size is 1K words For the TMS320C32 processor 8 bit and 16 bit versions of the malloc function are provided The functions malloc8 and malloc16 are analogous to malloc however memory
27. OPEN READ RENAME WRITE UNLINK O O O O O C L The first entry in the device table is predefined to be the host device on which the debugger is running The low level routine add_device finds the first empty position in the device table and initializes the device fields with the passed in arguments For a complete description see the add_device function on page 5 23 3 Once the device is added call fopen to open a stream and associate it with that device Use devicename filename as the first argument to fopen The C I O Functions B 5 Adding a Device For C I O The following program illustrates adding and using a device for C I O include lt stdio h gt KOR KK KK KK KK KK RR A A A A A IR A A A A A A A A A Ta a a Hk a oe Declarations of the user defined device drivers 8K RRR RRR AAA AA IAA A A A A IA A A IA I IA I IA A A A IA A A A I oe extern int my_open char path unsigned flags int fno extern int my_close int fno extern int my_read int fno char buffer unsigned count extern int my_write int fno char buffer unsigned count extern int my_lseek int fno long offset int origin extern int my_unlink char path extern int my_rename char old_name char new_name main FILE fid add_device mydevice _MSA my_open my_close my_read my_write my_lseek my_unlink my_rename fid fopen mydevice test w fprintf fid Hello world n
28. See sec tion 3 5 2 The DATA_SECTION pragma on page 3 13 Near and far function calls Function calls can be invoked in one of two ways near keyword The compiler assumes that the destination of the call is within 224 bytes of the caller Here the compiler uses the PC relative call instruction call _func far keyword The compiler is told by the user that the call is not within 224 bytes of the caller and the compiler uses the register ad dressing mode of the call instruction ldiu cll ro callu ro where constant cl1 in the bss holds the address of the function By default the compiler generates small memory model code which means that every function call is handled as if it were declared near unless it is actu ally declared far The default changes however when options ml mf and mb are used Large memory model code which means that every data ob ject is handled as if it were declared far is then generated TMS320C3x C4x C Language 3 9 Register Variables 3 4 Register Variables The TMS320C3x C4x C compiler treats register variables variables declared with the registerkeyword differently depending on whether or not you use the optimizer Compiling With the Optimizer The compiler ignores any register declarations and treats all variables as register variables while optimizing Compiling Without the Optimizer If you use the register keyword you can suggest variables as candidates for allocation i
29. TMS320C3x C4x C Language 3 21 Compatibility With K amp R C pk Option 3 10 Compatibility With K amp R C pk Option 3 22 The ANSI C language is a superset of the de facto C standard defined in the first edition of The C Programming Language K amp R Most programs written for earlier non ANSI C versions of the TMS320C3x C4x C compiler and other non ANSI compilers should correctly compile and run without modification However there are subtle changes in the language that may affect existing code Appendix C in K amp R second edition summarizes the differences be tween ANSI C and the previous C standard called K amp R C To simplify the process of compiling existing C programs with the TMS320C3x C4x ANSI C compiler the compiler has a K amp R option pk that modifies some of the semantic rules of the language for compatibility with older code In general the pk option relaxes requirements that are stricter for ANSI C than for previous C standards The pk option does not disable any new features of the language such as function prototypes enumerations initializations or preprocessor constructs Instead pk simply liberalizes the ANSI rules without revoking any of the features The specific effects of pk are include Lj The integral promotion rules have changed regarding promoting an un signed type to a wider signed type Under K amp R the result type was an unsigned version of the wider type under ANSI the res
30. There are two methods for copying the initialization data into memory RAM and ROM The RAM model of initialization is discussed on page 4 38 the ROM model of initialization is discussed on page 4 39 The tables in the cinit section consist of initialization records with varying sizes Each initialization record has the following format Figure 4 3 Format of Initialization Records in the cinit Section Cinit Section Initialization Record 1 Initialization Record 2 Initialization Record Initialization Record 3 Size in Initialization Bytes in bss Data Initialization Record n The first field word 0 record 1 is the size in words of the initialization data for the variable The second field word 1 record 2 is the starting address of the area in the bss section into which the initialization data must be copied This field points to a variable s space in bss The third field word 2 record 3 through n contains the data that is copied into the variable to initialize it Runtime Environment 4 37 System Initialization The cinit section contains an initialization record for each variable that must be initialized For example suppose two initialized variables are defined in C as follows int i 23 int a 5 Ly 2y By 4 5 The initialization tables would appear as follows sect 1 CINI Initialization section Initialization record for
31. This results in the compiler using the path in the environment variable to find the include file The pathnames specified with C_DIR are directories that contain include files You can separate pathnames with a semicolon or with blanks In C C Compiler Description 2 33 Controlling the Preprocessor 2 2 3 Generating a 2 34 source you can use the include directive without specifying any path infor mation instead you can specify the path information with C_DIR The environment variable remains set until you reboot the system or reset the variable by entering one of these commands Host Enter DOS or OS 2 set C_DIR UNIX unsetenv C_DIR Preprocessed Listing File pl pn po Options The pl shell option allows you to generate a preprocessed version of your source file The compiler s preprocessing functions perform the following actions on the source file Each source line ending in backslash is joined with the following line Trigraph sequences are expanded if enabled with the p option Comments are removed include files are copied into the file Macro definitions are processed and all macros are expanded All other preprocessing directives including line directives and conditional compilation are executed O O O O O O These functions correspond to translation phases 1 3 as specified in Section A12 of K amp R The preprocessed output file contains no preprocessor directives other tha
32. linking refer to Section 2 10 on page 2 65 Runtime Support Libraries 5 1 1 Modifying a Library Function You can inspect or modify library functions by using the archiver to extract the appropriate source file or files from rts src For example the following command extracts two source files ar30 x rts srce atoi c strcpy c To modify a function extract the source as in the previous example Make the required changes to the code recompile and then reinstall the new object file or files into the library c130 options atoi c strcpy c recompile ar30 r rts lib atoi obj strcpy obj rebuild library You can also build a new library this way rather than rebuilding back into rts lib For more information about the archiver refer to Chapter 8 of the TMS320C3x C4x Assembly Language Tools User s Guide 5 1 2 Building a Library With Different Options You can create a new library from rts src by using the library build utility mk30 For example use this command to build an optimized runtime support library for the TMS320C4x using the big memory model and the register argument runtime model mk30 mr v40 mb o2 x rts sre 1 rts40rb lib The u option tells the mk30 utility to use the header files in the current directory rather than extracting them from the source archive The new library is compatible with any code compiled for the C4x v40 using the big memory model mb and the register argument runtime mo
33. potential risk applications should be directed to TI through a local SC sales office In order to minimize risks associated with the customer s applications adequate design and operating safeguards should be provided by the customer to minimize inherent or procedural hazards Tl assumes no liability for applications assistance customer product design software performance or infringement of patents or services described herein Nor does TI warrant or represent that any license either express or implied is granted under any patent right copyright mask work right or other intellectual property right of TI covering or relating to any combination machine or process in which such semiconductor products or services might be or are used Copyright 1998 Texas Instruments Incorporated About This Manual Preface Read This First The TMS320C3x C4x Optimizing C Compiler User s Guide tells you how to use these compiler tools Compiler Source interlist utility Optimizer Preprocessor Library build utility O O O O C This compiler accepts American National Standards Institute ANSI standard C source code and produces assembly language source code for the TMS320C3x 4x devices This user s guide discusses the characteristics of the TMS320C3x 4x opti mizing C compiler lt assumes that you already know how to write C programs The C Programming Language second edition by Brian W Kernighan and Dennis M Ritchie describe
34. short int long float and double are 32 bits Data size long double is 40 bits This allows all types of data to take full advantage of the TMS320C3x C4x integer and floating point arithmetic capabilities For more information refer to Section 3 2 on page 3 4 A library build utility called mk30 allows you to easily custom build object libraries from source for any combination of runtime models or target CPUs Chapter 2 C Compiler Description Translating your source program into code that the TMS320C3x C4x can execute is aprocess consisting of several steps You must compile assemble and link your source files to create an executable object file The TMS320C3x C4x package contains a special cl30 shell program that enables you to execute all of these steps with one command This chapter provides a complete description of how to use the shell program to compile assemble and link your programs The TMS320C3x C4x C compiler includes an optimizer that allows you to pro duce highly optimized code The optimizer is explained in Section 2 4 The compiler package also includes a utility that interlists your original C source statements into the compiler s assembly language output This enables you to inspect the assembly language code generated for each C statement The interlist utility is explained in Section 2 6 This chapter includes the following topics Topic Page 2ecompiling G GOd er ee eee oer E A E reir tre p 2 2 2 Con
35. value using the RND instruction TMS320C3x C4x C Language 3 5 Data Types 3 6 Addition subtraction and negation use assembly instructions when the instructions are able to accept extended precision floating point values as input C3x multiplication uses the runtime support assembly function MPY_LD C4x multiplication uses the MPYF instruction Inversion and reciprocals use the runtime support assembly function INV_LD Division uses the runtime support assembly function DIV_LD Lj The 40 bit runtime support assembly functions are linked into their own section called float40 Keywords 3 3 Keywords 3 3 1 The cregister Keyword The TMS320C3x C4x compiler extends the C language by adding the cregis ter keyword to allow high level language access to control registers When you use the cregister keyword on an object the compiler compares the name of the ojbect to a list of standard control registers for the C3x C4x see Table 3 2 Ifthe name matches the compiler generates the code to reference the control register If the name does not match the compiler issues an error Table 3 2 Valid Control Registers Register Description IE CPU DMS interrupt enable register IF CPU interrupt flag register IOF I O flags ST Status register The cregister keyword can only be used in file scope The cregister keyword is not allowed on any declaration within the boundaries of a function It can only be used on objects
36. COFF object file that contains information about the symbols that are defined and used by the file uninitialized section A COFF section that reserves space in the TMS320 memory map but that has no actual contents These sections are built up with the bss and usect directives union A variable that may hold at different times objects of different types and sizes unsigned A kind of value that is treated as a positive number regardless of its actual sign virtual memory The ability for a program to use more memory than a com puter actually has available as RAM This is accomplished by using a swap file on disk to augment RAM When RAM is not sufficient part of the program is swapped outto a disk file until itis needed again The com bination of the swap file and available RAM is the virtual memory The TMS320C3x C4x tools use a memory extender to provide virtual memory management This memory extender is not provided as an executable but is embedded in several of the object programs word A 32 bit addressable location in target memory Appendix D Summary of Updates in This Document This appendix provides a summary of the updates in this version of the docu ment Updates within paragraphs appear in a bold typeface D 1 Summary of Updates in This Document Page Change or Add 2 6 Add one row msrevx s to the General Shell Option section of Table 2 1 Compiler Options Summary Table 2 6 Add note see also
37. FILE FOR LINKING C30 C PROGRAMS x7 R wy L Usage 1nk30 lt obj files gt o lt out file gt m lt map file gt c30 cmd hei wy Description This file is a sample command file that can be used Ey for linking programs built with the TMS320C30 C xf V Compiler Use it a guideline you may want to change aed F the allocation scheme according to the size of your y program and the memory layout of your target system Xy Lar Notes 1 Be sure to use the right library Use a library that af matches the runtime model you are using ff 2 You must specify the directory in which rts lib is A located Either add a i lt directory gt line to this file or use the system environment variable C_DIR to specify a search path for libraries ays Ef 3 When using the small default memory model be sure X7 that the ENTIRE bss section fits within a single page E To satisfy this bss must be smaller than 64K words and j must not cross any 64K boundaries KK HK KK I I I I IA IA A I IA A IA A A IA A IA A IA A A A I A I Ha Oe c LINK USING C CONVENTIONS A stack 0x400 1K STACK 7 heap 0x400 1K HEAP wy lrts30 lib GET RUN TIME SUPPORT SPECIFY THE SYSTEM MEMORY MAP MEMORY ROM org 0x0 len 0x1000 INTERNAL 4K ROM EXTO org 0x1000 len 0x7ff000 EXTERNAL MEMORY a XBUS org 0x800000 len 0x2000 EXPANSION BUS IOBUS org 0x804000 len
38. For each source archive file specified a cor responding object library file is created An object library cannot be built from multiple source archive files The mk30 utility runs the shell program cl30 on each source file in the archive to either compile or assemble it It then collects all the object files into the out put library All the tools must be in your PATH The utility ignores and disables the environment variables TMP C_OPTION and C_DIR Library Utility Specific Options 6 2 Most of the options that are included on the command line correspond directly to options of the same name used with the compiler and assembler The follow ing options apply only to the library build utility C h k extracts C source files contained in the source archive from the library and leaves them in the current directory after the utility has completed execution instructs mk30 to use header files contained in the source archive and leave them in the current directory after the utility has com pleted execution You will probably want to use this option to install the runtime support header files from the rts src archive that is shipped with the tools instructs the mk30 utility to over write files By default the utility aborts any time it attempts to create an object file when an object file of the same name already exists in the current directory re gardless of whether you specified the name or the utility derived it
39. Instructions 00 0 0 cece cece ene eee A 6 TMS320C4x Specific Features i A 8 Data Flow Optimizations 0 Copy Propagation and Control Flow Simplification ccc eee eens A 13 Loop Unrolling os eo en a E a a a ed A 14 Inline Function Expansion part one 7s A 15 Inline Function Expansion part tWo i A 16 Contents xvii Notes Cautions and Warnings Size Restrictions on Small Model are not Tested i 2 36 All Functions Must Be Prototyped 2 cc2 0scc csetgeshesmwrendestaaenigeebesbercsbends 2 3 Files That Redefine Standard Library Functions i 2 40 Symbolic Debugging and Optimized Code pp 2 41 Function Inlining May Greatly Increase Code Size i 2 44 A TMS320C3x C4x Byte Is 32 Bits 0 keene ete eens 3 5 Avoid Disrupting the C Environment With asm Statements 000 cece eee 3 17 The Linker Defines the Memory Map i 4 2 SLACK OVEN diac E ded ede ENTA EE dane ba eda Cade dene dames 4 4 Avoid Locals and Arguments With Large Offsets Assembler Support for Runtime Models i Use the mf Option When Using the Optimizer pp Avoid Disrupting the C Environment With asm Statements Initializing Variables s asi EE ER Raed Rhode hddar sade eddereadiveaseeaeeees Variable Argument Functions Must Have Prototypes Writing Your Own Clock Function 3 500 80073 am aia aa aea ka aaia a Accessing Objects After Calling the minit Function Writing Your Own Time Function 0 ed cee eee eai ein iai Use Unique Function Names 0 or B 5 xvii
40. RO R7 RO R11 on the TMS320C4x must be saved as complete 40 bit values because they may contain either integers or floating point values when the interrupt occurs For more information about interrupt handling refer to Section 4 6 on page 4 30 Access arguments from the stack or in the designated registers depend ing on which argument passing model is used When calling a C function from assembly language follow the guidelines in subsection 4 4 1 on page 4 16 push the arguments on the stack in reverse order When using the register argument model load the designated registers with arguments and push the remaining arguments on the stack as described in subsection 4 4 2 on page 4 17 When calling C functions remember that only the dedicated registers are preserved C functions can change the contents of any other register Functions must return values correctly according to their C declarations Integers pointers and floating point values are returned in register RO and structures are returned as described in step 4 on page 4 20 No assembly module should use the cinit section for any purpose other than autoinitialization of global variables The C startup routine in boot asm assumes that the cinit section consists entirely of initialization tables Disrupting the tables by putting other information in cinit can cause unpredictable results The compiler appends an underscore _ to the beginning of all identifiers In assem
41. Register Variables and Register Tracking Targeting int gvar reg int i int j gvar call amp i J gvar i return j KKK KK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KK TMS320C30 C COMPILER Version X XX A ac30 mr al c al if opt30 r 02 al if al opt cg30 p al opt al asm al tmp version 30 FP Set AR3 globl _gvar globl _reg KKK KKK KKK KR KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KK X FUNCTION DEF _reg X _reg PUSH R4 R4 assigned to parameter i LDI AR2 R4 CALL _call AND R4 R0 R2 STI R2 _gvar ADDI R4 R2 RO0 EPIO_1 POP R4 RETS globl _gvar SS _gvar 1
42. The compiler builds the constant table at the end of the source module by using the word and float assembler directives Each entry in the table occupies one word The label CONST is the address of the beginning of the table For exam ple CONST word 011223344h 32 bit constant float 3 14159265 floating point word _globvar address of global word SL23 address of string Objects in the table are accessed with direct addressing for example LDI const offset RO Inthis example offset is the index into the constant table of the required object As with string constants identical constants used within a source module share a single entry in the table In the big memory model the constant table is built in the const section and is not copied into RAM The compiler must insure that the DP register is correctly loaded before accessing the object in the table just as with accessing global variables This requires an LDP instruction before each access of the constant table The small model however avoids the overhead of loading the DP by requiring that all directly addressable objects including all global variables as well as the constant table are stored on the same memory page Of course global vari ables must be stored in RAM For the code to be ROM able the constant table Runtime Environment 4 9 Object Representation 4 10 must be in ROM In order to get them on the same page the boot routine must copy the
43. _table_size Set 10000 define the constant global _table_size make it global b C Program extern int table size external ref define TABLE SIZE int amp table_size use cast to hide address of for i 0 i lt TABLE_SIZE i use like normal symbol Because you are referencing only the symbol s value as stored in the symbol table the symbol s declared type is unimportant In Example 4 4 int is used You can reference linker defined symbols in a similar manner Inline Assembly Language Within a C program you can use the asm statement to inject a single line of assembly language into the assembly language file that the compiler creates Interfacing C With Assembly Language A series of asm statements places sequential lines of assembly language into the compiler output with no intervening code The asm statement is provided so that you can access features of the hardware that would be otherwise inaccessible from C For example you can modify the interrupt control registers to enable or disable interrupts You can also access the status interrupt enable and interrupt flag registers Note Avoid Disrupting the C Environment With asm Statements Be extremely careful not to disrupt the C environment with asm statements The compiler does not check the inserted instructions Inserting jumps and labels into C code can cause unpredictable res
44. an error gt gt Cannot open source file mystery c Treating Code E Errors as Warnings pe Option A fatal error is an error that prevents the compiler from generating an output file Normally code E F and errors are fatal while W errors are not fatal The pe shell option causes the compiler to effectively treat code E errors as warnings so that the compiler will generate code for the file despite the error Using pe allows you to bend the rules of the language so be careful As with any warning the compiler may not generate what you expect Note that there is no way to specify recovery from code F or errors these are always fatal and prevent generation of a compiled output file 2 7 2 Suppressing Warning Messages pw Option 2 52 The pw options inform the compiler to quietly ignore or to generate certain code W messages warnings You can suppress all warning messages with the pw0 or pw option This can be useful when you are aware of the condition causing a warning and con sider it innocuous The pw1 option causes the compiler to report serious warning messages This is the default How the Compiler Handles Errors The pw2 option causes the compiler to report all warning messages including messages that report undeclared functions at their point of call 2 7 3 An Example of How You Can Use Error Options The following example demonstrates how the pe and pw options can be use
45. and archiver with the compiler 2 1 Compiling O Code s ceran adaa gaga pai aaa aa aiara aa aaa E ar arae Gad aa Geb daaa ov bade 2 2 2 1 1 Invoking the C Compiler 3 i cece eee eee eee 2 3 2 1 2 Specifying Filenames 7 2 4 21 3 Compiler OPOone neal Padded aei Daata a paaa EEE aes 2 1 4 Using the C_OPTION Environment Variable i 2 28 2 1 5 Using the TMP Environment Variable i 2 28 2 2 Controlling the Preprocessor pp 2 30 2 21 Predefined Names 00 000 eee eee eens 2 31 2 2 2 include File Search Paths i 2 32 2 2 3 Generating a Preprocessed Listing File pl pn po Options 2 34 2 3 Using Runtime Models 0 cece eens 2 3 1 The Big and Small Memory Models i 2 3 2 The Register Argument and Standard Models 2 4 Using the C Compiler Optimizer 00 0 0 ccc eects 2 4 1 Optimization Levels mii 2 4 2 Definition Controlled Inline Expansion Option x Option 2 4 3 Using the Optimizer with the Interlist Option os option 2 4 4 Debugging Optimized Code pp 2 4 5 Special Considerations When Using the Optimizer 250 Functonm IO 2 5 1 Controlling Inline Expansion x Option pp 2 5 2 Automatic Inline Expansion Option oisize Option 2 5 3 INLINE Preprocessor Symbol ss 2 6 Using the Interlist Utility a a ds ead a en xi Contents xii 2 7 2 8 2 9 2 10 2 6 1 Using the Interlist Utility Without the Optimizer
46. as volatile unsigned int ctrl Aliasing occurs when a single object may be accessed in more than one way such as when two pointers point to the same object or when a pointer points to a named object Aliasing can disrupt optimization because any indirect reference could potentially refer to any other object The optimizer analyzes the code to determine where aliasing can and cannot occur then optimizes as much as possible while still preserving the correctness of the program The compiler assumes that if the address of a local variable is passed to a function the function might change the local by writing through the pointer but will not make its address available for use elsewhere after returning For example the called function cannot assign the local s address to a global variable or return it In cases where this assumption is invalid use the ma option in cl30 to force the compiler to assume worst case aliasing In worst case aliasing any indirect reference may refer to such a variable Function Inlining 2 5 Function Inlining When an inline function is called and the optimizer is invoked the code for the function is inserted at the point of the call This is advantageous in short functions for two reasons D It saves the overhead of a function call D Once inlined the optimizer is free to optimize the function in context with the surrounding code Inline expansion is performed one of three ways The intrins
47. call and return discipline E m The jmp_buf type is an array type suitable for holding the information needed to restore a calling environment The setjmp macro saves its calling environment in the jmp_buf argument for later use by the longjmp function If the return is from a direct invocation the setjmp macro returns the value zero If the return is from a call to the longjmp function the setjmp macro returns a nonzero value The longjmp function restores the environment that was saved in the jmp_buf argument by the most recent invocation of the setjmp macro If the setimp macro was not invoked or if it terminated execution irregularly the behavior of longjmp is undefined After longjmp is completed the program execution continues as if the corresponding invocation of setjmp had just returned returnval The longjmp function will not cause setjmp to return a value of zero even if returnval is zero If returnval is zero the setimp macro returns the value 1 These functions are typically used to effect an immediate return from a deeply nested function call include lt setjmp h gt jmp_buf env main int errcode nest42 if errcode setjmp env 0 nest1 else switch errcode if input ERRCODE42 return to setjmp call in main longjmp env ERRCODE42 Syntax Defined in Description Syntax Defined in Description Example Alphabetica
48. call va_start to initialize ap before calling va_arg or va_end include lt stdarg h gt int printf char fmt int i char s va_list ap va_start ap fmt zy i va_arg ap int Get next arg an integer S va_arg ap char Get next arg a string i va_arg ap long Get next arg a long va_end ap Reset ey vfprintf Syntax Defined in Description Syntax Defined in Description Syntax Defined in Description Alphabetical Summary of Runtime Support Functions vfprintf vprintf vsprintf Write to Stream include lt stdio h gt int vfprintf FILE iop const char format va_list ap vfprintf c in rts src Writes to the stream pointed to by iop How to write the stream is described by a string pointed to by format The ap parameter is the argument list Write to Standard Output include lt stdio h gt int vprintf const char format va_list ap vprintf c in rts src Writes to the standard output device How to write the stream is described by a string pointed to by format The ap parameter is the argument list Write Stream include lt stdio h gt int vsprintf char string const char format va_list ap vsprintf c in rts src Writes to the array pointed to by string How to write the stream is described by a string pointed to by format The ap parameter is the argument list Runtime Support Functions 5 79 Chapter 6 Library Build Utili
49. char file const char mode Expands inline if x is used Macro Expands inline unless x0 is used Summary of Runtime Support Functions and Macros Description Breaks value into a normalized fraction and an integer power of 2 Multiplies x by an integer power of 2 Returns the natural logarithm of x Returns the base 10 logarithm of x Breaks value into a signed integer and a signed fraction Returns x raised to the power y Returns the sine of x Returns the hyperbolic sine of x Returns the nonnegative square root of x Returns the tangent of x Returns the hyperbolic tangent of x Description Accesses the next argument of type type in a variable argument list Resets the calling mechanism after using va_arg Initializes ap to point to the first operand in the variable argument list Description Clears the EOF and error indicators for the stream that p points to Flushes the stream that iop points to and closes the file associated with that stream Tests the EOF indicator for the stream that p points to Tests the error indicator for the stream that p points to Flushes the O buffer for the stream that iop points to Reads the next character in the stream that fp points to Stores the object that pos points to to the current value of the file position indicator for the stream that iop points to Reads the next size minus 1 character from the stream that iop points to into array ptr Opens the file
50. divid asm invf asm invf asm invid asm modi asm modi asm modu asm modu asm Registers Used RO R1 ARO AR1 RO R1 ARO AR1 RO R1 R2 R3 BK RC RS RE RC RS RE RO R1 ARO AR1 RC RS RE RO R1 ARO AR1 RC RS RE RO R1 ARO AR1 RO R1 ARO AR1 R10 RO R1 R2 R3 R5 RC BK RO R1 ARO AR1 RO R1 ARO AR1 RO R1 R2 R3 BK RO R1 ARO AR1 RO R1 ARO AR1 RO R1 ARO AR1 RC RS RE RO R1 ARO AR1 RC RS RE Functions Provided for Compatibility With Previous Compiler Versions MPY I MPY_X DIVI DIV_U DIV_F MOD I MOD_U 4 34 Integer multiply Integer multiply for early versions of C30 Integer divide Unsigned integer divide Floating point divide Integer modulo Unsigned integer modulo arith410 asm arith410 asm arith410 asm arith410 asm arith410 asm arith410 asm arith410 asm RO R3 RO R3 RO R3 RC RS RE RO R3 RC RS RE RO R3 RO R3 RC RS RE RO R3 RC RS RE Runtime Support Arithmetic Routines 4 7 1 Precision Considerations The compiler will replace costly mathematical operations with narrower precision equivalents if the containing expression does not require the use of high precision functions For example on the C3x if the outermost operation causes the precision of the entire expression to be limited to 24 bits or less all multiplies within the expression will be performed with the MPYI instruction instead of with the MPY_130 funct
51. down time The adjustment from local time to GMT is dependent on the local time zone The current time zone is represented by a structure called _ tz of type struct tmzone defined in tmzone c Change this structure for the appropriate time zone For more information about the functions and types that the time h header de clares refer to subsection 5 2 13 page 5 11 Syntax Defined in Description Alphabetical Summary of Runtime Support Functions iSXXX Character Typing include lt ctype h gt int isalnum char c int islower char c int isalpha char c int isprint char c int isascii char c int ispunct char c int iscntrl char c int isspace char c int isdigit char c int isupper char c int isgraph char c int isxdigit char c isxxx c and ctype c in rts src Also defined in ctype h as macros These functions test a single argument c to see if it is a particular type of char acter alphabetic alphanumeric numeric ASCII etc If the test is true the character is the type of character that it was tested to be the function returns a nonzero value if the test is false the function returns 0 All of the character typing functions are expanded inline if the x option is used The character typing functions include isalnum identifies alphanumeric ASCII characters tests for any character for which isalpha or isdigit is true isalpha identifies alphabetic ASCII characters tests for any charac
52. expressions into equivalent forms requiring fewer instructions or registers For example the expression a b c d requires 5 instructions and 2 registers to evaluate it can be optimized to a b c d which takes only 4 instructions and 1 register Operations between constants are folded into single constants For example a b 4 c 1 becomes a b c 3 See Example A 5 Alias disambiguation Programs written in the C language generally use many pointer variables Frequently compilers are unable to determine whether or not two or more lowercase L values symbols pointer references or structure references refer to the same memory location This aliasing of memory locations often prevents the compiler from retaining values in registers because it cannot be sure that the register and memory continue to hold the same values over time Alias disambiguation is a technique that determines when two pointer expres sions cannot point to the same location allowing the compiler to optimize such expressions Description of Compiler Optimizations A 9 Description of Compiler Optimizations Data flow optimizations A 10 Collectively the following three data flow optimizations replace expressions with less costly ones detect and remove unnecessary assignments and avoid operations that produce values already computed The optimizer performs these data flow optimizations both locally within basic blocks and glob
53. file produce a verbose information file specify that callable functions and or modifiable variables are used in this module specify that no callable functions are used in this module default specify that no modifiable variables or callable functions are used in this module specify that no modifiable variables are used in this module but modifi able functions may be used interlist optimizer comments with as sembly source statements allow zero overhead loop operations C Compiler Description 2 11 Compiling C Code General Shell Options You can use the options described below to control the overall operation of the cl30 shell filename read shell options and commands from a command file The commands can be on one line or on several lines Comments in the command file can begin with a semicolon or a pound character and end at the end of a line or can begin with the characters and end with Options in addition to those specified in the command file can be specified on the command line or with the C_OPTION environment variable C Suppresses the linking option it causes the shell notto run the linker even if z is specified This option is especially useful when you have z specified in the C_OPTION environment variable and you don t want to link For more information refer to page 2 67 dnamel def _ predefines the constant name for the preprocessor This is equivalent to inse
54. for assembly language files and object files This affects the interpretation of source filenames as well as the naming of files that the shell creates The syntax for the e option is eal new extension for assembly language files eo new extension for object files For example cl130 ea rrr eo odsp fit rrr assembles the file fit rrr and creates an object file named fit odsp The in the extension and the space between the option and the extension are optional The example above could be written as cl130 earrr eoodsp fit rrr The e option should precede any filenames on the com mand line If you don t use the e option the default extensions are asm for assembly files and obj for object files Compiling C Code overrides default interpretations for source file extensions If your naming conventions do not conform to those of the shell you can use f options to specify which files are C source files assembly files or object files You can insert an optional space between the f option and the filename The f options are fafile for assembly source file fcfile for C source file fofile for object file For example if you have aC source file called file s and an assembly file called asmbly asm use f to force the correct interpretation c130 fcfile s fa asmbly Note that f cannot be applied to a wildcard specification permits you to specify a directory f
55. function v compiler option v library build utility option v0 linker option va_arg function va_end function va_start function variable argument functions and macros 5 8 5 15 variable argument function variable argument functions and macros va_arg va_end va_start 5 78 viprintf function volatile 2 41 vprintf function vsprintf function w linker option warning messages suppressing warnings messages wildcard write block of data function write functions WRITE I O function B 10 Index x compiler option x inlining option x linker option z code generator option z compiler option overriding Index 13
56. function 4 4 Bs 5 51 malloc16 function malloc8 function memcmp function memcpy function memory pool 5 29 reserved space MEMORY _SIZE MEMORY_SIZE constant 4 4 memset function 5 50 mf compiler option mi compiler option 2 21 minit function minit16 function minit8 function mk30 6 2 mktime function ml compiler option mm compiler option mn compiler option modf function 5 53 modular programming mp compiler option mr compiler option ms compiler option mt compiler option mtc compiler option multibyte characters Index 7 Index N inline function expansion loop induction variable optimizations A 14 n compiler option loop invariant code motion A 15 n linker option loop rotation A 19 natural logarithm redundant assignment elimination A 10 strength reduction NDEBUG macro symbolic simplification non local jumps information file options NULL macro library functions options TMS320C30 specific O oe addressing calls cost based register allocation A 4 0 extension delayed branches A 6 o linker option es pee pees Obj extension returns object libraries optimizer offsetof macro 5 9 invoking oi compiler option 2 26 options 2 60 ne parser output 2 59 oi optimizer option Special considerations 2 41 ol compiler option using
57. include lt math h gt double tan double x tan c in rts src The tan function returns the tangent of a floating point number x x is an angle expressed in radians An argument with a large magnitude may produce a re sult with little or no significance double x y x yY 3 1415927 4 0 tan x return value 1 0 Hyperbolic Tangent include lt math h gt double tanh double x tanh c in rts src The tanh function returns the hyperbolic tangent of a floating point number x double x y 0 0 tanh x return value 0 0 x y Runtime Support Functions 5 75 time tmpfile tmpnam toascii Syntax Defined in Description Syntax Defined in Description Syntax Defined in Description Syntax Defined in Description Alphabetical Summary of Runtime Support Functions Time include lt time h gt time_t time time_t timer time c in rts src The time function determines the current calendar time represented as a val ue of type time_t The value is the number of seconds since 12 00 A M Jan 1 1900 If the calendar time is not available the function returns 1 If timer is not anull pointer the function also assigns the return value to the object that timer points to For more information about the functions and types that the time h header de clares refer to subsection 5 2 13 page 5 11 Fr rr Note Writing Your Own Time Function The time function is target syste
58. inserting define name def at the top of each source file If the optional def is omitted adname sets name equal to 1 al invokes the assembler with the lowercase L option to produce an assembly listing file as retains labels Label definitions are written to the COFF symbol table for use with symbolic debugging auname undefines the predefined constant name Overrides any ad options for the specified constant aX invokes the assembler with the x option to produce a symbolic cross reference in the listing file For more information about assembler options see the TMS320C3x C4x Assembly Language Tools User s Guide Linker options can be used with the compiler or with the linker as a standalone See Section 2 10 2 Linking C Code on page 2 66 When used with the compiler shell all linker options should follow the z option described in General Options on page 2 12 For example cl30 q symtab c z a c o symtab out 1 rts30 lib In this example the file symtab c will be compiled with the q quiet option The z option causes the shell to invoke the linker and pass the a c o and linker options to the linker All compiler command line options following z are passed to the linker For this reason the z option followed by the linker options must be the last shell option specified on the command line All options on the command line follow ing the z option will be passed to
59. instructs mk30 to suppress header information quiet Invoking the Library Build Utility U instructs mk30 not to use the header files contained in the source archive when building the object library If the desired headers are already in the current directory there is no reason to reinstall them This option also gives you some flexibility in modifying runtime support functions to suit your application V prints progress information to the screen during execution of the utility Normally the utility operates silently no screen messages Example The following command builds the standard runtime support library as an object library named rts40r lib The library is compiled for the TMS320C4x v40 optimized with inline function expansion x and o and uses the register argument runtime conventions The example assumes that the runtime support headers already exist in the current directory u mk30 u v40 o x mr rts sre I rts40r lib Library Build Utility 6 3 Options Summary 6 2 Options Summary Options for the mk30 utility correspond directly to the options that the compiler uses These options are described in detail in subsection 2 1 3 on page 2 5 General Options 9 VXX Parser Options pk pw p Optimizer Options 00 01 02 or 0 03 ox equivalent to x2 Inlining Options x1 x2 or x Runtime Model Options Effect symbolic debugging
60. is discarded effectively rounding towards zero The compiler uses the TMS320C3x C4x FIX instruction for these conversions which rounds toward negative infinity followed by a four instruction sequence to correct negative values If the ANSI standard behavior is not important to your application the mc option suppresses the correction sequence for faster execution Compiling C Code forces the compiler to always honor indirection on external objects The compiler allows objects not declared in the bss section to be accessed indirectly via pointers as described in subsection 4 5 2 on page 4 25 Such objects cannot be accessed directly because they are not on the data page addressed by the DP In some cases the opti mizer may convert such indirect accesses into direct accesses possibly resulting in objects in the bss being accessed incorrectly For example extern struct sss ext_obj object not in bss struct sss ext_ptr amp ext_obj object pointer The optimizer may convert an expression such as structure member ext_ptr gt f1 to ext_obj f1 because the optimizer assumes that all variables are in the bss section This transformation is invalid if ext_obj is not in the bss section The mf option inhibits the transformation and preserves the indirection disables the use of RPTS instructions for loops and uses RPTB instead This allows loops to be interrupted runtime support assembly calls use far calls Wi
61. is too large double x y QD x y sinh x return value 0 0 Write Stream include lt stdio h gt int sprintf char string const char format sprintf c in rts src Writes to the array pointed to by string How to write the stream is described by a string pointed to by format Square Root include lt math h gt double sqrt double x sqrt30 asm in rts src The sqrt function returns the non negative square root of a real number x A domain error occurs if the argument is negative double x y 100 0 sqrt x x y return value 10 0 Syntax Defined in Description Syntax Defined in Description Example Alphabetical Summary of Runtime Support Functions sscanf strcat Read Stream include lt stdio h gt int sscanf const char str const char format sscanf c in rts src Reads from the string pointed to by str How to read the stream is described by a string pointed to by format Concatenate Strings include lt string h gt char sircat char s1 char s2 strcat c in rts src The strcat function appends a copy of s2 including the terminating null character to the end of s1 The initial character of s2 overwrites the null char acter that originally terminated s1 The function returns the value of s1 The strcat function is expanded inline if the x option is used In the following example the character strings pointed to by a b and c were assi
62. it wasn t me char strb wave char a a strpbrk stra strb After this example a points to the w in wasn t Find Last Occurrence of a Character include lt string h gt char strrchr char s int c strrchr c in rts src The strrehr function finds the last occurrence ofc ins If strrchr finds the char acter it returns a pointer to the character otherwise it returns a null pointer 0 The strrchr function is expanded inline if the x option is used char a When zz comes home the search is on for z s char b char the_z 2z b strrchr a the_Z After this example b points to the z in zs near the end of the string Runtime Support Functions 5 71 strspn strstr Alphabetical Summary of Runtime Support Functions Syntax Defined in Description Example Syntax Defined in Description Example 5 72 Find Number of Matching Characters include lt string h gt size_t strspn int s1 int s2 strspn c in rts src The strspn function returns the length of the initial segment of s1 which is entirely made up of characters in s2 If the first character of s1 is notin s2 the strspn function returns 0 char stra who is there char strb abcdefghijklmnopqrstuvwxyz char strc abcdefg size_t length length strespn stra strb length 3 length strcspn stra strc length 0 Find Matching String include lt
63. least significant bit to MSB in the order in which they are declared Noobjecthas any type of alignment requirement any object can be stored on any 32 bit word boundary Objects that are members of structures or arrays are stored just as they are individually Members are not packed into structures or arrays unless the members are bit fields The integer types char short int and long are all equivalent as are their unsigned counterparts Objects of type enum are also represented as 32 bit words The floatand double types are equivalent both types specify objects rep resented in the TMS320C3x C4x 32 bit floating point format The ong doubletype is represented in the TMS320C3x C4x 40 bit format For more information on data types refer to Section 3 2 Data Types on page 3 4 4 2 2 Long Immediate Values The TMS320C3x C4x instruction set has no immediate operands that are longer than 16 bits The compiler occasionally needs to use constants that are too long to be immediate operands This occurs with signed integer constants that have more than 15 significant nonsign bits with unsigned integers that have more than 16 significant bits or with floating point constants that have more than 11 significant nonsign bits in the mantissa 4 2 3 Addressing Global Variables The compiler generates the addresses of global and static symbols for index ing arrays or manipulating pointers Because these addresses may be
64. messages default enable all warning messages names the output file created when using the pm option C Compiler Description 2 7 Compiling C Code Table 2 1 Compiler Options Summary Table Continued These options control the p preprocessing syntax checking and error handling behavior of the compiler For more information see page enable trigraph expansion 2 16 Inlining Options Options Effect These options control ex x0 disable inlining Reece o iunelions ge x1 default inlining level clared as inline For more information refer to X2 define _INLINE invoke optimizer at page 2 18 Type Checking Options Option These options allow tf relaxation of compiler tyne checking rules For more information referto tp page 2 19 level 2 Effect relax prototype checking relax pointer combination checking Table 2 1 Compiler Options Summary Table Continued Runtime Model Options These options are used to customize the executable outut of the comniler for your specific application For more information see page 2 20 Assembler Options These options control the assembler s behavior For more information see page 2 23 Options mtc Options aa adname def al as auname ax Compiling C Code Effect assume aliased variables select big memory configuration use faster float to int conversions force indirect access to e
65. of object modules Eight object libraries are shipped with the C compiler These libraries contain ANSI standard runtime support functions and compiler utility functions for the TMS320C3x and TMS320C4x See Section 2 3 for a de scription of these libraries Use the library build utility mk30 to build your own customized runtime support library Standard runtime support library functions are provided as source code m rts src contains standard runtime functions for the TMS320C3x C4x processors E mathasm src contains assembly language source for trigonometric functions prts30 src contains C and assembly language routines for handling peripherals interrupts for C3x devices Introduction 1 3 Software Development Tools Overview prts40 src contains C and assembly language routines for handling peripherals and interrupts for C4x devices The hex conversion utility hex30 converts a COFF object file into ASCll hex Intel Motorola S Tl Tagged or Tektronix object format The converted file can be downloaded to an EPROM programmer The TMS320C3x C4x Assembly Language Tools User s Guide explains how to use the hex conversion utility The main purpose of this development process is to produce a module that can be executed in a TMS320C3x C4x target system You can use one of several debugging tools to refine and correct your code before downloading it to a TMS320C3x C4x target system These debugging platforms share acom
66. opt cg30 v40 a6 opt a6 asm a6 tmp version 40 FP Set AR3 globl _fsm FUNCTION DEF _fsm _fsm AR2 assigned to variable input LDI AR2 R0 BNZ L4 L2 LDI AR2 RO BZ L4 LDI AR2 RO BZ L2 L4 LDI AR2 RO BZ L4 EPIO_1 RETS end Loop induction variable optimizations strength reduction Loop induction variables are variables whose value within a loop is directly related to the number of executions of the loop Array indices and control vari ables of for loops are very often induction variables Strength reduction is the process of replacing costly expressions involving induction variables with more efficient expressions For example code that indexes into a sequence of array elements is replaced with code that increments a pointer through the array Loops controlled by incrementing a counter are written as TMS320C3x C4x repeat blocks or by usi
67. or declared as inline The x options control the inlining of functions declared as inline lowercase L controls file level optimizations When you invoke the optimizer at level 3 03 it makes use of known properties of the standard library functions If the file you are compiling redefines any of the standard functions the compiler may produce incorrect code Use the oln options to notify the optimizer if any of the following situations exist ol0 Use this option if the file you are compiling alters a standard library function For example if you have de fined a function with the same name as a standard library function or you have altered the source code of a standard library function use olo to inform the opti mizer not to assume the known properties of the stan dard library function ol1 Use this option if the file you are compiling con tains unaltered definitions for standard library functions For example use ol1 to compile the standard library D ol2 Use this option to restore the default behavior of the optimizer after you have used one of the other two options in a command file an environment variable etc Following the ol2 option the optimizer will use known properties of the standard library functions onn opn Compiling C Code causes the compiler to produce a user readable optimization information file with a nfo extension This option works only when the 03 option is
68. pointed to by ptr that was pre viously allocated by a malloc calloc or realloc call This makes the memory space available again If you attempt to free unallocated space the function takes no action and returns For the TMS320C22 processor 8 bit and 16 bit versions of the free function are provided The functions free8 and free16 are analogous to the 32 bit version For more information refer to subsection 4 1 3 Dynamic Memory Allocation on page 4 4 This example allocates 10 bytes and then frees them char x x malloc 10 allocate 10 bytes free x free 10 bytes Open File include lt stdio h gt FILE freopen const char file const char mode register FILE iop fopen c in rts src Opens the file pointed to by file and associates with it the stream pointed to by iop How to open the file is described by a string pointed to by mode Runtime Support Functions 5 41 frexp fscanf fseek Syntax Defined in Description Example Syntax Defined in Description Syntax Defined in Description 5 42 Alphabetical Summary of Runtime Support Functions Fraction and Exponent include lt math h gt double frexp double value int exp frexp30 asm in rts src The frexp function breaks a floating point number into a normalized fraction and an integer power of 2 The function returns a number x with a magnitude in the range 1 2 1 or 0 so that value xx 2 XP The frexp func
69. points to with the object that s1 points to The function returns one of the follow ing values lt 0 if s1 is less than s2 0 if s1 is equal to s2 gt 0 if s1 is greater than s2 The memcmp function is similar to strncmp except that the objects that memcmp compares can contain values of 0 The memcmp function is expand ed inline when the x option is used Memory Block Copy Nonoverlapping include lt string h gt void memcpy void s1 void s2 size_t n memcpy c in rts src The memcpy function copies n characters from the object that s2 points to into the object that s1 points to f you attempt to copy characters of overlapping objects the function s behavior is undefined The function returns the value of si The memcpy function is similar to strncpy except thatthe objects that memcpy copies can contain values of 0 The memcpy function is expanded inline when the x option is used Runtime Support Functions 5 49 memmove memset Alphabetical Summary of Runtime Support Functions memmove Syntax Defined in Description Syntax Defined in Description Memory Block Copy Overlapping include lt string h gt void memmove void s1 void s2 size_t n memmove c in rts src The memmove function moves n characters from the object that s2 points to into the object that s1 points to the function returns the value of s1 The memmove function correctly copies characters between overlappi
70. program data is larger than the offset allowed 32K from the DP For example ldiu cll aro sti ro aro where cl1 in the bss holds the address of the variable Summary of Updates in This Document By default the compiler generates small memory model code which means that every data object is handled as if it were declared near unless it is actually declared far If an object is declared near it is normally loaded using relative offset addressing from the data page pointer DP which is B14 DP points to the beginning of the bss section If the options ml mb or mf are used the default assumptions change See those options for how their usage changes the defaults of the standard memory model If you use the DATA_SECTION pragma the object is indicated as a far vari able and this cannot be overridden This ensures access to the variable since the variable might not be on the same data page as the bss section See sec tion 3 5 2 The DATA_SECTION pragma on page 3 13 Near and far function calls Function calls can be invoked in one of two ways near keyword The compiler assumes that the destination of the call is within 224 bytes of the caller Here the compiler uses the PC relative call instruction call _func far keyword The compiler is told by the user that the call is not within 224 bytes of the caller and the compiler uses the register ad dressing mode of the call instruction ldiu cll ro callu ro
71. runtime model Assembly Language Modules Interfacing with assembly language functions is straightforward if you follow the calling conventions defined in Section 4 4 and the register conventions defined in Section 4 3 C code can access variables and call functions defined in assembly language and assembly code can access C variables and call C functions Follow these guidelines to interface assembly language and C DD All functions whether they are written in C or assembly language must follow the conventions outlined in Section 4 3 page 4 11 You must preserve any dedicated registers modified by a function You must preserve the DP in the small model only These are the dedicated registers Save as integers Save as floating point R4 RS R6 R7 AR4 AR5 AR6 AR7 FP DP small model only SP R8 C4x only Interfacing C With Assembly Language All registers are saved as integers except R6 and R7 which are saved as floating point values If the SP is used normally it does not need to be explicitly preserved In other words the assembly function is free to use the stack as long as anything that is pushed is popped back off before the function returns thus preserving SP All other registers such as expression registers index registers status registers and block repeat registers are not dedicated and can be used freely without first being saved Interrupt routines must save the registers they use Registers
72. sections from differ ent modules and combines sections having the same name to create the output sections You can place these output sections anywhere in the address space as needed to meet system requirements The text cinit const and data sections can be linked into either ROM or RAM The bss stack and sysmem sections should be linked into some type of RAM Note however that the bss and const sections must be allocated in the same 64K data page for a small model see page 4 5 For more information about allocating sections into memory see the TMS320C3x C4x Assembly Language Tools User s Guide 4 1 2 C System Stack The C compiler uses a software stack to Save function return addresses Allocate local variables Pass arguments to functions Save temporary results Save registers Save the processor status O O O O O Runtime Environment 4 3 Memory Model The runtime stack grows up from low addresses to higher addresses The compiler uses two auxiliary registers to manage this stack SP is the stack pointer SP it points to the current top of the stack AR3 _ is the frame pointer FP it points to the beginning of the current frame Each function invocation creates a new frame at the top of the stack from which local and temporary variables are allocated The C environment manipulates these registers automatically If you write any assembly language routines that use the runtime stack be sure to u
73. srra ngata biaen sa a AN a a 4 2 2 Long Immediate Values pp 4 2 3 Addressing Global Variables pp 4 2 4 Character String Constants 000 eect eens 4 2 5 The Constant Table i 4 3 Register Conventions 0 4 3 1 Register Variables 0 si Seti ie ED 4 3 2 Expression Registers andar eect eens 4 3 8 Return Values si 4 3 4 Stack and Frame Pointers et 4 3 5 Other Registers saua uar ha anaa a aaa a da a d eee eens 4 4 Function Structure and Calling Conventions i 4 4 1 Function Call Standard Runtlme Model 0 0 0 c eee eee eae 4 4 2 Function Call Register Argument Runtime Model 4 4 3 Responsibilities of a Called Function ot 4 4 4 Accessing Arguments and Local Variables i 4 5 Interfacing C With Assembly Language pp 4 5 1 Assembly Language Modules i 4 5 2 Accessing Assembly Language Variables From C 4 5 3 Inline Assembly Language 0 0 cece eee 4 6 InterruptHandling Sous vers di a urie eens 4 6 1 Saving Registers During Interrupts pp 4 6 2 Assembly Language Interrupt Routines i 4 7 Runtime Support Arithmetic Routines 0c eee eee 4 7 1 Precision Considerations i 4 8 System Initialization mie ete eee eens 4 8 1 Autoinitialization of Variables and Constants i 5 Runtime Support Functions 00 0c eee eee eee eee Describes the header files included with the C compiler as well as the macros functions and types they declare Summarizes the runtime support functions according to category heade
74. symbol regardless of the use of h make all global symbols static set heap size words set heap size words for 8 bit memory C32 set heap size words for 16 bit memory C32 define library search path supply library name name the map file ignore all fill specifications in memory directives name the output file suppress banner and progress infor mation generate relocatable output strip symbol table set stack size bytes undefine entry point generates version val COFF generate warning if output section is created that was not specified with SECTIONS directive force rereading of libraries Table 2 1 Compiler Options Summary Table Continued Compiling C Code Optimizer Options These options control the behavior of the optimizer For more information see page 2 26 Options 00 01 oisize ol0 oL0 ol1 oL1 ol2 oL2 on0 on1 on2 op0 op1 op2 op3 Effect perform level 0 register optimization perform level 1 level 0 local optimization perform level 2 level 1 global optimization perform level 3 level 2 file optimization set automatic inlining size 03 only specify that this file alters a standard library function specify that this file defines a standard library function specify that this file does not define or alter library functions disable optimizer information file produce optimizer information
75. target application system the TMS320C3x C4x C compiler itself does not preinitial ize variables therefore it is up to your application to fulfill this requirement If your loader does not preinitialize variables you can use the linker to preinitialize the variables to 0 in the object file In the linker command file use a fill value of 0 in the bss section SECTIONS Because the linker writes a complete load image of the zeroed bss section into the output COFF file this method may have the unwanted effect of significantly increasing the size of the output file Initializing Static and Global Variables With the const Type Qualifier Static and global variables with the type qualifier const are initialized differently than other types of static and global variables const static and global variables without explicit initializations may or may not not be preinitialized to zero for the same reasons discussed in Section 3 7 For example const int zero may not be initialized to zero All constants that initialize global variables with or without the const qualifier will be placed in the cinit section All constants contained in expressions or that initialize local variables with or without the const qualifier will either be placed in the CONST table or will be loaded with immediate addressing Values initialized with the const qualifier are not placed in the const section because the values must be accessed with direc
76. that have specific functions are discussed below m The data page pointer DP is used to access global and static variables In the small model the DP is set at program startup and never changed Ifthe DP is modified by an assembly language function in the small model the function must preserve the value Index registers IRO and IR1 are used for array indexing and when an offset of more than 8 bits 255 words is required for indirect addressing In addition the compiler can use both for a general purpose integer register variable if itis not needed for other purposes Neither register is preserved across calls The BK register is used by the compiler as an integer register variable Its value is not preserved across calls The compiler uses block repeat registers RC RE and RS to generate efficient block copy operations for assigning large gt 5 words structures These registers can be used for integer register variables if not being used for block copy operations The repeat register values are not preserved across calls therefore no calls can be made inside of a loop structured with RPTB or RPTS instructions Function Structure and Calling Conventions 4 4 Function Structure and Calling Conventions The C compiler imposes a strict set of rules on function calls Except for special runtime support functions any function that calls or is called by a C function must follow these rules Failure to adhere to these rules can
77. the x x1 or x2 option is used together with the o option at any level the optimizer will be invoked at the level specified by o rather than at the level specified by x 2 5 2 Automatic Inline Expansion Option oisize Option The optimizer will automatically inline all small functions not defined or de clared with the inline keyword when invoked at level 3 A command line option controls the size of functions inlined when the optimizer is invoked at level 3 The oi option can be used three ways If you set the size parameter to zero oi0 all size controlled inlining is disabled If you do not use the oi option the optimizer inlines very small functions C Compiler Description 2 45 Function Inlining Ifyou set the size parameter to a nonzero integer the optimizer will inline all functions whose size is less than the size parameter If the function is called more than once the optimizer multiplies the size of the function by the number of calls and will inline the function only if the resulting product is less than the size parameter The optimizer measures the size of a function in arbitrary units The optimizer information file created with the on1 or on2 option however will report the size of each function in the same units that the oi option uses 2 5 3 _INLINE Preprocessor Symbol 2 46 _INLINE is a preprocessor symbol that is defined and set to 1 if the parser
78. the x option is used char stra who is there char strb abcdefghijklmnopaqrstuvwxyz char strc abcdefg size_t length length strlen stra length 13 length strlen strb length 26 length strlen strc length 7 Runtime Support Functions 5 67 strncat Alphabetical Summary of Runtime Support Functions Syntax Defined in Description Example 5 68 Concatenate Strings include lt string h gt char strncat char s1 char s2 size_t n strncat c in rts src The strncat function appends up to n characters of s2 including the terminat ing null character to the end of s1 The initial character of s2 overwrites the null character that originally terminated s1 strncat appends a null character to the result The function returns the value of s1 In the following example the character strings pointed to by a b and c were assigned the values shown in the comments In the comments the notation O represents the null character char a xD c size_t size 13 a gt I do not like them 0 b gt Sam I am 0 5 c gt I do not like green eggs and ham 0 strncat a b size a gt I do not like them Sam I am 0 strncat a c size a gt I do not like them Sam I am I do not like 0O Syntax Defined in Description Example Alphabetical Summary of Runtime Support Function
79. the address load The compiler is required to make calls to certain runtime support assembly functions to accomplish various initialization and arithmetic tasks These functions are listed in Table 4 3 on page 4 19 The shell s ml option page 2 21 can be used to cause the compiler to generate far calls to these func tions Using far calls in this way may be appropriate if for example functions that call the runtime support functions are separated from them by offsets of greater than 16 bits To make far calls to other runtime support functions you must extract the source files from the rts src file add the far keyword to the desired functions and then recompile the library The library build utility described in Section 6 1 allows you to extract source files and recompile the library It is important to add the far keyword to the function prototypes in the appropri ate include files to ensure far call generation in the source files Delay Slot Filling for Branches 3 9 Delay Slot Filling for Branches The compiler includes support for filling the three delay slots generated by the TMS320C3x C4x for branches The compiler handles unconditional branches by first trying to fill the delay slots with instructions located before the branch It will then try to move up in structions from the destination block Almost any type of instruction can be moved except for those that modify the PC Conditional branches are handled a lit
80. the linker and not the compiler C Compiler Description 2 23 Compiling C Code 2 24 The c and n options suppress the linker option and cause the shell not to run the linker even if z has been specified see General Shell Options page 2 12 for more information Linker options are summarized in Table 2 1 Options Summary Table beginning on page 2 6 For more information about linker options refer to Section 2 10 page 2 65 For more information on the linker see Chapter 8 of The TMS320C3x C4x Assembly Language Tools User s Guide a CT e global_symbol f fill_value g global_symbol h heap size heap8 size heap16 size produces an absolute executable module This is the default if neither a nor r is specified the linker acts as if a is specified produces a relocatable executable object module disables merging of symbolic debugging information enables linking conventions defined by the ROM auto initialization model of the TMS320C3x 4x C compiler This is the default initialization method enables linking conventions defined by the RAM auto initialization model of the TMS320C23x 4x C compiler defines a global_symbol that specifies the primary entry point for the output module sets the default fill value for holes within output sec tions fill_value is a 16 bit constant instructs the linker to maintain the specified symbol as global regardless of
81. the runtime support library and must be linked with the other C object modules This occurs automatically when you use the c or cr option in the linker and include a runtime support library created from rts src as one of the linker input files When C programs are linked the linker sets the entry point value in the executable output module to the symbol c_int00 The c_int00 function performs the following tasks in order to initialize the C environment D Defines a section called stack for the system stack and sets up the initial stack and frame pointers Autoinitializes global variables by copying the data from the initialization tables in cinit to the storage allocated for the variables in bss In the small model the constant tables are also copied from cinit to bss Note this does not refer to data in the const section In the RAM initialization model a loader performs this step before the program runs it is not performed by the boot routine For more information refer to subsection 4 8 1 Small memory model only sets up the page pointer DP to point to the global storage page in bss J Calls the function main to begin running the C program You can replace or modify the boot routine to meet your system requirements However the boot routine must perform the four operations listed above in order to correctly initialize the C environment The runtime support source library contains the source to this rout
82. the use of the h option makes all global symbols static sets heap size for the dynamic memory allocation in C to size words and defines a global symbol that spec ifies the heap size Default 1K words creates the C32 8 bit memory heap and sets heap size to size words and defines a global symbol that speci fies the heap size Default 1K words when needed creates the C32 16 bit memory heap and sets heap size to size words and defines a global symbol that specifies the heap size Default 1K words when needed i dir filename m filename n o filename S stack size u symbol vn W X Compiling C Code alters the library search algorithm to look in dir before looking in the default location This option must appear before the I option The directory must follow operat ing system conventions names an archive library file as linker input filename is an archive library name and must follow operating system conventions produces a map or listing of the input and output sections including holes and places the listing in file name The filename must follow operating system con ventions instructs the linker to ignore all fill specifications in memory directives names the executable output module The default file name is a out and must follow operating system con ventions suppresses banner and progress information retains relocation entries in the
83. up to 32 bits wide and immediate operands are limited to 16 bits these addresses are treated like long constants Subsection 4 2 5 on page 4 9 describes the structure of the constant table Runtime Environment 4 7 Object Representation 4 2 4 Character String Constants In C a character string constant can be used in either of two ways m It can initialize an array of characters for example char s abc When astring is used as an initializer it is simply treated as an initialized array each character is a separate initializer For more information about initialization refer to Section 4 8 System Initialization on page 4 36 It can be used in an expression for example stropy Sy abc When a string is used in an expression the string itself is defined in the const section with the byte assembler directive along with a unique label that points to the string the terminating 0 byte is also included In the following example the label SL5 points to the string from the example above const SL5 Byte abc 0 String labels have the form SLn n being a number assigned by the compiler to make the label unique These numbers begin at 0 with an increase of 1 for each string defined All strings used in a source module are defined at the end of the compiled assembly language module The label SLn represents the address of the string constant The compiler uses this label to reference the string in the
84. usage and thereby safely use additional registers not listed in Table 4 2 4 3 2 Expression Registers 4 12 The compiler uses registers not being used for register variables to evaluate expressions and store temporary results The code generator keeps track of Register Conventions the current contents of the registers and attempts to allocate registers for expressions in a way that preserves the useful contents in the registers whenever possible This allows the compiler to reuse register data to take advantage of the TMS320C3x C4x s efficient register addressing modes and to avoid unnecessary accesses of variables and constants The contents of the expression registers are not preserved across function calls Any register that is being used for temporary storage when a call occurs is saved to the local frame before the function is called This prevents the called function from ever having to save and restore expression registers If the compiler needs another register for storing an expression evaluation a register that is being used for temporary storage can be saved on the local frame and used for the expression analysis 4 3 3 Return Values In general when a value of any scalar type integer pointer or floating point is returned from a function the value is placed in register RO when the function returns However in the register argument calling convention used for runtime support assembly files pointers are return
85. use the register name directly See TMS320C3x C4x CPU and Instruction Set Reference Guide for detailed information on the control registers Summary of Updates in This Document D 3 Summary of Updates in This Document Example 3 1 Define and Use Control Registers extern cregisger volatile unsigned extern cregister volatile unsigned extern cregisger volatile unsigned xtern cregister volatile unsigned unsigned myfunc unsigned int mask while ST amp mask 0 Do nothing wait return IOF 3 3 2 The near and far Keywords The C3x C4x C compiler extends the C language with the near and far key words to specify how global and static variables are accessed and how func tions are called Syntactically the near and far keywords are treated as storage class modifiers They can appear before after or in between the storage class specifiers and types Two storage class modifiers cannot be used together in a single decla ration For example the following are legal uses far static int x static near int x static int far x far int foo static far int foo Near and far data objects Global and static data objects can be accessed in the following two ways near keyword The compiler assumes that the data item can be accessed relative to the data page pointer For example sti ro _var far keyword The compiler cannot access the data item via the dp This can be required if the total amount of
86. way to invoke the optimizer is to use the cl30 shell program specifying the o option on the cl30 command line you may also invoke the optimizer outside cl30 refer to Section 2 9 on page 2 56 for more information The o option may be followed by a digit specifying the level of optimization If you do not specify a level digit the default is level 2 For example to invoke the compiler using full optimization with inline function expansion enter c130 o3 x function c Figure 2 2 illustrates the execution flow of the compiler with standalone optimization Figure 2 2 Compiling a C Program with the Optimizer Code Generator C Source Parser Optimizer File c if File Opt File asm File The optimizer also recognizes cl30 options s ma q and pk these options are discussed in subsection 2 1 3 To invoke the optimizer outside cl30 refer to subsection 2 9 2 2 4 1 Optimization Levels Using the C Compiler Optimizer There are four levels of optimization 0 1 2 and 3 These levels control the type and degree of optimization Lj Level 0 performs control flow graph simplification allocates variables to registers performs loop rotation eliminates dead code simplifies expressions and statements expands calls to functions declared as inline J Level 1 performs all level 0 features plus performs local copy constant propagat
87. with interlist utility ol optimizer option options 2 4 ol0 compiler option assembler ol1 compiler option code generator ol2 compiler option conventions file specifiers ON optimizer option bs i 1 2 1 on optimizer option A ON0 compiler option parser 2 58 oN1 compiler option oN2 compiler option op optimizer option op0 compiler option op1 compiler option op2 compiler option open file function 5 39 5 41 runtime model summary table 2 6 type checking os compiler option p compiler option OPEN 1 0 function parser opt extension options 2 16 2 58 opt30 parsing in two passes ia pe compiler option general perror function algebraic reordering A 9 alias disambiguation A 9 branch optimizations common subexpression elimination A 10 pf parser option pk compiler option B 22 pl compiler option constant folding A g pm parser option control flow simplification A 14 pn compiler option 2 34 2 34 copy propagation A 14 po compiler option Index 8 po option pointer combinations 3 22 position file indicator function 5 59 pow function 5 54 power pragma CODE_SECTION 3 12 DATA_SECTION FUNC_CANNOT_INLINE FUNC_EXT_CALLED FILE ea _INLINE 2 31 2 46 LINE 2 31 TMS320C30 2 31 TMS320C31
88. you intend You must be extremely careful when using asm inline assembly statements in optimized code The optimizer rearranges code segments uses registers freely and may completely remove variables or expressions Although the compiler will never optimize out an asm statement except when it is totally unreachable the surrounding environment where the assembly code is inserted may differ significantly from its apparent context in the C source code It is usually safe to use asm statements to manipulate hardware controls such as interrupt registers or I O ports but asm statements that attempt to interface with the C environment or access C variables may have unexpected results After compilation check the assembly output to make sure your asm statements are correct and maintain the integrity of the program The optimizer analyzes data flow to avoid memory accesses whenever possible If you have code that depends on memory accesses exactly as written in the C code you must use the volatile keyword to identify these accesses The compiler won t optimize out any references to volatile variables In the following example the loop waits for a location to be read as OxFF unsigned int ctrl while ctrl 0OxFF C Compiler Description 2 41 Using the C Compiler Optimizer Aliasing 2 42 In this example ctrl is a loop invariant expression so the loop will be optimized down to a single memory read To correct this declare ctrl
89. 0 Bugs SDSsq03911 SDSsq04011 SDSsq04090 SDSsq04165 SDSsq04167 SDSsq04220 SDSsq04347 Description Error when compiling code with line preprocessor command enhancement request 40bit precision in register variable calls v 5 00 ASM30 generates an INDIRECT ADDRESS REQUIRED error that v 4 70 does not Differences from V4 70 to V5 00 Inline memcpy being generated in c_intxx s Optimizer ignores onx from shell command line and z from opt30 command line The pragma CODE_SECTION doesn t work a linker option aa compiler option abort function abs function as intrinsic absolute value ac30 2 57 acos function ad compiler option add_device function al compiler option aliased variables aliasing 2 42 alternate directories for include files 2 33 ANSI C ansi_ftoi ar linker option ARO FP AR1 SP arc cosine arc sine arc tangent archive library 2 68 archiver as compiler option 2 29 ASCII conversion functions asctime function asin function asm extension asm statement C language assembler 1 3 options Index assembler options 2 23 assembly language and C source statements 2 49 assembly language modules 4 22 assert function assert h header atan function atan2 function atexit function 5 27 atof function atoi function atol function au compiler op
90. 29E 07 DBL_EPSILON 1 1920929E 07 LDBL_EPSILON 1 19209287E 07 FLT_MIN 5 877481 7E 39 DBL_MIN 5 877481 7E 39 LDBL_MIN 5 87747175E 39 FLT_MAX 3 4028235E 88 DBL_MAX 3 4028235E 88 LDBL_MAX 3 40282367E 88 FLT MIN 10 EXP 39 DBL_MIN_10_EXP LDBL_MIN_10_EXP FLT MAX 10 EXP 38 DBL MAX 10_EXP LDBL MAX 10_ EXP Key to prefixes FLT_ applies to type float DBL_ applies to type double LDBL_ applies to type long double Header Files Table 5 2 Macros That Supply Floating Point Range Limits float h Description Base or radix of exponent representation Rounding mode for addition Number of decimal digits of precision for a float double or long double floating point Number of base FLT_RADIX digits in the mantissa of a float double or long double Minimum negative integer such that FLT_RADIX raised to that power minus 1 is a normalized float double or long double Maximum negative integer such that FLT_RADIX raised to that power minus 1 is a representable finite float double or long double Minimum positive float double or long double number x such that 1 0 x 1 0 Minimum positive float double or long double Maximum float double or long double Minimum negative integers such that 10 raised to that power is in the range of normalized floats doubles or long doubles Maximum positive integers such that 10 raised to that power is in the range of representable finite floats doubles or long doubles
91. 3x User s Guide literature number SPRU031 describes the C3x 32 bit floating point microprocessor developed for digital signal proces sing as well as general applications its architecture internal register structure instruction set pipeline specifications and DMA and serial port operation Software and hardware applications are included TMS320C32 Addendum to the TMS320C3x User s Guide literature num ber SPRU132 describes the TMS320C32 floating point microprocessor developed for digital signal processing as well as general applications Discusses its architecture internal register structure specifications and DMA and serial port operation Hardware applications are also included Related Documentation From Texas Instruments TMS320C4x User s Guide literature number SPRU063 describes the C4x 32 bit floating point processor developed for digital signal processing as well as parallel processing applications Covered are its architecture in ternal register structure instruction set pipeline specifications and op eration of its six DMA channels and six communication ports Parallel Processing with the TMS320C4x literature number SPRA031 de scribes parallel processing and how the C4x can be used in parallel pro cessing Also provides sample parallel processing applications TMS320C4x General Purpose Applications User s Guide literature number SPRU159 describes software and hardware applications for the
92. ARM 0 Standard runtime model POP FP Restore FP endif RETS Inthe C program in Example 4 1 the extern declaration of asmfunc is optional because the function returns an int Like C functions assembly functions need be declared only if they return noninteger values If you are using the register argument runtime model all functions including assembly language functions should have prototypes so that the arguments are passed correctly 4 5 2 Accessing Assembly Language Variables From C Itis sometimes useful for a C program to access variables or constants defined in assembly language There are three different methods that you can use to accomplish this depending on where and how the item is defined a variable defined in the bss section a variable not defined in the bss section or a constant Runtime Environment 4 25 Interfacing C With Assembly Language Accessing Variables Defined in the bss Section Accessing uninitialized variables from the bss section is straightforward D Use the bss directive to define the variable D Use the global directive to make the definition external DD Remember to precede the name with an underscore D InC declare the variable as extern and access it normally Example 4 2 shows an example that accesses a variable defined in bss Example 4 2 Accessing a Variable Defined in bss From C a Assembly Language Program Note the use of underscores in the
93. C4x processor Also includes development support information parts lists and XDS510 emulator design considerations TMS320C30 Evaluation Module Technical Reference literature number SPRU069 describes board level operation of the TMS320C30 evalua tion module Digital Signal Processing Applications With the TMS320C30 Evaluation Module Selected Application Notes literature number SPRA0O21 contains useful information for people who are preparing and debugging code The book gives additional information about the TMS320C30 eval uation module as well as C coding tips TMS320 DSP Development Support Reference Guide literature number SPRUO011 describes the TMS320 family of digital signal processors and the tools that support these devices Included are code generation tools compilers assemblers linkers etc and system integration and debug tools simulators emulators evaluation modules etc Also covered are available documentation seminars the university program and factory repair and exchange TMS320 DSP Designer s Notebook Volume 1 literature number SPRT125 presents solutions to common design problems using C2x C3x C4x C5x and other TI DSPs TMS320 Third Party Support Reference Guide literature number SPRU052 alphabetically lists over 100 third parties that provide various products that serve the family of TMS320 digital signal processors A myriad of products and applications are offered software and hardw
94. D RENAME Read Characters From Buffer int READ int file_descriptor char buffer unsigned count The READ function reads the number of characters specified by count to the buffer from the device or file associated with file_descriptor The file_descriptor is the stream number assigned by the low level routines that is associated with the opened file or device The buffer is the location of the buffer where the read characters are placed The count is the number of characters to read from the device or file The function returns one of the following values 0 if EOF was encountered before the read was complete number of characters read in every other instance if fails Rename File int RENAME char o d_name char new_name The RENAME function changes the name of a file The old_name is the current name of the file Lj The new_name is the new name for the file The function returns one of the following values 0 if the rename is successful Non 0 if it fails The C I O Functions B 9 UNLINK WRITE Alphabetical Summary of C I O Functions UNLINK Syntax Description Return Value WRITE Syntax Description Return Value B 10 Delete File int UNLINK char path The UNLINK function deletes the file specified by path The path is the filename of the file to be opened including path information The function returns one of the following values 0 if successful
95. D Uninitialized sections reserve space in memory usually RAM A pro gram can use this space at runtime for creating and storing variables The compiler creates three uninitialized sections bss stack and sysmem Memory Model E The bss section reserves space for global and static variables in the small model the bss section also reserves space for the constant table At program startup the C boot routine copies data out of the cinit section which may be in ROM and stores it in the bss section m The stack section allocates memory for the system stack This memory is used to pass arguments to functions and to allocate local variables m The sysmem section is a memory pool or heap used by the dynamic memory functions malloc calloc and realloc If a program does not link these functions the linker does not create the sysmem section For the TMS320C32 only the sysm8 section and sysm16 section are used by special 8 bit and 16 bit versions of the dynamic memory management functions See Section 4 1 3 for more information The linker takes the individual sections from different models and combines sections with the same name to create output sections Note that the assembler creates three default sections text bss and data the C compiler however does not use the data section The complete program is made up of the compiler output sections plus the assembler s data section The linker takes the individual
96. I O dynamic memory allocation string operations and trigonometric functions are not part of the C language itself However the ANSI C standard defines a set of runtime support functions that perform these tasks The TMS320C3x C4x C compiler implements the complete ANSI standard library except for those facilities that handle exception conditions and locale issues properties that depend on local language nationality or culture Using the ANSI standard library ensures a consistent set of functions that provide for greater portability In addition to the ANSI specified functions the TMS320C3x C4x runtime support library includes routines that give you direct C language I O requests Topic Page BaleeUsingithell OFRUnciions Srerrt rrr eter Geter teeter e rr B 2 Overview of Low Level I O Implementation B 3 Addinigia Device For C NOn a a a guteusannseas B 1 Using the I O Functions B 1 Using the I O Functions B 2 The C I O functions make it possible to access the host s operating system to perform I O using the debugger For example printf statements executed in a program appear in the debugger command window When used in conjunction with the debugging tools the capability to perform I O on the host gives you more options when debugging and testing code To use the I O functions DD Include the header file stdio h for each module that references a function With properly written device
97. INLINE Invoking the Tools Individually Parsing in Two Passes Compiling very large source programs on small host systems such as PCs can cause the compiler to run out of memory and fail You may be able to work around such host memory limitations by running the parser as two separate passes the first pass preprocesses the file and the second pass parses the file When you run the parser as one pass it uses host memory to store both macro definitions and symbol definitions simultaneously But when you run the parser as two passes these functions can be separated The first pass performs only preprocessing therefore memory is needed only for macro definitions In the second pass there are no macro definitions therefore memory is needed only for the symbol table The following example illustrates how to run the parser as two passes 1 Run the parser with the po option specifying preprocessing only c130 po file c If you want to use the d mr u v x or i options use them on this first pass This pass produces a preprocessed output file called file pp For more information about the preprocessor refer to Section 2 2 2 Rerun the whole compiler on the preprocessed file to finish compiling it c130 file pp You can use any other options on this final pass 2 9 2 Optimizing Parser Output The second step in compiling a TMS320C3x C4x C program optimizing is optional After parsing a C source file you c
98. KR KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK TMS320C30 C COMPILER Version X XX KEK KKK KKK KKK KKK KK KKK KKK KEK KKK KKK KEK KKK KKK KKK KKK KKKKKKKKAEKKAKK KKK KKK KK KK KKK ac30 mr a3 c a3 if opt30 r 02 a3 if a3 opt cg30 p a3 opt a3 asm a3 tmp version 30 FP Set AR3 globl _wait KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK x FUNCTION DEF _wait KKK KK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK _wait i AR2 assigned to parameter p L2 LDI 8 RO TSTB RO AR2 BZ L2 LDI 240 R1 OR R1 AR2 R2 STI R2 AR2 XEK B L2 BRANCH OCCURS end A 6 Description of Compiler Optimizations TMS320C4x specific features The TMS320C4x has several instructions and addressing modes that are particularly useful in compiled code The instructions include store integer immediate STIK load address register LDA load data page pointer LDPK and a 32x32 integer multiply MPYI The new addressing modes allow constants and indirect offset operands to be used in 3 operand instructions In addition separate AR interlocks eliminate the pipeline delays associated with independent use of the AR registers Example A 4 illustrates some of the new C4x features Description of Compiler Optimizations A 7 Description of Compiler Optimizations Example A 4 TMS320C4x Spe
99. LK 16 bit constant shift The LALK instruction has two parameters The first parameter 16 bit con stant is required The second parameter shift is optional As this syntax shows if you use the optional second parameter you must precede it with a comma Square brackets are also used as part of the pathname specification for VMS pathnames in this case the brackets are actually part of the path name they are not optional Braces and indicate alist The symbol read as or separates items within the list Here s an example of a list EE we This provides three choices or Unless the list is enclosed in square brackets you must choose one item from the list Some directives can have a varying number of parameters For example the byte directive can have up to 100 parameters The syntax for this di rective is byte value valuen This syntax shows that byte must have at least one value parameter but you have the option of supplying additional value parameters separated by commas Read This First V Related Documentation From Texas Instruments Related Documentation From Texas Instruments vi The following books describe the TMS320C3x C4x and related support tools To obtain a copy of any of these TI documents call the Texas Instruments Liter ature Response Center at 800 477 8924 When ordering please identify the book by its title and literature number TMS320C3x C4x Cod
100. Product Information Center PIC _http www ti com sc docs pic home htm DSP Solutions http www ti com dsps 320 Hotline On line http www ti com sc docs dsps support htm g North America South America Central America Product Information Center PIC 972 644 5580 TI Literature Response Center U S A 800 477 8924 Software Registration Upgrades 214 638 0333 Fax 214 638 7742 U S A Factory Repair Hardware Upgrades 281 274 2285 U S Technical Training Organization 972 644 5580 DSP Hotline 281 274 2320 Fax 281 274 2324 Email dsph ti com DSP Modem BBS 281 274 2323 DSP Internet BBS via anonymous ftp to ftp ftp ti com pub tms320bbs Europe Middle East Africa European Product Information Center EPIC Hotlines Multi Language Support 33 130701169 Fax 33 1 30 70 1032 Email epic ti com Deutsch 49 8161 80 33 11 or 33 1 30 70 11 68 English 33 1 30 70 11 65 Francais 33 1 30 70 11 64 Italiano 33 1 30 70 11 67 EPIC Modem BBS 33 1 30 70 11 99 European Factory Repair 33 4 93 22 25 40 Europe Customer Training Helpline Fax 49 81 61 80 40 10 g Asia Pacific Literature Response Center 852 2 956 7288 Fax 852 2 956 2200 Hong Kong DSP Hotline 852 2956 7268 Fax 852 2 956 1002 Korea DSP Hotline 82 2551 2804 Fax 82 2551 2828 Korea DSP Modem BBS 82 2551 2914 Singapore DSP Hotline Fax 65 390 7179 Taiwan DSP Hotline 886 23771450 Fax 886 2 377 2718 Taiwan DSP Modem BBS 886 2 376 2592 Taiwan DSP Internet BBS via
101. Runtime Support Functions 5 7 Header Files 5 2 6 Floating Point Math math h The math h header defines several trigonometric exponential and hyperbolic math functions These math functions expect double precision floating point arguments and return double precision floating point values Except where indicated all trigonometric functions use angles expressed in radians The math h header also defines one macro named HUGE_VAL the math functions use this macro to represent out or range values When a function produces a floating point return value that is too large to be represented it returns HUGE_VAL instead 5 2 7 Nonlocal Jumps setjmp h The setjmp h header defines one type one macro and one function for bypassing the normal function call and return discipline These include J jmpbuf an array type suitable for holding the information needed to restore a calling environment J setimp amacro that saves its calling environment in its jmp_buf argument for later use by the longjmp function ongjmp a function that uses its jmp_buf argument to restore the program environment 5 2 8 Variable Arguments stdarg h 5 8 Some functions can have a variable number of arguments whose types can differ such functions are called variable argument functions The stdarg h header declares three macros and a type that help you to use variable argument functions D The three macros are va_start va_arg and va_end These mac
102. SDSsq03798 SDSsq03892 SDSsq03896 SDSsq03909 Description Enhancement request for error and warning summary Request to change the function of the block keyword Documentation incomplete Problem with STF Need option to do RND before STF ISR s should use more ARx s than Rx s to reduce push pops switch var amp 7 generates useless default case data amp prog on same page direct addressing Allow assembly DATA in non standard sections Assembler should warn of possible parallelism Add capabilities to support quoted strings in packed string ASM directv Add capability for packed char int arrays to save memory Sometimes the map and stdout do not report eh cinit section Wants to be able to use a C header to make assembly struct directives Optimize the c_intxx functions customer has problem compiling following code with v4 70 strtod function does not give accurate results Invalid Divide Routine Request for compiler to be able to place init data in named sections Request for compiler to allow packed bytes Symbol pinit at address FFFFFFFF appears in link map Encoding of MPYF SUBF changed from v4 7 preprocessing does not work correctly for conditional compilations asm statement with circular addressing not compiled corrected by C compiler When converting to ascii hex format sometimes places entry point in output file Summary of Updates in This Document D 9 Summary of Updates in This Document D 1
103. TMS320C32 TMS320C3x TMS320C40 TMS320C44 TMS320C4x preinitialized a preprocess only 2 preprocessed eg io preprocessor 2 34 P 34 isting fle Ba es 2 33 listing file 2 2 16 predefining name a symbols 2 31 preprocessor directives 2 30 C language 8 3 Index trailing tokens 3 23 printf function program termination functions abort exit 5 22 atexit exit prototype listing file pseudorandom ptrdiff_t type 3 2 5 9 putc function putchar function puts function pw option 2 52 q compiler option q interlist utility option 2 64 q library build utility option q linker option qq compiler option qsort function 5 56 r interlist utility option 2 64 r linker option RAM model of autoinitialization RAM model of initialization 2 69 rand function 5 57 RAND_MAX macro 5 10 read character functions multiple characters ee next character unction 5 43 single characler 5 38 stream functions from standard input 5 59 from string to array 5 40 string read function READ I O nenon E realloc function rr realloc16 function realloc8 function recoverable errors Index 9 Index register variables register storage cass Ba register variables 4 C language _REGPARM remove function rename function RENAME I O function B 9 rewind function 5 59 ROM model of autoinitialization ROM mo
104. TMS320C3x C4x Optimizing C Compiler User s Guide Literature Number SPRU034H June1998 sag TEXAS INSTRUMENTS Printed on Recycled Paper IMPORTANT NOTICE Texas Instruments TI reserves the right to make changes to its products or to discontinue any semiconductor product or service without notice and advises its customers to obtain the latest version of relevant information to verify before placing orders that the information being relied on is current Tl warrants performance of its semiconductor products and related software to the specifications applicable at the time of sale in accordance with Tl s standard warranty Testing and other quality control techniques are utilized to the extent TI deems necessary to support this warranty Specific testing of all parameters of each device is not necessarily performed except those mandated by government requirements Certain applications using semiconductor products may involve potential risks of death personal injury or severe property or environmental damage Critical Applications TI SEMICONDUCTOR PRODUCTS ARE NOT DESIGNED INTENDED AUTHORIZED OR WARRANTED TO BE SUITABLE FOR USE IN LIFE SUPPORT APPLICATIONS DEVICES OR SYSTEMS OR OTHER CRITICAL APPLICATIONS Inclusion of TI products in such applications is understood to be fully at the risk of the customer Use of TI products in such applications requires the written approval of an appropriate TI officer Questions concerning
105. The __INLINE Preprocessor Symbol page 2 46 D Automatic inline expansion functions notdeclared as inline is done when the optimizer is invoked at level 3 By default the optimizer will inline very small functions You can change the size of functions that are automatically inlined with the oisize option The oi option specifies that functions whose size times number of calls is less than size units are in lined regardless of how they were declared The optimizer measures the size of a function in arbitrary units However the size of each function is reported in the optimizer information file on1 option If you want to be certain that a function is always inlined use the inline keyword discussed above and in the next subsection You can defeat all automatic inlining of small functions not declared as inline by setting the size to 0 oi0 Te Function Inlining May Greatly Increase Code Size It should be noted that expanding functions inline expands code size and that inlining a function that is called a great number of times can expand code size exponentially Function inlining is optimal for functions that are called only asmall number of times or for small functions that are called more often If your code size seems too large try compiling with the x0 keyword and note the difference in code size ee Function Inlining 2 5 1 Controlling Inline Expansion x Option A command line switch controls the types
106. Tools Overview The following list describes the tools that are shown in Figure 1 1 E The C compiler accepts C source code and produces TMS320C3x or TMS320C4x assembly language source code A shell program cl30 an optimizer opt30 and an interlist utility clist are included in the compiler package m The shell program enables you to automatically compile assemble and link source modules m The optimizer modifies code to improve the efficiency of C programs The interlist utility interlists C source statements with assembly lan guage output Chapter 2 describes how to invoke and operate the compiler the shell the optimizer and the interlist utility The assembler translates assembly language source files into machine language object files The machine language is based on common object file format COFF The TMS320C3x C4x Assembly Language Tools User s Guide explains how to use the assembler The linker Ink30 combines object files into a single executable object module As it creates the executable module it performs relocation and resolves external references The linker accepts relocatable COFF object files and object libraries as input The archiver ar30 allows you to collect a group of files into a single archive file called a ibrary lt also allows you to modify a library by deleting replacing extracting or adding members One of the most useful applications of the archiver is building a library
107. With the tf option the compiler overlooks such redeclarations of parameter lists relaxes type checking on pointer combinations This option has two effects D A pointer to a signed type can be combined in an operation with a pointer to the corresponding unsigned type int pi unsigned pu pi pu Illegal unless tp used D Pointers to differently qualified types can be combined char p const char pc p pc Illegal unless tp used tp is especially useful when you pass pointers to prototyped functions because the passed pointer type would ordinarily disagree with the declared parameter type in the prototype C Compiler Description 2 19 Compiling C Code Runtime Model Options 2 20 assumes that variables are aliased The compiler assumes that pointers may alias point to named variables and therefore aborts certain optimizations when an assignment is made through a pointer selects the big memory model allowing unlimited space for global data static data and constants In the small memory model which is the default this space is limited to 64K words All code used in the eventual executable module in cluding all library resident code must be compiled under the same model For more information refer to Section 2 3 on page 2 35 uses faster float to int conversion The ANSI C standard specifies that when an object of floating point type is con verted to an integer type the fractional part
108. _str tm_mday time_str tm_hour time_str tm_min time_str tm_sec time_str tm_isdst ll Ha O Oea Ne Ne Ne Ne Ne we mktime amp time_str After calling this function time_str tm_wday contains the day of the week for July 4 2001 printf result is s n wday time_str tm_wday For more information about the functions and types that the time h header declares refer to subsection 5 2 13 on page 5 11 Syntax Defined in Description Example Syntax Defined in Description Alphabetical Summary of Runtime Support Functions modf perror Signed Integer and Fraction include lt math h gt double modf double value double iptr modf30 asm in rts src The modf function breaks a value into a signed integer and a signed fraction Each of the two parts has the same sign as the input argument The function returns the fractional part of value and stores the integer part as a double at the object pointed to by iptr double value ipart fpart value 3 1415 fpart modf value amp ipart After execution ipart contains 3 0 and fpart contains 0 1415 Map Error Number include lt stdio h gt void perror const char s perror c in rts src Maps the error number ins to a string The function then prints the error mes sage Runtime Support Functions 5 53 pow printf putc Alphabetical Summary of Runtime Support Functions Syntax Defined in Description Example
109. a code diagnostic message indicating the condition that caused the failure usually the message also spec ifies the maximum value for whatever limit has been exceeded The code generator also has compilation limits but fewer than the parser In general exceeding any compiler limit prevents continued compilation so the compiler aborts immediately after printing the error message The only way to avoid exceeding acompiler limit is to simplify the program or parse and pre process in separate steps Many compiler tables have no absolute limits but rather are limited only by the amount of memory available on the host system Table 3 3 specifies the limits that are absolute When two values are listed the first is for PCs DOS or OS 2 and the second is for other hosts All the absolute limits equal or exceed those required by the ANSI C standard On smaller host systems such as PCs the optimizer may run out of memory If this occurs the optimizer terminates and the shell continues compiling the file with the code generator This results in a file compiled with no optimization The optimizer compiles one function at a time so the most likely cause of this is alarge or extremely complex function in your source module To correct the problem your options are J don t optimize the module in question identify the function that caused the problem and break it down into smaller functions D extract the function from the module and pl
110. able LDP X 1 extra word 1 cycle LDI _x RO 3 cycles 2 pipeline delays To use the big memory model invoke the compiler with the mb option For more information refer to Section 2 3 Using Runtime Models on page 2 35 4 1 5 RAM and ROM Models 4 6 The C compiler produces code that is suitable for use as firmware in a ROM based system In such a system the initialization tables in the cinit section used for initialization of globals and statics are stored in ROM At sys tem initialization time the C boot routine copies data from these tables from ROM to the initialized variables in bss RAM In situations where a program is loaded directly from an object file into memory and then run you can avoid having the cinit section occupy space in memory A user defined loader can read the initialization tables directly from the object file instead of from ROM and perform the initialization directly at load time instead of at runtime You can specify this to the linkerby using the cr linker option For more information refer to Section 4 8 System Initialization on page 4 36 Object Representation 4 2 Object Representation This section explains how various data objects are sized aligned and accessed 4 2 1 Data Type Storage D All basic types are 32 bits wide and stored in individual words of memory No packing is performed except on bit fields which are packed into words Bit fields are allocated from LSB
111. ace it in a separate module that can be compiled without optimization so that the remaining functions can be optimized DD Use the protected mode compiler Compiler Limits Table 3 3 Absolute Compiler Limits Description Limits Filename length 256 characters Source line length 16K characters see note 1 Length of strings built from or 512 characters see note 2 Macro definitions Allocated from available system memory Macros predefined with d 32 Macro parameters 32 Macro nesting 32 levels see note 3 include search paths 32 paths see note 4 include file nesting 32 levels Conditional inclusion if nesting 32 levels Nesting of struct union or prototype dec 20 levels larations Function parameters 32 parms Array function or pointer derivations on 12 derivations a type Aggregate initialization nesting 32 levels Static initializers 1500 per initialization Local initializers 150 per block Nesting of declarations in structs unions 32 levels or prototypes Global symbols 2000 PCs 10000 All others Block scope symbols visible at any point 500 PCs 1000 All others Number of unique string constants 400 PCs 1000 All others Number of unique floating point 400 PCs constants 2000 All others Notes 1 After splicing of lines This limit also applies to any single macro definition or invoca tion 2 Before concatenation All other character strings are unrestricted 3 Includes argument subst
112. al Summary of Runtime Support Functions remove Syntax Defined in Description Syntax Defined in Description If in order to allocate more space the entire object must be moved realloc returns a pointer to the new space Any memory freed by this operation is deallocated If an error occurs the function returns a null pointer 0 The memory that realloc uses is in a special memory pool or heap defined in an uninitialized named section called sysmem in memory c The linker sets the size of this section from the value specified by the heap option Default heap size is 1K words For the TMS320C32 processor 8 bit and 16 bit versions of the realloc function are provided The functions realloc8 and realloc16 are analogous to realloc however memory is allocated from the uninitialized sections sysm8 and sysm16 respectively The linker creates a sysm8 or sysm16 section when a size is specified using the heap8 or heap16 option It will create a section of the default size 1K of 8 bit or 16 bit words when the realloc8 and realloc16 functions are used and the heap8 and heap16 options are not For more information refer to subsection 4 1 3 Dynamic Memory Allocation on page 4 4 Remove File include lt stdio h gt int remove const char file remove c in rts src Makes the file pointed to no longer available by that name The file is pointed to by file Rename File include lt stdio h gt int renam
113. al instructions 1 Branch optimizations control flow L Delayed branches simplification delayed branches L TMS320C4x specific features D Loop induction variable optimizations strength reduction D Loop unrolling Li Loop rotation 1 Loop invariant code motion L Inline function expansion A 1 Description of Compiler Optimizations Effective register use A 2 The TMS320C3x C4x DSPs have a large and versatile set of registers The compiler is designed to make effective use of the registers for both general computations and in cases where specific registers can be used in specialized ways I Register variables The compiler helps maximize the use of registers for storing local variables parameters and temporary values Variables stored in registers can be accessed more efficiently than variables in memory Register variables are particularly effective for pointers See Example A 1 and Example A 2 Lj Register tracking targeting The compiler tracks the contents of registers so that it avoids reloading values if they are used again soon Variables constants and structure references such as a b are tracked through both straight line code and forward branches The compiler also uses register targeting to compute expressions directly into specific registers when required as in the case of assigning to reg ister variables or returning values from functions See Example A 1 Description of Compiler Optimizations Example A 1
114. alled directly or indirectly the com piler removes the function By default the name of the resulting object file or assembly file is the same as the name of the first input C file suppresses line and file information pn causes line di rectives of the form 123 file c to be suppressed in a file generated with po or pl You may find pn useful when compiling machine generated source runs the compiler for preprocessing only When invoked with po the compiler processes only macro expansions include files and conditional compilation The compiler writes the preprocessed file with a pp extension For more information refer to subsection 2 2 3 on page 2 34 creates a parser error message file The error file has the base name of the input file and the err extension The file contains all error messages generated by the parser sets the warning message level Section 2 7 on page 2 51 discusses the diagnostic information reported by the com piler pw or pw0 disables all warning messages D pw1 enables serious warning messages default J pw2 enables all warning messages C Compiler Description 2 17 Compiling C Code Inlining Options 2 18 px filename xX n when using the pm option specifies the name of the final output file For example cl30 pm one c two c three c px progl results in an object file named prog1 obj enables trigraph expansion Trigraphs are special escape seq
115. alloc function struct big table table struct big malloc 10000 sizeof struct big For the TMS320C32 the runtime support library contains the following 8 bit and 16 bit versions of the dynamic memory management functions calloc8 free8 malloc8 bmalloc8 minit8 realloc8 callocl6 freel6 mallocl6 bmallocl6 minit16 reallocl6 These functions allocate space from the sysm8 and sysm16 uninitialized sections rather than the sysmem section The sizes of the sysm8 and sysm16 sections are set by specifying the heap8 and heap16 linker options respectively If the 8 bit or 16 bit memory management functions are used but the heap8 and heap16 options are not specified the linker will allo cate the default size of 1K 8 bit or 16 bit words The 8 bit or 16 bit memory functions cause the linker to set the constant heap size values for the _SYSMEM8_SIZE and _SYSMEM16_SIZE symbols The stdlib h header file should be included in any file that uses these functions 4 1 4 Big and Small Memory Models The compiler supports two memory models that affect how bss is allocated into memory Neither model restricts the size of the text or cinit sections Both models restrict the size of a single function to 32K words of code or less this allows the compiler to use relative conditional jumps over the entire range of the function The small memory model which is the default requires that the entire bss section fit within a si
116. ally across entire functions See Example A 5 and Example A 6 m Copy propagation Following an assignmentto a variable the compiler replaces references to the variable with its value The value could be another variable a constant or a common subexpression This may result in increased opportunities for constant folding common subexpression elimination or even total elimination of the variable See Example A 5 and Example A 6 Common subexpression elimination When the same value is produced by two or more expressions the compiler computes the value once saves it and reuses it See Example A 5 Redundant assignment elimination Often copy propagation and common subexpression elimination optimizations result in unnecessary assignments to variables variables with no subsequent reference before another assignment or before the end of the function The optimizer removes these dead assignments See Example A 5 Description of Compiler Optimizations Example A 5 Data Flow Optimizations simp int j int a 3 int b J a J 2 int c j lt lt a int d j lt lt 3 J lt lt b call a b c d KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK AK KKK KK KK TMS320C30 C COMPILER Version X XX K KKK KK KKK KKK KK KKK KKK KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KKK KKK KK KKK KK ac30 mr a5 c a5 if A opt30 r 02 a5 if a5 o
117. amp R A8 3 A bit field of type integer is signed Bit fields are packed into words begin ning at the low order bits and do not cross word boundaries ANSI 3 5 2 1 K amp R A8 3 The preprocessor recognizes one pragma directive all others are ig nored For details see Section 3 5 Pragma Directives The recognized pragma is pragma DATA_SECTION symbol section name The standard error preprocessor directive forces the compiler to issue a diagnostic message and halt compilation The TMS320C3x C4x compiler extends the error directive with a warn directive which like error forces a diagnostic message but does not halt compilation The syntax of warn is identical to error K amp R A12 7 TMS320C3x C4x C Language 3 3 Data Types 3 2 Data Types UO oO OULO All integer types char short int long and their unsigned counterparts are equivalent types and are represented as 32 bit binary values Signed types are represented in 2s complement notation The type char is a signed type equivalent to int Objects of type enum are represented as 32 bit values in expressions the type enum is equivalent to int Floating point types float and double are equivalent and are represented in the TMS320C3x C4x 32 bit single precision floating point format Floating point type long double is represented in the TMS320C3x C4x 40 bit extended precision format Although floating point types are not directly suppo
118. an angle in the range 1 2 71 2 radians double realval radians realval 1 0 radians asin realval asin returns 1 2 Runtime Support Functions 5 25 assert Alphabetical Summary of Runtime Support Functions Syntax Defined in Description Example Insert Diagnostic Information Macro include lt assert h gt void assert int expression assert h as a macro The assert macro tests an expression depending upon the value of the expression assert either aborts execution and issues a message or continues execution This macro is useful for debugging Ifexpression is false the assert macro writes information about the partic ular call that failed to the standard output and then aborts execution If expression is true the assert macro does nothing The header file that declares the assert macro refers to another macro NDEBUG If you have defined NDEBUG as a macro name when the assert h header is included in the source file then the assert macro is defined to have no effect If NDEBUG is not defined when assert h is included the assert macro is de fined to test the expression and if false write a diagnostic message including the source filename line number and test of expression The assert macro is defined with the printf function which is not included in the library To use assert you must either D Provide your own version of printf or Modify assert to output the messa
119. an choose to process the intermediate file with the optimizer The optimizer improves the execution speed and reduces the size of C programs The optimizer reads the intermediate file optimizes it according to the level you choose and produces an intermediate file The intermediate file has the same format as the original intermediate file but it enables the code generator to produce more efficient code C Compiler Description 2 59 Invoking the Tools Individually To invoke the optimizer enter opt30 input file output file options opt30 input file output file options is the command that invokes the optimizer names the intermediate file produced by the parser The optimizer assumes that the extension is if names the intermediate file that the optimizer creates If you don t supply a filename for the output file the optimizer uses the input filename with an extension of opt affect the way the optimizer processes the input file The options that you use in standalone optimization are the same as those used for the shell Besides the optimizer options some other compiler options may be used with the optimizer Those formats are shown in Table 2 5 Section 2 4 provides a detailed list of the optimizations performed at each level Detailed explanations of each optimizer option may be found on page 2 26 Table 2 5 Optimizer Options and Shell Options Invoking the Tools Individually opt30 Option SU
120. anonymous ftp to ftp dsp ee tit edu tw pub TI Japan Product Information Center 0120 81 0026 in Japan Fax 0120 81 0036 in Japan 03 3457 0972 or INTL 813 3457 0972 Fax 03 3457 1259 or INTL 813 3457 1259 DSP Hotline 03 3769 8735 or INTL 813 3769 8735 Fax 03 3457 7071 or INTL 813 3457 7071 DSP BBS via Nifty Serve Type Go TIASP Documentation When making suggestions or reporting errors in documentation please include the following information that is on the title page the full title of the book the publication date and the literature number Mail Texas Instruments Incorporated Email dsph ti com Technical Documentation Services MS 702 P O Box 1443 Houston Texas 77251 1443 Note When calling a Literature Response Center to order documentation please specify the literature number of the book Read This First ix Contents Introduction 7 1 1 Provides an overview of the TMS320C3x 4x software development tools 1 1 Software Development Tools Overview pp 1 2 1 2 TMS320C3x C4x C Compiler Overview pp 1 5 C Compiler Description pp 2 1 Describes how to operate the C compiler and the cl30 shell program Contains instructions for invoking the shell program which compiles assembles and links a C source file and for invok ing the individual compiler components such as the optimizer Discusses the interlist utility file name specifications compiler options compiler errors and use of the linker
121. ant to set C_OPTION in your system initialization file for example on PCs in your autoexec bat file Using the z option enables linking If you plan to link most of the time when using the shell you can specify the z option with C_OPTION Later if you need to invoke the shell without linking you can use c on the command line to override the z specified with C_OPTION These examples assume C_OPTION is set as shown previously c130 c compiles and links cl30 c SG only compiles el30 c Groma compiles links using command file C130 c c z c cmd only compiles c overrides z 2 1 5 Using the TMP Environment Variable The shell program creates intermediate files as it processes your program For example the parser phase of the shell creates a temporary file used as input by the code generation phase By default the shell puts intermediate files in the current directory However you can name a specific directory for temporary files This feature allows use of a RAM disk or other high speed storage files It also allows source files to be compiled from a remote directory without writing any files into the directory where the source resides This is useful for protected directories 2 28 Compiling C Code There are two ways to specify a temporary directory 1 Use the TMP environment variable set TMP d temp This example is for a PC Use the appropriate command for your host 2 Use the ft option o
122. are development tools speech recognition image processing noise can cellation modems etc Read This First vii Related Documentation Trademarks Related Documentation Trademarks viii The C Programming Language second edition by Brian W Kernighan and Dennis M Ritchie published by Prentice Hall Englewood Cliffs New Jersey 1988 describes ANSI C You can use it as a reference You may find these documents helpful as well Advanced C Techniques and Applications Sobelman Gerald E and David E Krekelberg Que Corporation American National Standards Institute C Specification American National Standard for Information Systems Programming Language C x3 159 1989 ANSI standard for C Programming in C Kochan Steve G Hayden Book Company Understanding and Using COFF Gircys Gintaras R published by O Reilly and Associates Inc HP UX is a trademark of Hewlett Packard Company MS DOS is a registered trademark of Microsoft Corporation PC DOS is a trademark of International Business Machines Corporation Solaris is a trademark of Sun Microsystems Inc SunOS is a trademark of Sun Microsystems Inc UNIX is a registered trademark in the United States and other countries licensed exclusively through X Open Company Limited XDS is a trademark of Texas Instruments Incorporated If You Need Assistance If You Need Assistance World Wide Web Sites TI Online http www ti com Semiconductor
123. ase int ti_sprintf char s const char format Expands inline if x is used Macro Expands inline unless x0 is used wr Description Terminates a program normally Deallocates memory space allocated by malloc calloc or realloc 8 bit version TMS320C32 only 16 bit version TMS320C32 only Returns the absolute value of j Divides numer by denom producing a quotient and a remainder Converts n to the equivalent digit string Allocates memory for an object of size bytes 8 bit version TMS320C32 only 16 bit version TMS320C32 only Resets all the memory previously allocated by malloc calloc or realloc 8 bit version TMS320C32 only 16 bit version TMS320C32 only Sorts an array of n members base points to the first member of the unsorted array and size specifies the size of members Returns a sequence of pseudorandom integers in the range 0 to RAND_ MAX Changes the size of memory pointed to by pir to size bytes 8 bit version TMS320C32 only 16 bit version TMS320C32 only Resets the random number generator Converts a string to a floating point value Converts a string to a long integer value Converts a string to an unsigned long integer value Supports conversion functions required by time String Functions string h void int void void void char char int int char size_t char size_t char int char char char size_t cha
124. at when the sizeof operator is applied to type char the result is one Since the TMS320C3x C4x char is 32 bits to make it separately addressable a byte is also 32 bits This yields results that you may not expect for example sizeof int 1 not 4 TMS320C3x C4x bytes and words are equivalent 32 bits SS The Long Double Data Type The long double data type is handled differently than the other floating point data types The features of long doubles are described below m m Long doubles are not represented in the single precision 32 bit format used for floats and doubles but in extended precision 40 bit format Long doubles require two memory words for storage the first word con tains the upper 24 bits and the second word contains the lower 24 bits The sizeof long double operator returns 2 Two instructions are required to load and or store long doubles Long doubles can be stored in one floating point register and like floats and doubles can be passed as parameters in registers No register variable can hold a 40 bit value therefore a long double can not be held in a register variable across a call It will be stored to memory before the call and then reloaded when needed In float double to long double conversion the lower 8 bits of the 40 bit register will be filled with zeros In long double to float double conversion the value will be rounded to the nearest single precision floating point
125. ata holes or about any locations reserved for I O or control purposes The compiler produces relocatable code that allows the linker to allocate code and data into the appropriate memory spaces For example you can use the linker to allocate global variables into fast internal RAM or to allocate executable code into internal ROM Each block of code or data could be allo cated individually into memory but this is not a general practice An exception to this is memory mapped I O although physical memory loca tions can be accessed with C pointer types eee eee ee ss The compiler produces six relocatable blocks of code and data these blocks called sections can be allocated into memory in a variety of ways to conform to a variety of system configurations For more information about sections please read the Introduction to Common Object File Format in the TMS320C3x C4x Assembly Language Tools User s Guide There are two basic types of sections J Initialized sections contain data or executable code The C compiler creates three initialized sections text cinit and const m The text section is an initialized section that contains all the executable code as well as floating point constants The cinit section is an initialized section that contains tables with the values for initializing variables and constants m The const section is an initialized section that contains floating point constants and switch tables D
126. atements undefine a constant specify processor xx 30 31 32 40 or 44 default is v30 see also msrev enable linking all options following are passed to linker Table 2 1 Compiler Options Summary Table Continued Compiling C Code File Specifiers These options use the extensions of each file name to determine how to process the file For more information see page 2 14 Option ea e0 fa file fc file fo file frdir fsdir tt Effect set default extension for assembly files set default extension for object files identify assembly language file de fault for asm or s identify C source file default for c or no extension identify object file default for o specify object file directory specify assembly file directory override TMP environment variable Parser Options These options control the preprocessing syntax checking and error handling behavior of the compiler For more information see page 2 16 Option pw0 or pw pw1 pw2 px filename Effect treat code E errors as warnings generate prototypes for functions allow compatibility with pre ANSI K amp R C generate preprocessed listing pp file combines source files to perform program level optimization suppress line directives in pp file preprocess only write parser error messages to file suppress all warning messages enable serious warning
127. ation in an array of flags this array is defined in ctype c The macros have the same name as the corresponding functions but each macro is prefixed with an underscore for example _isdigit 5 2 3 Error Reporting errno h Errors can occur in a math function if the invalid parameter values are passed to the function or if the function returns a result thatis outside the defined range for the type of the result When this happens a variable named errno is set to the value of one of the following macros EDOM for domain errors invalid parameter ERANGE for range errors invalid result C code that calls a math function can read the value of errno to check for error conditions The errno variable is declared in errno h and defined in errno c 5 2 4 Low Level I O Functions file h The file h header declares the low level I O functions used to implement input and output operations The C I O functions make it possible to access the host s operating system to perform I O using the debugger For example printf statements executed in a program appear in the debugger command window When used in conjunction with the debugging tools the capability to perform I O on the host gives you more options when debugging and testing code For detailed information on using the low level I O functions see Appendix B Runtime Support Functions 5 5 Header Files 5 2 5 Limits float h and limits h The float h and limits h heade
128. ave on call register variables The following table summarizes how the code generator uses the TMS320C3x C4x registers and shows which registers are defined to be pre served across function calls Table 4 1 Register Use and Preservation Conventions Register Usage Preserved by Call RO Integer and float expressions No Scalar return values R1 Integer and float expressions No R2 R3 Integer and float expressions No R4 R5 Integer register variables Integer part preserved R6 R7 Float register variables Floating part preserved ARO AR1 Pointer expressions No AR2 Pointer expressions No AR3 Frame Pointer FP Yes AR4 AR7 Pointer register variables Yes IRO Extended frame offsets No IR1 Extended frame offsets No BK Integer expressions No RC RS RE Block structure copy No ST Status register No SP Stack pointer Yes DP Accessing globals big model only Yes in small model No in big model TMS320C4x Only R8 Integer register variables Integer part preserved R9 R11 Integer and float variables No Runtime Environment 4 11 Register Conventions 4 3 1 Register Variables Register variables are local variables or compiler temporaries defined to reside in a register rather than in memory Storing local variables in registers allows significantly faster access which improves the efficiency of compiled code Table 4 2 shows the registers that are reserved to store register vari ables Table 4 2 Registers Reserved for Reg
129. bly language modules you must use a prefix of _ for all objects that are to be accessible from C For example a C object named x is called _x in assembly language For identifiers that are to be used only in an assembly language module or modules any name that does not begin with a leading underscore may be safely used without conflicting with a C identifier Runtime Environment 4 23 Interfacing C With Assembly Language Any objector function declared in assembly thatis to be accessed or called from C must be declared with the global directive in the assembler This defines the symbol as external and allows the linker to resolve references to it Likewise to access a C function or object from assembly declare the C object with global This creates an undefined external reference that the linker will resolve Predefined Symbols The assembler has several predefined symbols that allow you to write assembly code that is compatible with the different runtime models You can conditionally assemble code corresponding to different models by using these symbols as control switches when you invoke the assembler with the appropriate options this happens automatically when you use cl30 Symbols Value Description TMS320C30 1 or0 1 if v30 option used TMS320C40 1 or0 1 if v40 option used REGPARM 1or0 1 if mr option used BIGMODEL 1or0 1 if mb option used An Example of an Assembly Language Function 4 24 Example 4 1 illu
130. bsection 5 2 13 page 5 11 div Idiv Syntax Defined in Description Example Alphabetical Summary of Runtime Support Functions div Idiv Division include lt stdlib h gt div_t div int numer long denom Idiv_t Idiv long numer long denom div c in rts src Two functions support integer division by returning numer divided by denom You can use these functions to get both the quotient and the remainder in a single operation The div function performs integer division The input arguments are inte gers the function returns the quotient and the remainder in a structure of type div_t The structure is defined as follows typedef struct int quot quotient Ey int rem remainder div_t The ldiv function performs long integer division The input arguments are long integers the function returns the quotient and the remainder in a structure of type Idiv_t The structure is defined as follows typedef struct long int quot quotient m f long int rem remainder xy ldiv_t If the division produces a remainder the sign of the quotient is the same as the algebraic quotient and the magnitude of the resulting quotient is the largest integer less than the magnitude of the algebraic quotient The sign of the re mainder is the same as the sign of numer Because ints and longs are equivalent types in TMS320C3x C4x C these functions are also equivalent int i 10 int j 3 div_t result
131. c Two functions work together to provide pseudorandom sequence generation D The rand function returns pseudorandom integers in the range 0 RAND_MAX For the TMS320C3x C4x C compiler the value of RAND_ MAX is 2147483646 231 2 J The srand function sets the value of the random number generator seed so that a subsequent call to the rand function produces a new sequence of pseudorandom numbers The srand function does not return a value If you call rand before calling srand rand generates the same sequence it would produce if you first called srand with a seed value of 1 If you call srand with the same seed value rand generates the same sequence of numbers Change Heap Size include lt stdlib h gt void realloc void ptr size_t size void realloc8 void _ptr size_t _ size void realloc16 void _ptr size_t size memory c in rts src The realloc function changes the size of the allocated memory pointed to by ptr to the size specified in bytes by size The contents of the memory space up to the lesser of the old and new sizes is not changed _ If ptr is 0 realloc behaves like malloc DD If ptr points to unallocated space the function takes no action and returns If the space cannot be allocated the original memory space is not changed and realloc returns 0 If size 0 and pir is not null realloc frees the space that ptr points to Runtime Support Functions 5 57 remove rename Alphabetic
132. cific Features typedef struct S int i j k s sval s p p gt j 5 p gt k 10 return p gt i KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK TMS320C30 C COMPILER Version X XX x ac30 v40 a4 c a4 if opt30 v40 02 a4 if a4 opt 7 cg30 v40 a4 opt a4 asm a4 tmp version 40 FP Set AR3 globl _ sval KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK FUNCTION DEF _sval ki _sval PUSH FP LDI SP FP AR2 assigned to parameter p LDA FP 2 AR2 STIK 5 AR2 1 MPYI 10 AR2 2 RO STI RO AR2 2 LDI AR2 RO EPIO_1 LDI FP 1 R1 BD R1 LDI FP FP OP SUB1 2 SP R1 BRANCH OCCURS end A 8 Description of Compiler Optimizations Expression simplification For optimal evaluation the compiler simplifies
133. code generator mode has a corresponding shell option that performs the same function The following table shows the shell options the code generator options and the corresponding functions Invoking the Tools Individually Table 2 6 Code Generator Options and Shell Options cg30 Option gb 9p gr0 gr1 or gr Shell Option Function enable the big memory model fast floating point to integer conversions disables RPTS instructions for loops uses RPTB use far calls for runtime support assembly calls enable short multiply C3x only re enable optimizations disabled by symbolic debugging perform speed optimizations at the cost of code size use standard stack runtime model use register argument runtime model assume all memory is accessible when optimiz ing specify silicon revision see msrev in shell generate Ada compatible frame structure generate Tartan C function names perform optimizations while generating interlist information enable symbolic debugging suppress progress messages quiet specify processor xx 30 31 32 40 or 44 default is v30 retain the input file t z tells the code generator to retain the input file the intermediate file created by the parser This option is useful for creating several output files with different options for example you might want to use the same intermediate file to create one file that contains symbolic debugging directives o
134. cond execution of strncpy stra begins with the phrase am followed by two spaces In the comments the notation 0 represents the null character char stra she s the one mother warned you of char strb he s char strc I am the one father warned you of char strd oops size_t length 5 strncpy stra strb length stra gt he s the one mother warned you of 0 strb gt he s 0 strc gt I am the one father warned you of 0 strd gt oops 0 x strncpy stra strc length stra gt I am the one mother warned you of 0 strb gt he s 0 strce gt I am the one father warned you of 0 strd gt oops 0 strncpy stra strd length stra gt oops 0 fs strb gt he s 0 a strc gt I am the one father warned you of 0 strd gt oops 0 EF Syntax Defined in Description Example Syntax Defined in Description Example Alphabetical Summary of Runtime Support Functions strpbrk strrchr Find Any Matching Character include lt string h gt char strpbrk char s1 char s2 strpbrk c in rts src The strpbrk function locates the first occurrence in s1 of any character in s2 If strpbrk finds a matching character it returns a pointer to that character otherwise it returns a null pointer 0 char stra
135. constant table from permanent storage in ROM to the global page in RAM The compiler accomplishes this by placing the data for the constant table in the cinit section and allocating space for the table itself bss Thus the table is automatically built into RAM through the autoinitialization process Note that the small memory model restricts the total size of the global data page to 64K words As with all autoinitialization you can avoid the extra use of memory required by the cinit section by using the cr linker option and a smart loader to per form the initialization directly from the object file For more information about autoinitialization refer to Section 4 8 on page 4 36 Register Conventions 4 3 Register Conventions Strict conventions associate specific registers with specific operations in the C environment If you plan to interface an assembly language routine to a C program it is important that you understand these register conventions The register conventions dictate both how the code generator uses registers and how values are preserved across function calls There are two types of register variable registers save on call and save on entry The distinction between these two types of register variable registers is the method by which they are preserved across calls It is the called function s responsibility to pre serve save on entry register variables and the calling function s responsibility to preserve s
136. creates a sysm8 or sysm16 section when a size is specified using the heap8 or heap16 option For more information refer to subsection 4 1 3 Dynamic Memory Allocation on page 4 4 Runtime Support Functions 5 51 mktime Alphabetical Summary of Runtime Support Functions Syntax Defined in Description Example 5 52 Convert to Calendar Time include lt time h gt time_t mktime struct tm timeptr mktime c in rts src The mktime function converts a broken down time expressed as local time into atime value of type time_t The timeptr argument points to a structure that holds the broken down time The function ignores the original values of tm_wday and tm_yday and does not restrict the other values in the structure After successful completion of time conversions tm_wday and tm_yday are set appropriately and the other components in the structure have values within the restricted ranges The final value of tm_mday is not sent until tm_mon and tm_year are determined The return value is encoded as a value of type time_t If the calendar time cannot be represented the function returns the value 1 This example determines the day of the week that July 4 2001 falls on include lt time h gt static const char const wday Sunday Monday Tuesday Wednesday Thursday Friday Saturday struct tm time_str time_str tm_year 2001 1900 time_str tm_mon time
137. ction converts an uppercase argument to lowercase If c The toupper function converts a lowercase argument to uppercase If c 5 77 va_arg va_end va_start Alphabetical Summary of Runtime Support Functions va_arg va_end va_start Syntax Defined in Description Example Variable Argument Macros Functions include lt stdarg h gt type va_arg ap type void va_end ap void va_start ap parmN va_list ap stdarg h as macros Some functions can be called with a varying number of arguments that have varying types Such functions called variable argument functions can use the following macros to step through argument lists at runtime The ap parameter points to an argument in the variable argument list QO m The va_start macro initializes ap to point to the first argument in an argu ment list for the variable argument function The parmN parameter points to the rightmost parameter in the fixed declared list The va_arg macro returns the value of the next argument in a call to a variable argument function Each time you call va_arg it modifies ap so that successive arguments for the variable argument function can be returned by successive calls to va_arg va_arg modifies ap to point to the next argumentin the list The type parameter is a type name it is the type of the current argument in the list The va_end macro resets the stack environment after va_start and va_arg are used Note that you must
138. d C statements as assembly language comments which show the optimized C statements The comments also include a list of the allocated register variables Note that occasionally the optimizer interlist comments may be misleading because of copy propagation or assignment of multiple or equivalent variables to the same register 2 4 4 Debugging Optimized Code The best way to debug code that is also optimized is to debug it in an unoptimized form and then reverify its correctness after it has been optimized 2 40 Using the C Compiler Optimizer The debugger may be used with optimized code but the extensive rearrange ment of code and the many to one allocation of variables to registers often makes it difficult to correlate source code with object code Note Symbolic Debugging and Optimized Code If you use the g option to generate symbolic debugging information many code generator optimizations are disabled because they disrupt the debugger If you want to use symbolic debugging and still generate fully optimized code use the mn option on cl30 mn re enables the optimizations disabled by g es 2 4 5 Special Considerations When Using the Optimizer asm Statements Volatile Keyword The optimizer is designed to improve your ANSI conforming C programs while maintaining their correctness However when you write code for the optimizer you should note the following special considerations to insure that your program performs as
139. d f is a function that returns a structure the caller can simply place the address of s in ARO and call f Function f then copies the return structure directly into s performing the assignment automatically You must be careful to properly declare functions that return structures both at the point where they are called so the caller properly sets up ARO and where they are defined so the function knows to copy the result The called function restores all saved registers It deallocates the local frame if necessary by subtracting its size from SP and restores the old FP by popping it It pops the return address and branches to it In functions with no saved registers this is performed by executing a RETS statement In other functions the compiler loads the return address into R1 and uses a delayed branch to return The delay slots are used to restore registers and deallocate the local frame Function Structure and Calling Conventions 4 4 4 Accessing Arguments and Local Variables A function accesses its stack arguments and local nonregister variables indirectly through the FP which always points to the bottom of the local frame Because the FP actually points to the old FP the first local variable is addressed as FP 1 Other local variables are addressed with increasing offsets up to a maximum of 255 Local objects with offsets larger than 255 are accessed by first loading their offset into an index register IRn and addres
140. d to suppress errors and error messages The examples use this 2 line code segment int pi char pc pi pc Ifyou invoke the code with the shell and q this is the result err err c line3 E104 operands of point to different types In this case because code E errors are fatal the compiler does not generate code Ifyou invoke the code with the shell and the pe option this is the result err err c line3 E104 operands of point to different types In this case the same message is generated but because pe is used the compiler ignores the error and generates an output file If you invoke the code with the shell and pe and pw this is the result err As in the previous case pe causes the compiler to overlook the error and generate code Because the pw option is used the message is sup pressed C Compiler Description 2 53 Intrinsics 2 8 Table 2 3 Supported Intrinsic Functions 2 54 Intrinsics The compiler supports nine intrinsic functions built in functions whose bodies are supplied by the code generator The supported intrinsics provide access to certain conversion and math instructions as described in Table 2 3 Function abs i labs l fabs f toieee f frieee f fast_ftoi f ansi_ftoi f fast_imult i fast_invf f Description Integer absolute value of i via ABSI instruction Long integer abso
141. del mr The use of the optimizer 02 and inline function expansion x options does not affect compatibility with code compiled without these options Runtime Support Functions 5 3 Header Files 5 2 Header Files Each runtime support function is declared in a header file Each header file declares the following D A set of related functions or macros Any types that you need to use the functions Any macros that you need to use the functions These are the header files that declare the runtime support functions assert h limits h stdio h ctype h math h stdlib h errno h setjmp h string h file h stdarg h time h float h stddef h In order to use a runtime support function you must first use the include preprocessor directive to include the header file that declares the function For example the isdigit function is declared by the ctype h header Before you can use the isdigit function you must first include ctype h include lt ctype h gt val isdigit num You can include headers in any order You must include a header before you reference any of the functions or objects that it declares Subsections 5 2 1 through 5 2 7 describe the header files that are included with the TMS320C3x C4x C compiler Section 5 3 page 5 13 lists the functions that these headers declare 5 2 1 Diagnostic Messages assert h 5 4 The assert h header defines the assert macro which inserts diagnostic failure messa
142. del of initialization 2 69 rts lib rts src 5 1 5 2 5 10 rts30 lib 2 35 2 66 rts30g lib rts30gr lib rts30r lib rts40 lib 2 35 rts40g lib rts40gr lib 2 35 rts40r lib 2 35 runtime environment 4 4 40 register ce ae 4 12 defining variables in assembl nguege function call conventions inline assembly nyu interfacing C with assen interrupt handling 4 3d 31 memory model dynamic memor RAM model 4 6 ROM model 4 6 sections precision considerations register considerations stack 4 4 system sca ee runtime model options runtime support libraries sf Bebe b 68 6 1 runtime support functions summary table 5 13 runtime support libraries s compiler option Index 10 allocation s linker option scanf function searches sections Ee text f SEEK COR macro SEEK_END macro SEEK_SET macro set file position functions fseek function fsetpos function setbuf function setjmp function setvbuf function shell program i option C_OPTION environment variable 2 28 enabling linking 2 13 keeping the assembly language file 2 12 overview suppressing the linking option 2 12 shift 3 3 sinh troton beal size_t type small memory model 2 20 software development tools 1 2 1 4 sorts 5 56 source file extensions assembler files C source files object files SP regi
143. dex ERANGE macro 5 5 errno h header 5 5 error indicators function mapping function error handling 2 54 2 53 B 22 using error options error message macros assert error messages code E code F code l code W general error options error reporting 5 5 errors treated as warnings escape sequences 3 2 exit function 5 22 exp function exponential math function expressions Ba C language external declarations 3 22 f compiler option fa f linker option fa file specifier fabs function as intrinsic far calls 3 20 fast_ftoi nei ped fast_imult intrinsic fast_invf intrinsic fatal errors fc file specifier fclose function feof function ferror function fflush function Index 3 Index fgetc function 5 38 fgetpos function fgets function file removal function 5 58 rename function 5 58 FILE data type 5 9 file extension ea option eo option file specifier options 2 14 e option f option file h header __FILE__ 2 31 filename generate function filename extensions filename specifications 2 4 FILENAME_MAX macro 5 9 flib lib float h header float40 section floating point math functions floating point remainder 5 39 floor function flush I O buffer function 5 37 Index 4 fmod function 5 39 fo file specifier option 2 15 fo
144. disrupt the C environment and cause a program to fail Figure 4 1 illustrates a typical function call In this example parameters are passed to the function and the function uses local variables On the Before Call stack SP points to the last saved register and FP points to the previous FP The Push Arguments stack displays the stack just before executing the first assembly instruction of the called function after the last instruction of the calling function The Allocate Local Frame stack displays the stack after all frame allocation On this stack SP points to the last saved register This example shows allocation of a local frame for the called function Functions that have no arguments passed on the stack and no local variables do not allo cate a local frame If you use the register argument model see Section 4 4 2 some or all of the arguments may be passed in registers rather than on the stack as shown Runtime Environment 4 15 Function Structure and Calling Conventions Figure 4 1 Stack Use During a Function Call Before Push Arguments Allocate CALL Call Function Local Frame YY ZZ Saved 4 SP Registers Old FP FP Return Address Argument 1 e o fo Argumentn Caller s Local Caller s Local Frame Frame 4 4 1 Function Call Standard Runtime Model In general a function performs the following tasks when it calls another function 1 The caller pushes the arguments on t
145. ditions Unreachable code is deleted branches to branches are bypassed and conditional branches over unconditional branches are simplified to a single conditional branch When the value of a condition can be determined at compile time through copy propagation or other data flow anal ysis a conditional branch can be deleted Switch case lists are analyzed in the same way as conditional branches and are sometimes eliminated entirely Some simple control flow constructs can be reduced to conditional instruc tions totally eliminating the need for branches See Example A 6 Description of Compiler Optimizations Example A 6 Copy Propagation and Control Flow Simplification fsm enum ALPHA BETA GAMMA OMEGA state ALPHA int input while state OMEGA switch state case ALPHA state input 0 BETA GAMMA break case BETA state inputt 0 GAMMA ALPHA break case GAMMA state inputt 0 GAMMA OMEGA break TMS320C40 C COMPILER Version X XX KKEKKKK KKK KK KKK KK KKK KK KKK KKK KK KKK KKK KK KKK KKK KEK KKK KKK KKKAKAKK KKK KKK KK KK F ac30 v40 a6 c a6 if 2 opt30 v40 02 a6 if a6
146. does not run as a separate pass Instead the optimizer inserts comments into the code indi cating how the optimizer has rearranged and optimized the code These com ments appear in the assembly language file as comments starting with Optimization makes normal source interlisting impractical because the optimizer extensively rearranges your program Therefore when you use the os option the optimizer writes reconstructed C statements The comments also include a list of the allocated register variables Note that occasionally the optimizer interlist comments may be misleading because of copy propagation or assignment of multiple or equivalent variables to the same register If the os option is specified and the optimizer o is not the option will be ignored and the following warning will be issued Optimizer comments requested optimization not run ignoring option os If the ss option is used with the optimizer o the original C source code is added to the assembly file by the interlist utility In this case to maintain a correspondence between the interlist comments and the code optimization and instruction scheduling will take place on a line by line basis roughly corresponding to the instructions between interlist comments If both the ss and os options are used the file generated contains the assembly code the original C source comments and the optimized source comments The s option will interlist opti
147. drivers the library also offers facilities to perform I O on a user specified device If there is not enough space on the heap for a C I O buffer buffered operations on the file will fail If a call to printf mysteriously fails this may be the reason Check the size of the heap To set the heap size use the heap option when linking For information on the heap option see the Linker Description chapter of the 7MS320C3x C4x Assembly Language Tools User s Guide For example given the following program in a file named main c include lt stdio h gt main FILE fid fid fopen myfile w fprintf fid Hello world n fclose fid printf Hello again world n Issuing the following shell command compiles links and creates the file main out cl30 main c z heap 400 1 rts lib o main out Executing main out under the debugger on a SPARC host accomplishes the following Opens the file myfile in the directory where the debugger was invoked 2 Prints the string Hello world into that file 3 Closes the file 4 Prints the string Hello again world in the debugger command window Overview of Low Level I O Implementation B 2 Overview of Low Level I O Implementation The code that implements I O is logically divided into layers high level low level and device level The high level functions are the standard C library of stream I O routines printf scanf fopen getc
148. e Generation Tools Getting Started Guide literature number SPRU119 describes how to install the TMS320C3x C4x assembly language tools and the C compiler Installation instructions are included for MS DOS Windows 3 x Windows NT Windows 95 SunOS Solaris and HP UX systems TMS320C3x C4x Assembly Language Tools User s Guide literature number SPRU035 describes the assembly language tools assembler linker and other tools used to develop assembly language code assembler directives macros common object file format and symbolic debugging directives for the C3x and C4x generations of devices TMS320C3x C Source Debugger User s Guide literature number SPRU053 tells you how to invoke the C3x emulator evaluation module and simulator versions of the C source debugger interface This book discusses various aspects of the debugger interface including window management command entry code execution data management and breakpoints It also includes a tutorial that introduces basic debugger functionality TMS320C4x C Source Debugger User s Guide literature number SPRU054 tells you how to invoke the C4x emulator and simulator ver sions of the C source debugger interface This book discusses various aspects of the debugger interface including window management com mand entry code execution data management and breakpoints It also includes a tutorial that introduces basic debugger functionality TMS320C
149. e MPY instructions for all integer multiplies Because the TMS320C4x MPYI instruction performs full 32 bit multiplication there is no MPY_140 function Because the TMS320C3x C4x has no division instructions integer and floating point division are performed via calls to additional runtime support functions named DIV_I30 and DIV_F30 or DIV_I40 and DIV_F40 for the TMS320C4x Another function MOD_I30 performs the integer modulo operation Corresponding functions named DIV_U30 and MOD_U30 are used for unsigned integer division and modulo Like MPY_1I30 these functions take their arguments from RO and R1 and return the result in RO These functions differ for the TMS320C3x and the TMS320C4x because the C4x division func tions take advantage of the RCPF instruction 16 bit reciprocal Runtime Support Arithmetic Routines There are three runtime support arithmetic functions specifically for extended precision arithmetic MPY_LD multiply DIV_LD divide and INV_LD inverse reciprocals These functions support the 40 bit long double data type The runtime support arithmetic functions can use expression registers without saving them Each function has individual register use conventions and the compiler respects these conventions Register use is fully documented in the source to each of the functions The arithmetic functions are written in assembly language Because of the special calling conventions these functions use you canno
150. e const char old const char new lowlev c in rts src Renames the file pointed to by old The new name is pointed to by new Syntax Defined in Description Syntax Defined in Description Syntax Defined in Description Alphabetical Summary of Runtime Support Functions rewind scanf setbuf Position File Position Indicator to Beginning of File include lt stdio h gt void rewind register FILE iop rewind c in rts src Sets the file position indicator for a stream to the beginning of the file The file is pointed to by iop Read Stream From Standard Input include lt stdio h gt int scanf const char format fscanf c in rts src Reads from the stream from the standard input device How to read the stream is described by a string pointed to by format Specify Buffer for Stream include lt stdio h gt void setbuf register FILE iop char buf setbuf c in rts src Specifies the buffer used by the stream pointed to by iop If buf is set to null buffering is turned off No value is returned Runtime Support Functions 5 59 setjmp longjmp Alphabetical Summary of Runtime Support Functions setjmp longjmp Syntax Defined in Description Example Nonlocal Jumps include lt setjmp h gt int setjmp jmp_buf env void longjmp jmp_buf env int returnval setjmp asm in rts src The setjmp h header defines one type one macro and one function for bypassing the normal function
151. e listing An output file created by the assembler that lists the symbols that were defined what line they were defined on which lines referenced them and their final values data One of the default COFF sections The data section is an initialized section that contains initialized data You can use the data directive to assemble code into the data section directive Special purpose commands that control the actions and functions of a software tool as opposed to assembly language instructions which control the actions of a device environment variables System symbols that you define and assign to a string They are usually included in various batch files for example in AUTOEXEC BAT entry point The starting execution point in target memory executable module An object file that has been linked and can be executed in a TMS320 system Glossary expression A constant a symbol or a series of constants and symbols separated by arithmetic operators field For the TMS320 a software configurable data type whose length can be programmed to be any value in the range of 1 16 bits global A kind of symbol that is either 1 defined in the current module and accessed in another or 2 accessed in the current module but defined in another high level language debugging The ability of a compiler to retain symbolic and high level language information such as type and function definitions so that a debugging tool can use t
152. e space is an optional sign and then digits that represent the integer portion of the number The fractional part of the number follows then the exponent including an optional sign The first character that cannot be part of the number terminates the string Since int and long are functionally equivalent in TMS320C3x C4x C the atoi and atol functions are also functionally equivalent The functions do not handle any overflow resulting from the conversion Example int i double d i atoi 3291 i 3291 d atof 1 23e 2 d 0123 Syntax Defined in Description Alphabetical Summary of Runtime Support Functions bmalloc Allocate Memory on a Boundary include lt stdlib h gt void bmalloc size _ size void bmalloc8 size _ size void bmalloc16 size_t_ size memory c in rts src The bmalloc function allocates space for an object of size bytes and returns a pointer to the space The packet of the given size is aligned on a boundary suitable for TMS320C3x and TMS320C4x circular buffers and bit reversed address buffers See the TMS320C3x User s Guide for information on circular buffers and bit reversed addressing The memory that bmalloc uses is in a special memory pool or heap defined in an uninitialized named section called sysmem in memory c The linker sets the size of this section from the value specified by the heap option Default heap size is 1K words For the TMS320C32 proces
153. e state ments into the compiler s assembly language output For more information see Section 2 6 page 2 49 invokes the interlist utility which interlists C source state ments into the compiler s assembly language output For more information see Section 2 6 page 2 49 undefines the predefined constant name Overrides any d options for the specified constant specifies the target processor Choices are v30 for a TMS320C30 processor v31 for a TMS320C31 processor v32 for a TMS320C32 processor DD v40 for a TMS320C40 processor v44 for a TMS320C44 processor By default the tools produce code for the C30 processor You must specify the appropriate option to generate code for the C31 C32 C40 or C44 All code used in the eventual executable module including all library resident code must be compiled under the same version For more information refer to Section 2 3 on page 2 35 enables the linking option It causes the shell to run the link er on specified object files The z option and its parameters follow all other compiler options and source files on the command line All arguments that follow z on the command line are passed to and interpreted by the linker For more information refer to subsection 2 10 1 on page 2 65 C Compiler Description 2 13 Compiling C Code File Specifiers 2 14 e allowsyouto changethe default naming conventions forfile extensions
154. e substituted for the macro call and are subsequently assembled map file An output file created by the linker that shows the memory configuration section composition and section allocation as well as symbols and the addresses at which they were defined member The elements or variables of a structure union archive or enumeration memory map A map of TMS320 target system memory space which is partitioned off into functional blocks object file A file that has been assembled or linked and contains machine language object code object library An archive library made up of individual object files operand The arguments or parameters of an assembly language instruction assembler directive or macro directive options Command parameters that allow you to request additional or specific functions when you invoke a software tool Glossary output module Alinked executable object file that can be downloaded and executed on a target system output section A final allocated section in a linked executable module protected mode Thirty two bit extended DOS mode These programs re quire an extended memory manager and will run only on larger proces sors 386 or better They can utilize all the available RAM on the com puter RAM model An autoinitialization model used by the linker when linking C code The linker uses this model when you invoke the linker with the cr option The RAM model allows variables to be i
155. eclares one macro several types and functions that manipulate dates and times Times are represented in two different ways m As an arithmetic value of type time_t When expressed in this way a time is represented as a number of seconds since 12 00 AM January 1 1900 The time_t is a synonym for the type unsigned long As a structure of type struct_tm This structure contains members for expressing time as a combination of years months days hours minutes and seconds A time represented like this is called broken down time The structure has the following members int tm_sec seconds after the minute 0 59 int tm_min minutes after the hour 0 59 int tm_hour hours after midnight 0 23 ki int tm_mday day of the month 1 31 a int tm_mon months since January 0 11 int tm_year years since 1900 0 99 af Int tm_wday days since Saturday 0 6 ai int tm_yday days since January 1 0 365 int tm_isdst Daylight Savings Time flag Runtime Support Functions 5 11 Header Files 5 12 A time whether represented as a time_t or a struct tm can be expressed from different points of reference D Calendar time represents the current Gregorian date and time 4 Local time is the calendar time expressed for a specific time zone Local time may be adjusted for daylight savings time Obviously local time depends on the time zone The time h header declares a structure type called tmz
156. ect remember to remove the underscore Interfacing C With Assembly Language eS ee CO sFee6h Note Use the mf Option When Using the Optimizer The optimizer by default assumes that all variables are defined in the bss section As aresult of this assumption the optimizer is free to change indirect memory accesses to direct ones if it is more efficient to do so If you are accessing a variable that is not defined in bss this assumption is invalid Use the mf option to force the optimizer to preserve indirect memory access Example 4 3 shows an example for accessing a variable that is not defined in bss Example 4 3 Accessing a Variable Not Defined in bss From C a Assembly Language Program global _sine Declare variable as external Sect sine tab Make a separate section _sine The table starts here float 0 0 float 0 015987 float 0 022145 b C Program extern float sine This is the object float sine_p sine Declare pointer to it f sine_p 4 Access sine as normal array A reference such as sine 4 will not work because the object is not in bss and because a direct reference such as this generates incorrect code Alternatively the following can be used in C extern float sine float sine_p amp sine f sine_p 4 or the following can be used in the assembly program
157. ed function sets up the local frame The local frame is allocated in the following way a The old frame pointer is saved on the stack b The new frame pointer is set to the current SP c The frame is allocated by adding its size to the SP Runtime Environment 4 19 Function Structure and Calling Conventions 4 20 2 If the called function modifies any of the following registers it must save them on the stack Save as integers Save as floating point R4 R5 R6 R7 AR4 AR5 AR6 AR7 FP DP small model only R8 C4x only The called function may modify any other registers without saving them The called function executes its code If the function returns an integer pointer or float it places the return value in RO In the modified register argument calling convention used for runtime support assembly files page 4 18 pointers are returned in ARO If the function returns a structure the caller allocates space for the structure and then passes the address of the return space to the called function in register ARO To return a structure the called function then copies the structure to the memory block that ARO points to If the caller does not use the return value ARO is set to 0 This directs the called function not to copy the return structure In this way the caller can be smart about telling the called function where to return the structure For example in the statement s f where sis a structure an
158. ed in ARO 4 3 4 Stack and Frame Pointers The TMS320C3x C4x C compiler uses a conventional stack mechanism for allocating local automatic variables and passing arguments to functions When a function requires local storage it creates its own working space local frame from the stack The local frame is allocated during the function s entry sequence and deallocated during the return sequence Two registers the stack pointer SP and the frame pointer FP manage the stack and the local frame The SP is a TMS320C3x C4x register dedicated to managing the stack The compiler uses SP in the conventional way the stack grows toward higher addresses and the stack pointer points to the top location highest memory on the stack Register AR3 is dedicated as the frame pointer FP The FP points to the beginning or bottom of the local frame for the current function All objects stored in the local frame are referenced indirectly through the FP Both the FP and the SP must be preserved across function calls The function calls automatically preserve the SP because everything pushed for the call is popped on return The FP is preserved as a specific part of a function s entry and exit sequence For more information about stack and frame pointer use during function calls refer to Section 4 4 Function Structure and Calling Connections page 4 15 Runtime Environment 4 13 Register Conventions 4 3 5 Other Registers 4 14 Other registers
159. efine REGS 6 2 2 2 include File Search Paths 2 32 The include preprocessor directive tells the compiler to read source statements from another file The syntax for this directive is include filename or include lt filename gt The filename names the include file that the compiler reads statements from You can enclose the filename in double quotes or in angle brackets The filename can be acomplete pathname have partial path information or have no path information Ifyou enclose the filename in double quotes the compiler searches for the file in the following directories in the order given 1 The directory that contains the current source file The current source file refers to the file that is being compiled when the compiler encounters the include directive 2 Any directories named with the i compiler option in the shell 3 Any directories set with the environment variable C_DIR 1 If you enclose the filename in angle brackets the compiler searches for the file in the following directories in the order given 1 Any directories named with the option in the shell 2 Any directories set with the environment variable C_DIR Note that if you enclose the filename in angle brackets the compiler does not search for the file in the current directory Include files are sometimes stored in directories You can augment the compiler s directory search algorithm by using the i shell option
160. efined as inline are expanded when the optimizer is invoked and the x option is not equal to x0 Setting the x option to x2 will automatically invoke the optimizer at the default level level 2 C Compiler Description 2 43 Function Inlining static inline return type function name parameter declarations 2 44 E Method 2 By declaring a function as static inline you can specify that the function is inlined in the present module This names the function and specifies that the function is to be expanded inline but no code is generated for the function declaration itself Functions declared in this way may be placed in header files and included by all source modules of the program Declaring a function as static inline in a header file specifies that the function is inlined in any module that includes the header Functions declared as inline are expanded whenever the optimizer is invoked at any level Functions declared as inline and controlled by the _INLINE preprocessor symbol such as the runtime library func tions are expanded whenever the optimizer is invoked and the _INLINE preprocessor symbol is equal to 1 When you define an inline function it is recommended that you use the _INLINE preprocessor symbol to control its declaration If you fail to control the expansion using _INLINE and subsequently compile without the optimizer the call to the function will be unresolved For more information see subsection 2 5 3
161. emory accordingly no runtime initialization is performed at boot time Instead when the program is loaded into memory the loader must detect the presence of the cinit section and its special attribute Instead of loading the section into memory the loader uses the initialization tables directly from the object file to initialize the variables in bss To use the RAM model the loader must understand the format of the initialization tables so that it can use them System Initialization A loader is not part of the compiler package The loader used in TI emulator and simulator products is a smart loader Figure 4 4 RAM Model of Autoinitialization Object File Memory bss section Initializing Variables in the ROM Model The ROM model is the default model for autoinitialization To use the ROM model invoke the linker with the c option Under this method the cinit section is loaded into memory possibly ROM along with all the other sections and global variables are initialized at runtime The linker defines a special symbol called cinit that points to the beginning of the initialization tables in memory When the program begins running the C boot routine copies data from the tables pointed to by cinit into the specified variables in bss This allows initialization data to be stored in ROM and then copied to RAM each time the program is started Runtime Environment 4 39 System Initialization Figure 4 5 ROM M
162. enabled and the prototype declared as static inline only if _INLINE is true that is the module including this header is compiled with the x option The second definition in memcpy c is for the library so that the callable version of memcpy exists when inlining is disabled Since this is not an inline function the _INLINE symbol is undefined undef before including string h so that the non inline version of memcpy s prototype is generated C Compiler Description 2 47 Function Inlining 2 48 If the application is compiled with the x option and the string h header is included all references to memcpy in the runtime support library will be inlined and the linker will not have to use the memcpy in the runtime support library to resolve any references Any modules that call memcpy that are not compiled with inlining enabled will generate calls that the linker resolves by getting the memcpy code out if the library You will want to use the _INLINE preprocessor symbol in the same way so that your programs will run regardless of whether inlining mode is selected for any or all of the modules in your program Using the Interlist Utility 2 6 Using the Interlist Utility The compiler package includes a utility that interlists your original C source statements into the assembly language output of the compiler The interlist utility enables you to inspect the assembly code generated for each C statement The easiest way to invoke t
163. enerator Assembler Source Executable COFF File 2 2 Compiling C Code 2 1 1 Invoking the C Compiler To run the compiler enter cl30 options filenames z link_options object files cl30 is the command that invokes the compiler and the assembler options affect the way the compiler processes input files filenames are one or more C source files assembly source files or object files zZ is the option that runs the linker link_options control the linking process object files name the object files that the compiler creates Options control how the compiler processes files and the filenames provide a method of identifying source files intermediate files and output files Options and filenames can be specified in any order on the command line However the z option and its associated information must follow all filenames and compiler options on the commandline For example if you wanted to com pile two files named symtab and file assemble a third file named seek asm and use the quiet option q you would enter c130 q symtab file seek asm As cl30 encounters each source file it prints the filename in square brackets for C files or angle brackets lt for asm files gt The example above uses the q option to suppress the additional progress information that cl30 produces Entering the command above produces symtab file lt seek asm gt C Compiler Descripti
164. ess z so do not use them if you want to link For all arguments that follow z on the command line the shell generates a linker command file containing the arguments The shell passes the command file to the linker In this way you are not limited by command line size restric tions The arguments can be other linker command files object files linker op tions or libraries For example to compile and link all the c files in a directory enter cl30 sq c z c cmd 0 prog out L rts30 lib The shell will call the compiler using the s and q options to compile all of the files in the current directory that end with a c extension Because z is specified the shell will generate a command file containing all of the argu ments following the z option and then invoke the linker with this command file The linker will link together all of the object files produced during compilation the runtime support library and any additional files specified in c cmd The resulting linked file will be named prog out The order in which the linker processes arguments can be important especially for command files and libraries The cl30 shell passes arguments to the linker in the following order 1 Object file names from the command line 2 Arguments following z on the command line 3 Arguments following z from the C_OPTION environment variable Cc and n Shell Options You can override the z option by using the c or n shell o
165. expression Like all addresses of static objects this address must be stored in the constant table in order to be accessed Thus in addition to storing the string itself in the const section the compiler uses the following directive statement to store the string s address in the constant table word SLn If the same string is used more than once within a source module the string will not be duplicated in memory All uses of an identical string constant share a single definition of the string Because strings are stored in the const section possibly in ROM and shared it is bad practice for a program to modify a string constant The following code is an example of incorrect string use n char a abc all x Incorrect mr Object Representation 4 2 5 The Constant Table The constant table contains definitions of all the objects that the compiler must access but are too wide to be used as immediate operands Such objects include DD integer constants that are wider than 16 bits floating point constants that have exponents larger than 4 bits or mantissas larger than 11 bits J integer local variable initializers wider than 16 bits floating point local variable initializers with exponents larger than 4 bits or mantissas larger than 11 bits addresses of global variables addresses of string constants The constant table is simply a block of memory that contains all such objects
166. ey can appear as either a statement or a declaration even out side blocks This is particularly useful for inserting directives at the very begin ning of a compiled module _ s o oS ee Note Avoid Disrupting the C Environment With asm Statements Be extremely careful not to disrupt the C environment with asm statements The compiler does not check the inserted instructions Inserting jumps and labels into C code can cause unpredictable results in variables manipulated in or around the inserted code Directives that change sections or otherwise affect the assembly environment can also be troublesome Be especially careful when you use the optimizer with asm statements Although the opti mizer cannot remove asm statements except where such statements are totally unreachable it can significantly rearrange the code order near asm statements possibly causing undesired results The asm command is pro vided so that you can access features of the hardware which by definition C is unable to access aNNNmy N wTe Saas TMS320C3x C4x C Language 3 17 Initializing Static and Global Variables 3 7 Initializing Static and Global Variables The ANSI C standard specifies that static and global variables without explicit initializations must be specifically initialized to zero before the program begins running This task is typically done when the program is loaded Because the loading process depends heavily on the specific environment of the
167. f mi 02 X rts30g lib TMS320C3x mf mi 02 x g rts30r lib TMS320C3x mf mi 02 x mr rts30gr lib TMS320C3x mf mi 02 x g mr rts40 lib TMS320C4x v40 mf mi 02 X rts40g lib TMS320C4x v40 mf mi 02 x g rts40r lib TMS320C4x v40 mf mi 02 x mr rts40gr lib TMS320C4x v40 mf mi 02 x g mr rts src is the source library If necessary you can create your own runtime support library from rts src by using the library build utility mk30 described in Chapter 6 All object libraries built from rts src include the standard C runtime support functions described in this chapter the intrinsic arithmetic routines described in Section 4 7 on page 4 32 and the system startup routine _c_int00 The object libraries are built from the C and assembly source contained in rts src When you link your program you must specify an object library as one of the linker input files so that references to runtime support functions can be resolved You should usually specify libraries ast on the linker command line because the assembler searches for unresolved references when it encounters a library onthe commandline You can also use the x linker option to force repeated searches of each library until it can resolve no more references When alibrary is linked the linker includes only those library mem bers required to resolve undefined references For more information about
168. f the runtime library with the library build utility mk30 See Chapter 6 for more information on using this utility By default the mk30 utility will create a runtime support library called rts lib However if you use more than one library you may wish to adopt a naming convention that makes it obvious which models were used For example append a suffix that contains the target CPU number 30 or 40 an r for the register argument model and a b for the big model Thus rts40rb lib would be easily recognized as the runtime support library for the TMS320C4x big model with the register argument runtime model and rts30 lib would be for the TMS320C3x small model and stack based or standard runtime model 2 3 1 The Big and Small Memory Models The small memory model default requires that all external variables global variables static variables and compiler generated constants in the program after linking fit into a single 64K word long data page 65536 words This allows the compiler to access any of these objects without modifying the data page pointer DP register Neither model restricts the size of code automatic data or dynamically allocated data The big model mb option removes the 64K restriction However this model also forces the compiler to reload the data page pointer before accessing any external variables or compiler generated constants This is less efficient since it forces an extra instruction and poss
169. fails The C I O Functions B 7 OPEN Alphabetical Summary of C I O Functions Syntax Description Return Value Open File or Device For I O int OPEN char path unsigned flags int mode The OPEN function opens the device or file specified by path and prepares it for I O information The path is the filename of the file to be opened including path The flags are attributes that specify how the device or file is manipulated The flags are specified using the following symbols O RDONLY 0x0000 O_WRONLY 0x0001 O_RDWR Ox0002 O APPEND 0x0008 O_CREAT Ox0100 O TRUNC 0x0200 O BINARY 0x8000 open for reading open for writing open for read amp write append on each write open with file create open with truncation open in binary mode These parameters can be ignored in some cases depending on how data is interpreted by the device Note however that the high level I O calls look at how the file was opened in an fopen statement and prevent certain actions depending on the open attributes J The mode is required but ignored The function returns one of the following values stream number assigned by the low level routines that the device level driver associates with the opened file or device if successful lt 0 iffails Syntax Description Return Value Syntax Description Return Value Alphabetical Summary of C I O Functions REA
170. following lines bss _var 1 Define the variable global _var Declare it as external b C Program extern int var External variable E var 1 Use the variable Accessing Variables Not Defined in the bss Section 4 26 It is more difficult to access a variable from C when the variable is not defined inthe bss section andyou are using the small memory model andthe variable is not allocated on the same data page as the bss sections generated by the compiler Note that using the big memory model causes the compiler to load the data page pointer prior to each direct memory access to variables therefore the following method is not needed Consider a lookup table defined in assembly that you do not want to put in RAM In this case you must define a pointer to the object and access it indirectly from C The first step is to define the object You can define the object in its own section either initialized or uninitialized or you can define it in an existing section After defining the object declare a global label that points to the beginning of the object If the object has its own section it can easily be linked anywhere into the memory space this task is a little more difficult if the object is sharing an exist ing section To access it in C you must declare an additional C variable to point to the object Initialize the pointer with the assembly language label declared for the obj
171. ge by other means In this example an integer i is divided by another integer j Since dividing by Ois an illegal operation the example uses the assert macro to test j before the division If j 0 when this code runs a message such as Assertion failed j file foo c line 123 is sent to standard output int irp SF assert j q i j Syntax Defined in Description Example Syntax Defined in Description Example Syntax Defined in Description Alphabetical Summary of Runtime Support Functions atan atan2 atexit Polar Arc Tangent include lt math h gt double atan double x atan c in rts src The atan function returns the arc tangent of a floating point argument x The return value is an angle in the range 70 2 70 2 radians double realval radians realval 1 07 radians atan realval return value T 4 Cartesian Arc Tangent include lt math h gt double atan2 double y x atan c in rts src The atan2 function returns the arc tangent of y x The function uses the signs of the arguments to determine the quadrant of the return value Both arguments cannot be 0 The return value is an angle in the range 7 71 radians atan2 1 0 1 0 returns 7 4 atan2 1 0 1 0 returns 37 4 atan2 1 0 1 0 returns 1 4 atan2 1 0 1 0 returns 31 4 Exit Without Arguments include lt stdlib h gt void atexit void fun void exit c in rts
172. ges into programs at runtime The assert macro tests a runtime expression Lj Ifthe expression is true nonzero the program continues running j Ifthe expression is false the macro outputs a message that contains the expression the source file name and the line number of the statement that contains the expression then the program terminates via the abort function The assert h header refers to another macro named NDEBUG assert h does not define NDEBUG If you have defined NDEBUG as a macro name when you include assert h then assert is turned off and does nothing If NDEBUG is not defined assert is enabled Header Files 5 2 2 Character Typing and Conversion ctype h The ctype h header declares functions that test and convert characters For example a character typing function may test a character to determine whether it is a letter a printing character a hexadecimal digit etc These functions return a value of true a nonzero value or false 0 The character conversion functions convert characters to lower case upper case or ASCII and return the converted character Character typing functions have names in the form isxxx for example isdigit Character conversion functions have names in the form toxxx for example toupper The ctype h header also contains macro definitions that perform these same operations the macros run faster than the corresponding functions The typing macros expand to a lookup oper
173. global _sine _sine usect sine_tab 4 or global _ sine bss _sine 4 In the last case use the C method only if the bss section generated by the assembler is not allocated by the linker on the same data page as the bss output section generated by the compiler Runtime Environment 4 27 Interfacing C With Assembly Language Accessing Assembly Language Constants You can define global constants in assembly language by using the set and global directives or in a linker command file using a linker assignment statement These constants are accessible from C but itis not straightforward For normal variables defined in C or assembly language the symbol table contains the address of the value of the variable For assembler constants however the symbol table contains the value of the constant The compiler cannot tell which items in the symbol table are values and which are addresses If you try to access an assembler or linker constant by name the compiler attempts to fetch a value from the address represented in the symbol table To prevent this unwanted fetch you must use the amp address of operator to get the value In other words if _x is an assembly language constant its value in Cis amp x You can use casts and defines to ease the use of these symbols in your pro gram as in Example 4 4 Example 4 4 Accessing an Assembly Language Constant From C 4 5 3 4 28 a Assembly Language Program
174. gned to point to the strings shown in the comments In the comments the notation O represents the null character cher a b cz a gt The quick black fox 0 Ly b gt jumps over 0 Al c gt the lazy dog 0 ay strcat a b a gt The quick black fox jumps over 0 ay strcat a c a gt The quick black fox jumps over the lazy dog 0 Runtime Support Functions 5 63 strchr strcmp strcoll Syntax Defined in Description Example strcmp strcoll Syntax Defined in Description Example Alphabetical Summary of Runtime Support Functions Find First Occurrence of a Character include lt string h gt char strchr char s char c strchr c in rts src The strehr function finds the first occurrence ofc ins If strchr finds the charac ter it returns a pointer to the character otherwise it returns a null pointer 0 The sirchr function is expanded inline if the x option is used char a When zz comes home th char b char the_z search is on for z s Ea b strchr a the_z After this example b points to the first z in zz String Compare include lt string h gt int stremp char s1 char s2 int strcoll char s1 char s2 strcmp c in rts src The strcmp and strcoll functions compare s2 with s1 The functions are equivalent both functions are supported to provide compatibility with ANSI C The strcm
175. grams in a single step For more information refer to Section 2 1 on page 2 2 Introduction 1 5 TMS320C3x C4x C Compiler Overview Flexible Assembly Language Interface The compiler has straightforward calling conventions allowing you to easily write assembly and C functions that call each other For more information refer to Chapter 4 Runtime Environment Integrated Preprocessor COFF Object Files ROM able Code The C preprocessor is integrated with the parser allowing for faster compilation Standalone preprocessing or preprocessed listing is also available For more information refer to Section 2 2 on page 2 30 Common object file format COFF allows you to define your system s memory map at link time This maximizes performance by enabling you to link C code and data objects into specific memory areas COFF also provides rich support for source level debugging For standalone embedded applications the compiler enables you to link all code and initialization data into ROM allowing C code to run from reset Source Interlist Utility The compiler package includes a utility clist that interlists your original C source statements into the assembly language output of the compiler This utility provides you with an easy method for inspecting the assembly code gen erated for each C statement For more information refer to Section 2 6 on page 2 49 32 Bit and 40 Bit Data Sizes Library Build Utility Data sizes char
176. har and so on These routines map an I O request to one or more of the I O commands that are handled by the low level routines The low level routines are comprised of basic I O functions OPEN READ WRITE CLOSE LSEEK RENAME and UNLINK These low level routines are declared in file h and provide the interface between the high level functions and the device level drivers that actually perform the I O command on the specified device The low level functions also define and maintain a stream table that associates a file descriptor with a device The stream table interacts with the device table to ensure that an I O command performed on a stream executes the correct device level routine The data structures interact as shown in Figure B 14 Figure B 1 Interaction of Data Structures in I O Functions Stream table Device table file_descriptor1 open read p eee file_descriptor2 open read p eee The C I O Functions B 3 Overview of Low Level I O Implementation The first three streams in the stream table are predefined to be stdin stdout and stderr and they point to the host device and associated device drivers Figure B 2 The First Three Streams in the Stream Table Stream table Device table file_descriptor1 gt open file_descriptor2 Host read file_descriptor3 gt ees open read p eee At the next level are the user definable device level drivers They
177. have C functions that are called by hand coded assembly instead of main The FUNC_EXT_CALLED pragma specifies to the optimizer to keep these C functions or any other functions that these C functions call These functions act as entry points into C The pragma must appear before any declaration or reference to the function that you want to keep The syntax of the pragma is pragma FUNC EXT CALLED func The argument funcis the name of the C function that you do not want removed 3 5 5 The FUNC_IS PURE Pragma 3 14 The FUNC_IS_PURE pragma specifies to the optimizer that the named func tion has no side effects This allows the optimizer to do the following DD Delete the call to the function if the function s value is not needed DD Delete duplicate functions The pragma must appear before any declaration or reference to the function The syntax of the pragma is pragma FUNC_IS_ PURE func The argument func is the name of a C function Pragma Directives 3 5 6 The FUNC_IS SYSTEM Pragma The FUNC_IS_ SYSTEM pragma specifies to the optimizer that the named function has the behavior defined by the ANSI standard for a function with that name The pragma must appear before any declaration or reference to the function that you want to keep The syntax of the pragma is pragma FUNC_IS_ SYSTEM func The argument func is the name of the C function to treat as an ANSI standard functi
178. he arctangent of x double atan2 double y double x Returns the arctangent of y x double ceil double x T Returns the smallest integer greater than or equal to x double cos double x Returns the cosine of x double cosh double x Returns the hyperbolic cosine of x double exp double x Returns the exponential function of x double fabs double x Returns the absolute value of x double floor double x t Returns the largest integer less than or equal to x double fmod double x double y t Returns the floating point remainder of x y Tt Expands inline if x is used Macro Expands inline unless x0 is used 5 14 Floating Point Math Functions continued double double double double double double double double double double double frexp double value int exp Idexp double x int exp log double x log10 double x modf double value int iptr pow double x double y sin double x sinh double x sqrt double x tan double x tanh double x Variable Argument Functions and Macros stdarg h type void void va_arg va_list ap va_end va_list ap t va_start va_list ap MO Functions stdio h void clearerr FILE p int fclose FILE iop int feof FILE p int ferror FILE p int fflush register FILE iop int fgetc register FILE fp int fgetpos FILE iop fpos_t pos char fgets char ptr register int size register FILE iop FILE fopen const
179. he code generator may inline many commonly used functions such as MPY_130 to save the overhead of a function call uses the register argument model Code compiled under this model is completely incompatible with code compiled under the default model All code used in the eventual executable module including all library resident code must be compiled under the same model For more information refer to Section 2 3 on page 2 35 assumes all memory is accessible when optimizing The ms option causes the code generator to assume that no access to memory will cause the bus to block See Section 3 9 on page 3 21 causes the compiler to generate code that supports the Tartan Ada function calling conventions generates an additional header for every C function compiled allowing it to be used with the Tartan LAJ function calling method Calling functions compiled with the TMS320C3x C4x compiler from within Tartan compiled code will exact a penalty of two cycles per call but still allows some compatibility with existing Tartan assembly code and libraries This option may be removed in a future release so the legacy Tartan code should be recompiled Assembler Options Linker Options Compiling C Code aa invokes the assembler with the a option which creates an absolute listing An absolute listing shows the abso lute addresses of object code adname def predefines the constant name for the assembler This is equivalent to
180. he full weekday name sb the abbreviated month name Jan Feb B_ the locale s full month name se the date and time representation sd the day of the month as a decimal number 0 31 H the hour 24 hour clock as a decimal number 00 23 I the hour 12 hour clock as a decimal number 01 12 sj the day of the year as a decimal number 001 366 sm the month as a decimal number 01 12 mM the minute as a decimal number 00 59 sp the locale s equivalent of either A M or P M ss the second as a decimal number 00 50 sU the week number of the year Sunday is the first day of the week as a decimal number 00 52 Syntax Defined in Description Example Sx SX sy SY SZ Alphabetical Summary of Runtime Support Functions strlen the date representation the time representation the year without century as a decimal number 00 99 the year with century as a decimal number the time zone name or by no characters if no time zone exists For more information about the functions and types that the time h header de clares refer to subsection 5 2 13 page 5 11 Find String Length include lt string h gt size_t strlen char s strlen c in rts src The strlen function returns the length of s In C a character string is terminated by the first byte with a value of 0 a null character The returned result does not include the terminating null character The strlen function is expanded in line if
181. he interlist utility is to use the ss shell option To compile and run the interlist utility on a program called function c enter cl130 ss function 2 6 1 Using the Interlist Utility Without the Optimizer The interlist utility runs as a separate pass between the code generator and the assembler It reads both the assembly and C source files merges them and writes the C statements into the assembly file as comments surrounded by dashes such as The output assembly file function asm is assembled normally The ss option automatically prevents the cl30 shell from deleting the interlisted assembly language file as if you had used k Example 2 2 shows a typical interlisted assembly file Example 2 2 An Interlisted Assembly Language File KKK KK KK KKK KKK KKKKKK KKK KKK KKK KKK KAKA KKKAKKKKKK FUNCTION NAME _main _main 7 2 6 main 7 7 8 int i J 7 PUSH FP LDI SP FP ADDI 2 SP 7 A 10 i j 7 LDI FP 2 RO ADDI RO FP 1 R1 STI R1 FP 1 7 11 Li 1233 7 ADDI 123 R1 STI R1 FP 2 C Compiler Description 2 49 Using the Interlist Utility 2 6 2 Using the Interlist Utility With the Optimizer If the os option is used with the optimizer o the interlist utility
182. he stack in reverse order the right most declared argument is pushed first and the leftmost is pushed last This places the leftmost argument at the top of the stack when the function is called 2 The caller calls the function 3 When the called function is complete the caller pops the arguments off the stack with the following instruction SUBI n SP nis the number of argument words that were pushed 4 16 Function Structure and Calling Conventions 4 4 2 Function Call Register Argument Runtime Model In general when the register argument model is in use a function performs the following tasks when it calls another function 1 Six registers AR2 R2 R3 RC RS and RE are used to pass arguments as follows m The first two left most floating point float double or long double arguments are passed in R2 and R3 m Theremaining integer or pointer arguments are passed in the remain ing registers in the above list in order Note that structures and unions can be passed by address as an integer argument All arguments that are not assigned to registers either because of type incompatibility or because all registers have been exhausted are pushed onto the stack in reverse order right to left A seventh register ARO may be used to return structures and unions by address In Figure 4 2 several function prototypes are shown with the location of each argument indicated to illustrate the conventions Fig
183. he versions are distinguished from each other by the number appended to the function name For example DIV_F30 is the version of DIV_F that is called when the code is compiled for the TMS320C3x DIV_F40 is for the C4x and DIV_F is the version called by code compiled by version 4 10 and all earlier versions of the compiler The TMS320C3x MPYI multiply integer instruction does not perform full 32 bit multiplication the TMS320C4x MPYI instruction does it uses only the lower 24 bits of each operand Because standard C requires full 32 bit multiplication a runtime support function MPY_130 is provided to implement 32 bit integer multiplication for the TMS320C3x This function does not follow the standard C calling sequence instead operands are passed in registers RO and R1 The 32 bit product is returned in RO Note that using the shell option mp causes the code generator to inline 32 bit by 32 bit and 32 bit by 16 bit integer multiplication rather than call MPY_I30 Inlining this multiplication significantly reduces cycle time In addition the MPY_130 function is not used for squares such as i i an inline squaring func tion is used which also reduces cycle time The compiler uses the TMS320C3x MPYI instruction only in cases where address arithmetic is performed such as during array indexing because no address can have more than 24 bits a 24 x 24 multiply is sufficient You can use the mm option to force the compiler to us
184. his information hole An area between the input sections that compose an output section that contains no actual code or data initialized section A COFF section that contains executable code or initialized data An initialized section can be built up with the data text or sect directive input section A section from an object file that will be linked into an executable module K amp R TheC Programming Language second edition by Brian Kernighan and Dennis M Ritchie published by Prentice Hall Englewood Cliffs New Jersey 1988 This book describes ANSI C and is used as a refer ence in this book Paragraphs within the book are referred to with this symbol Glossary C 3 Glossary C4 label A symbol that begins in column 1 of a source statement and corresponds to the address of that statement linker A software tool that combines object files to form an object module that can be allocated into TMS320 system memory and executed by the TMS320 listing file An output file created by the assembler that lists source statements their line numbers and their effects on the SPC loader A device that loads an executable module into TMS320 system memory macro A user defined routine that can be used as an instruction macro call The process of invoking a macro macro definition A block of source statements that define the name and the code that make up a macro macro expansion The source statements that ar
185. how the upper and lower bits of R3 and R4 are saved and restored sep arately Any extended precision register must be saved in two parts All other registers can be saved as integers 4 6 2 Assembly Language Interrupt Routines Interrupts can also be handled with assembly language code as long as the register conventions are followed Like all assembly functions interrupt routines can use the stack access global C variables and call C functions nor mally When calling C functions be sure that all nondedicated registers are preserved because the C function can modify any of them Of course dedi cated registers need not be saved because they are preserved by the C func tion Interrupt handler functions whether in C or assembly must be installed by placing their address in the interrupt vector table On the TMS320C3x this table is located in the first 64 words of the address space On the TMS320C4x the table can be located anywhere on any 512 word boundary in the address space The IVTP register points to the location of the interrupt vector table Runtime Environment 4 31 Runtime Support Arithmetic Routines 4 7 Runtime Support Arithmetic Routines 4 32 The runtime support library contains a number of assembly language func tions that provide arithmetic routines for C math operators that the TMS320C3x C4x instruction set does not provide such as division There are as many as three different versions of each of these functions T
186. i Chapter 1 Introduction The TMS320 family of digital signal processors DSPs combines the high performance required in DSP applications with special features for these applications The TMS320C3x C4x DSPs are fully supported by a complete set of code generation tools including an optimizing C compiler an assembler a linker an archiver a software simulator a full speed emulator and a software development board This chapter provides an overview of these tools and introduces the features of the optimizing C compiler The assembler and linker are discussed in detail in the TMS320C3x C4x Assembly Language Tools User s Guide Topic Page 1 1 Software Development Tools Overview f 2 1 2 TMS320C3x C4x C Compiler Overview pp Iq Software Development Tools Overview 1 1 Software Development Tools Overview Figure 1 1 illustrates the TMS320C3x C4x software development flow The shaded portion of the figure highlights the most common path of software development the other portions are optional Figure 1 1 TMS320C3x C4x Software Development Flow Assembly Language Source Archiver i Macro Library Archiver i e Library of Runtime Object t e Support Files s e Library vy Hex Conversion Utility EPROM Programmer TMS320C3x TMS320C4x Debugging Tools Software Development
187. i 3 12 3 5 2 The DATA_SECTION Pragmea cece eect eee ene eee 3 13 3 5 3 The FUNC_CANNOT_INLINE Pragma 0000 cece eee eens 3 13 3 5 4 The FUNC_EXT_CALLED Pragma i 3 14 3 5 5 The FUNC_IS PURE Pragma vs de se padia iepa is 3 14 3 5 6 The FUNC_IS SYSTEM Pragma 0 0c eee cece 3 15 3 5 7 The FUNC_NEVER_RETURNS Pragma i 3 15 3 5 8 The FUNC NO GLOBAL_ASG Pragma 0 ccc eee ee eens 3 15 3 5 9 The FUNC NO IND ASG Pragma i 3 16 3 5 10 The INTERRUPT Pragma a 3 16 The asm Statement 0000 ed eens 3 17 Initializing Static and Global Variables i 3 18 Far Call SUpport iien siama atinada ada a ee eee Oe ee e 3 20 Delay Slot Filling for Branches 0 a ee eee ees 3 21 Compatibility With K amp R C pk Option pp 3 22 Compiler Limite 3 sm 3 24 Contents 4 Runtime Environment et Contains technical information on how the compiler uses the TMS320C3x C4x architecture Discusses memory and register conventions stack organization function call conventions system initialization and TMS320C3x C4x C compiler optimizations Provides information needed for interfacing assembly language to C programs AA Memory Model Gomme 441 S6CUONSs ea wher aa a 412 C System Stack mam agea arai i aaae Deel eek edetalee dees 4 1 3 Dynamic Memory Allocation i 4 1 4 Big and Small Memory Models pp 4 1 5 RAMand ROM Models is auers tmira meina paina i 4 2 Object Representation me 4 21 Data Type Storage s
188. ibly one or more extra pipeline delay cycles each time the compiler accesses one of these objects Use the small model whenever possible If you have large arrays allocate them dynamically from the heap using malloc rather than declaring them as global or static 5 eeeeeeeSEeseseseseseseeeeeeeSeeSes Note Size Restrictions on Small Model are not Tested When you use the small model you must be sure the bss section is less than 64K words and does not cross any 64K page boundaries Neither the compiler nor the linker checks these restrictions against the model used To make sure that the bss section conforms to these two rules link the bss section using the block attribute of the SECTIONS directive The statement bss load block 0x10000 when used with the SECTIONS directive will force the bss section into a 64K data page if the size of the bss section is less than 64K You should check the link map after linking to verify that the bss does not violate the restrictions Using Runtime Models If you have variables declared in assembly language outside the bss section you can still use the small model but you must access them indirectly and you may need to use the mf option as well Section 4 5 on page 4 22 discusses interfacing C with assembly language 2 3 2 The Register Argument and Standard Models You can choose from two different argument passing models In the standard runtime model default the compile
189. ic operators of the target system such as abs are inlined by the compiler by default This happens whether or not the optimizer is used and whether or not any compiler or optimizer options are used You can defeat this automatic inlining by invoking the compiler with the x0 option J Definition controlled inline expansion is performed when two conditions exist the inline keyword is encountered in source code and the optimizer is invoked at any level Functions with local static variables or a variable number of arguments will not be inlined with the exception of functions declared as static inline In functions defined as static inline expansion will occur despite the pres ence of local statics In addition a limit is placed on the depth of inlining for recursive or non leaf functions Inlining should be used for small functions or functions that are called only a few times though the compiler does not enforce this You can control this type of function inlining two ways inline return type function name parameter declarations function m Method 1 By defining a function as inline within a module with the inline keyword you can specify that the function is inlined within that module A global symbol for the function is created but the function will be inlined only within the module where it is defined as inline It will be called by other modules unless they contain a compatible static inline declaration Functions d
190. imizer pass that you enable and control with the o compiler options For details about the o options refer to Section 2 4 on page 2 38 However the code generator performs some optimizations particularly the target specific optimizations that you cannot selectively enable or disable This appendix describes two categories of optimizations general and target specific General optimizations improve any C code and target specific optimizations are designed especially for the TMS320C3x C4x architecture Both kinds of optimizations are performed throughout the compiler Some of the examples in this section were compiled with the v40 option and some with v30 The code produced will be slightly different different depending on the version For example Example A 1 shows code produced with the v40 option soone ofits local variables is assignedto register R8 a register the C3x doesn t have Unless otherwise noted the differences between v30 and v40 code are minimal These are the optimizations covered in this appendix Target Specific Optimizations General Optimizations 1 Register variables DD Algebraic reordering symbolic L Register tracking targeting simplification constant folding DD Cost based register allocation D Alias disambiguation L Autoincrement addressing Li Copy propagation D Repeat blocks L Common subexpression elimination D Parallel instructions Redundant assignment elimination DD Condition
191. ine in a module named boot asm 4 8 1 Autoinitialization of Variables and Constants 4 36 Some global variables must have initial values assigned to them before a C program starts running The process of retrieving these variables data and initializing the variables with the data is called autoinitialization The compiler builds tables in a special section called cinit that contains data for initializing global and static variables Each compiled module contains these initialization tables The linker combines them into a single table a single cinit section The boot routine uses this table to initialize all the variables that need values before the program starts running Initialization Tables System Initialization aaa Note Initializing Variables In standard C global and static variables that are not explicitly initialized are set to 0 before program execution The TMS320C3x C4x C compiler does not perform any preinitialization of uninitialized variables Any variable that must have an initial value of 0 must be explicitly initialized An alternative is to have a loader or boot obj clear the bss section before the program starts running In the small memory model any tables of long constant values or constant addresses must also be copied into the global data page at this time Data for these tables is incorporated into the initialization tables in cinit and thus is automatically copied at initialization time
192. ing const char format int sscanf const char str const char format FILE tmpfile void char tmpnam char s int ungetc int c FILE p int vfprintf FILE iop const char format va_list ap int vprintf const char format va_list ap int vsprintf char string const char format va_list ap General Utilities stdlib h int void void double int long void void void void void void void div_t T abs int j abort void atexit void fun void atof char nptr atoi char nptr atol char nptr bmalloc size_t_ size bmalloc8 size_t_ size bmalloc16 size_t_ size bsearch void key void base size_t n size_t size int compar void calloc size_t n size_t size calloc8 size_t_num size_t_size calloc16 size_t num size_t_size div int numer int denom Expands inline if x is used Macro Expands inline unless x0 is used Summary of Runtime Support Functions and Macros Description Writes to the array pointed to by string Reads from the string pointed to by str Creates a temporary file Generates a string that is a valid filename Writes the character c to a stream pointed to by p Writes to the stream pointed to by iop Writes to the standard output device Writes to the array pointed to by string Description Returns the absolute value of j Terminates a program abnormally Registers
193. ing C code you must use a runtime support library The rts lib library is included with the C compiler Whenever you specify a library as linker input the linker includes and links only those library members that resolve undefined references For example you can link a C program consisting of modules progi prog2 and prog3 the output file is named prog out 1ink30 e progl prog2 prog3 1 rts30 lib o prog out The linker uses a default allocation algorithm to allocate your program into memory You can use the MEMORY and SECTIONS linker directives to customize the allocation process and you can also use other linker options described in Table 2 1 on page 2 6 These directives are also described in Chapter 8 of the TMS320C3x C4x Assembly Language Tools User s Guide 2 10 2 Using the Shell to Invoke the Linker z Option The options and parameters discussed in this section apply to both methods of linking however when you are linking with the shell the options follow the z shell option By default the shell does not run the linker However if you use the z option the shell compiles assembles and links in one step When using z to enable linking remember that z must follow all source files and compiler options on the command line or be specified with C_OPTION Linking C Code z divides the command line into compiler options before z and linker options following z c and n suppr
194. inking C Code 2 74 In these command files the c option specifies that the linker use the ROM initialization model and the lowercase L option with rts30 lib or any of the runtime support libraries specifies that the linker search for the library named If the library is not in the current directory you can customize the command file to use C_DIR or the i option to define a path where the rts lib can be found You will most likely have to customize the command file to fit a particular application by adding or modifying options libraries memory configurations and section allocations If you use the RAM initialization model change c to cr If you use the big memory model you can remove the 64K word blocking on the bss section For more information about operating the linker refer to the linker chapter in the TMS320C3x C4x Assembly Language Tools User s Guide Chapter 3 TMS320C3x C4x C Language The TMS320C3x C4x C compiler supports the C language based on the ANSI American National Standards Institute C standard This standard was developed by a committee chartered by ANSI to standardize the C program ming language ANSI C supersedes the de facto C standard which was described in the first edition of The C Programming Language and based on the UNIX System V C language The ANSI standard is described in the American National Standard for Information Systems Programming Language C X3 159 1989 The seco
195. inted to by iop Write Block of Data include lt stdio h gt size_t fwrite const void ptr size_t size size_t count register FILE iop fwrite c in rts src Writes a block of data from the memory pointed to by ptr to a stream The stream is pointed to by iop Read Next Character include lt stdio h gt int getc FILE p fgetc c in rts src Reads the next character in a file The file is pointed to by p Runtime Support Functions 5 43 getchar getenv gets gmtime Alphabetical Summary of Runtime Support Functions Syntax Defined in Description Syntax Defined in Description Syntax Defined in Description Syntax Defined in Description 5 44 Read Next Character From Standard Input include lt stdio h gt int getchar void fgetc c in rts src Reads the next character from the standard input device Get Environment Information include lt stdlib h gt char getenv const char name Iddrv c in rts src Returns the environment information associated with name Read Next From Standard Input include lt stdio h gt char gets char pir fgets c in rts src Reads an input line from the standard input device The characters are placed in the array named by ptr Greenwich Mean Time include lt time h gt struct tm gmtime time_t timer gmtime c in rts src The gmtime function converts a local time pointed to by timer into Greenwich Mean Time represented as a broken
196. ion Bit masks and shift counts may be reduced to fit within an immediate value rather than requiring a space in the constant table For example consider the following code fragment int offset index i j k 1 m n 0 OxFFF amp offset index offset index lt lt 12 OxXOOFFFFFF amp offset lt lt 24 array OxFF amp offset index array offset index lt lt 12 array OxFFFFFF amp offset lt lt 24 OXFFFFFFF amp offset index lt lt 24 oS 8 FP wu Be ou owe wh th th a n all of the cases above the compiler recognizes that the interior multiplications will be precision limited by the various masks and or shifts spe cified It will then avoid using the MPY_1I30 runtime support function even though the variables offset and index are 32 bit integers The MPYI instruction or a series of shifts will be used instead In the assignment of variable o the precision requirements introduced by the shift left of 24 allow the compiler to convert the value OxFFFFFFF into OxFF eliminating the need to store this val ue on the constant table Runtime Environment 4 35 System Initialization 4 8 System Initialization Before you can run aC program the C runtime environment must be created This task is performed by the C boot routine which is a function called c_int00 The c_int00 function can be branched to called or vectored by reset hardware to begin running the system The function is in
197. ion removes local dead assignments eliminates local common subexpressions J Level 2 performs all level 1 features plus performs loop optimizations eliminates global common subexpressions eliminates global redundant assignments converts array references in loops to incremented pointer form performs loop unrolling Lj Level 3 performs all level 2 features plus removes all functions that are never called simplifies functions that have return values that are never used expands calls to small functions inline reorders function definitions so the attributes of called functions are known when the caller is optimized propagates arguments into function bodies when all call sites pass the same value in the same argument position identifies file level variable characteristics C Compiler Description 2 39 Using the C Compiler Optimizer _ lt _ gt lt _ 1 Note Files That Redefine Standard Library Functions The optimizer uses known properties of the standard library functions to perform level 3 optimizations If you have files that redefine standard library functions use the ol lowercase L options to inform the optimizer See page 2 26 This list describes optimizations performed by the standalone optimization pass The code generator performs several additional optimizations particularly TMS320C3x C4x specific optimizations it does so regardless of whether
198. ions Strength Reduction Induction Variable Elimination Register Variables and Loop Test Replacement f KKK KKK KKK KK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KKK KK KKK KK KK KKK KKK KR KKK KKK KR KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK 7 F loat a 10 b 10 loat dot_product pi ot seme float sum for i 0 i lt 10 i sum a i b return sum TMS320C30 COMPIL i ER Version X XX ac30 mr a2 c a2 if opt30 r 02 a2 cg30 p a2 opt version P Set globl _a globl _b globl _dot_product FUNCTION DEF _dot_product KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KKK KK KKK KK _dot_product E
199. ir You can set up default options for the shell by using the C_OPTION environ ment variable For a detailed description of the C_OPTION environment variable refer to subsection 2 1 4 Using the C_OPTION Environment Variable on page 2 28 Table 2 1 summarizes all compiler options The table is followed by in depth descriptions of each of the options C Compiler Description 2 5 Compiling C Code Table 2 1 Compiler Options Summary Table General Shell Options These options control the overall operation of the cl30 shell For more information see page 2 12 Option filename C dname def 9 idir K msrevx uname VXX Effect causes the compiler shell to read options from the specified file no linking negates z predefine a constant enable symbolic debugging define include search path keep asm file specifies the silicon revision of the target chip to enable additional func tionality for more recent silicon re leases Used in conjunction with v flag Example msrev6 v31 enable new 1996 C31 parallel instructions msrev2 v32 enable new 1996 C32 parallel instructions compile only create asm file suppress progress messages quiet suppress all messages Super quiet interlist optimizer comments and assembly source statements if avail able otherwise interlist C and assembly source statements interlist C and assembly source st
200. is allocated from the uninitialized sections sysm8 and Sysm16 respectively The linker creates a sysm8 or sysm16 section when a size is specified using the heap8 or heap16 option It will create a section of the default size 1K of 8 bit or 16 bit words when the malloc8 and malloc16 functions are used and the heap8 and heap16 options are not For more information refer to subsection 4 1 3 Dynamic Memory Allocation on page 4 4 This example allocates free space for a structure struct xyz p p malloc sizeof struct xyz Alphabetical Summary of Runtime Support Functions Syntax Defined in Description Syntax Defined in Description Syntax Defined in Description memchr memcmp memcpy Find First Occurrence of Byte include lt string h gt void memchr void s char c size_t n memchr c in rts src The memchr function finds the first occurrence of c in the first n characters of the object that s points to If the character is found memchr returns a pointer to the located character otherwise it returns a null pointer 0 The memchr function is similar to strchr except that the object that memchr searches can contain values of 0 and c can be 0 The memchr function is expanded inline when the x option is used Memory Compare include lt string h gt int memcmp void s1 void s2 size_t n memcmp c in rts src The memcmp function compares the first n characters of the object that s2
201. is greater than s2 Copies string s2 into s1 Returns the length of the initial segment of s1 that is made up entirely of characters that are not in s2 Maps the error number in errnum to an error message string Returns the length of a string Appends up to n characters from s1 to s2 Compares up to n characters in two strings Copies up to n characters of a s2 to s1 Finds the last occurrence of character c ins Locates the first occurrence in s1 of any character from s2 Returns the length of the initial segment of s1 which is entirely made up of characters from s2 Finds the first occurrence of s2 in s1 Breaks s1 into aseries of tokens each delimited by a character from s2 Runtime Support Functions 5 19 Summary of Runtime Support Functions and Macros Nonlocal Jumps setjmp h int void char setjmp jmp_buf env longjmp jmp_buf env int returnval asctime struct tm timeptr Time Functions time h clock_t char double time0 clock void ctime struct time timeptr difftime time_t time1 time_t structtm gmtime time_t timer structtm localtime time_t timer time_t size_t time_t T mktime struct tm timeptr strftime char s format size_t maxsize struct tm timeptr time time_t timer Expands inline if x is used Macro Expands inline unless x0 is used Description Saves calling environment for later use by longjmp function Uses jm
202. ister Variables Register Description R4 R5 Integer register variables R6 R7 Floating point register variables R8 C4x only Integer register variables AR4 AR7 Pointer register variables These registers are preserved across calls When a function uses register variables it must save the contents of each used register on entrance to the function then restore the saved contents on exit This ensures that a called function does not disrupt the register variables of the caller When you are not using the optimizer o option you can allocate register variables with the register keyword The code generator tries to allocate these variables to the registers listed in Table 4 2 if the value needs to be preserved across Calls If a function declares more register variables than are available for that type the excess variables are treated as automatic variables and are stored in memory on the local frame When you are using the optimizer the compiler ignores the register keyword and treats all variables as register variables The code generator allocates as many variables to registers as possible based on the life of a variable and when it is used In general registers not listed in Table 4 2 are not preserved across function calls so they are used only for variables that do not overlap any calls However if the pm shell option is used to create a single assembly file the code generator can more accurately determine the register
203. itutions 4 Includes i and C_DIR directories TMS320C3x C4x C Language 3 25 Chapter 4 Runtime Environment This section describes the TMS320C3x C4x C runtime environment To ensure successful execution of C programs it is critical that all runtime code maintain this environment If you write assembly language functions that inter face to C code follow the guidelines in this chapter Topics in this chapter include Topic Page 4i Memory Model se p 2 429 Object Representatie Ni ee E EE 4 7 4 3 Register Conventions e se easca eee neee 4 11 4 4 Function Structure and Calling Conventions 4 5 Interfacing C with Assembly Language ee 4 22 4 6 Interrupt Handling ee sence ten cet samsas n EE E E 4 7 Runtime Support Arithmetic Routines ss 4 32 4 8 System Initialization 4 1 Memory Model 4 1 Memory Model 4 1 1 4 2 Sections The C compiler treats memory as a single linear block that is partitioned into subblocks of code and data Each block of code or data that a C program gen erates will be placed in its own contiguous space in memory The compiler assumes that a full 32 bit address space is available in target memory a a 0 Note The Linker Defines the Memory Map The linker not the compiler defines the memory map and allocates code and data into target memory The compiler assumes nothing about the types of memory available about any locations not available for code or d
204. ividual files For more information about the e and f options refer to page 2 14 The conventions for filename extensions allow you to compile C files and assemble assembly files with a single command as shown in the example on page 2 3 You can use wildcard filename specifications to compile multiple files Wildcard specifications vary by system use the appropriate form To compile all the files in a directory that have a c extension by default all C files enter the following DOS system c130 c Compiling C Code 2 1 3 Compiler Options Commandline options control the operation of both the shell and the programs it runs This section provides a description of option conventions an option summary table and a detailed description of each of the options Compiler options m m m Lj L m Consist of single letters or letter groupings Are not case sensitive Are preceded by a hyphen Can be combined if there are single letter options without parameters for example sgq is equivalent to s g q Can be combined if two letter pair options without parameters have the same first letter for example mr and mb can be combined as mrb Cannot be combined in a grouping that contains a two letter pair option and a single letter option For example mrq is invalid because it would be parsed as mr and mq Cannot be combined with other options if they have parameters such as uname and id
205. ker as individual pro grams This section also describes how to invoke the interlist utility outside the shell The compiler is made up of three distinct programs the parser optimizer and code generator Figure 2 3 Compiler Overview Code Generator Optimizer The input for the parser is a C source file The parser reads the source file checking for syntax and semantic errors and writes out an internal representation of the program called an intermediate file Subsection 2 9 1 page 2 57 describes how to run the parser and also describes how to run the parser in two passes the first pass preprocesses the code and the second pass parses the code The optimizer is an optional pass that runs between the parser and the code generator The input is the intermediate file if produced by the parser When you run the optimizer you choose the level of optimization The optimizer performs the optimizations on the intermediate file and produces a highly efficient version of the file in the same intermediate file format Section 2 4 page 2 38 describes the optimizer The input for the code generator is the intermediate file produced by the parser if or the opt file from the optimizer The code generator produces an assembly language source file Subsection 2 9 3 page 2 62 describes how to run the code generator Assembler Interlist Utility Linker Invoking the Tools Individually The input for the a
206. l Summary of Runtime Support Functions setvbuf sin Define and Associate Buffer With Stream include lt stdio h gt int setvbuf register FILE iop register char buf register int type register size t_size setbuf c in rts src Defines and associates the buffer used by the stream pointed to by iop If buf is set to null a buffer is allocated If buf names a buffer that buffer is used for the stream The t_size parameter specifies the size of the buffer The type pa rameter specifies the type of buffering as follows _IOFBF Full buffering occurs _IOLBF Line buffering occurs _IONBF No buffering occurs Sine include lt math h gt double sin double x sin c in rts src The sin function returns the sine of a floating point number x x is an angle ex pressed in radians An argument with a large magnitude may produce a result with little or no significance double radian sval sval is returned by sin radian 3 1415927 sval sin radian sin returns 1 0 Runtime Support Functions 5 61 sinh sprintf sqrt Alphabetical Summary of Runtime Support Functions Syntax Defined in Description Example Syntax Defined in Description Syntax Defined in Description Example Hyperbolic Sine include lt math h gt double sinh double x sinh c in rts src The sinh function returns the hyperbolic sine of a floating point number x A range error occurs if the magnitude of the argument
207. lt extension for all input files is obj any other extension must be explicitly specified The linker can deter mine whether the input file is an object file or an ASCII file that contains linker commands The default output filename is a out Linker options can be specified on the commandline or inacommand file The command file allows you to use the MEMORY and SECTIONS directives which can customize your memory to your specifications If you enter the Ink30 command with no options the linker will prompt for them Command files Object files obj Output files Options C Compiler Description 2 65 Linking C Code This is the usual syntax for linking compiler based C programs as a separate step Ink30 c filenames oname out l rts lib or Ink30 cr filenames O name out l rts lib Ink30 is the command that invokes the linker C Cr are options that tell the linker to use special conventions defined by the C environment Note that when you use the shell to link it automatically passes c to the linker filenames are object files created by compiling and assembling C programs 0 name out names the output file If you don t use the o option the link er creates an output file with the default name of a out rts lib identifies the appropriate archive library containing C runtime support and floating point math functions The option tells the linker that a file is an object library If you re link
208. lute value of via ABSI instruction Floating point absolute value of f via ABSF instruction Conversion of floating point variable f to IEEE format via TOIEEE instruction Conversion of IEEE formatted variable f to floating point format via FRIEEE instruction Conversion of floating point variable f to integer via FIX instruction Conversion of floating point variable f to integer using ANSI compatible conversion sequence 24 bit integer multiplication of i and j using MPYI instruction similar to specifying the mm shell option 16 bit floating point inverse of f using RCPF instruction Processor s all all all C4x C4x all all C3x C4x When working with intrinsics it is important to be aware of the following DD fthe x0 shell option is specified disabling inline expansion the compiler treats intrinsic functions as regular function calls This means that at link time the linker will look for a function with the appropriate name and issue an error message if it has not been defined It is your responsibility to pro vide such a function Note however that the runtime support library includes callable functions for the abs labs and fabs intrinsics Intrinsics You should include the intrin h file in any file that uses the intrinsics functions The fast_ftoi intrinsic is similar to the mc shell option in that both cause the compiler to perform fast floating point to integer conversions
209. m specific so you must write your own time function Create Temporary File include lt stdlib h gt FILE tmpfile void tmpfile c in rts src Creates a temporary file Generate Valid Filename include lt stdlib h gt char tmpnam char s tmpnam c in rts src Generates a string that is a valid filename Convert to ASCII include lt ctype h gt int toascii char c toascii c in rts src The toascii function ensures that c is a valid ASCII character by masking the lower seven bits There is also an equivalent macro _toascii Alphabetical Summary of Runtime Support Functions tolower toupper Syntax Defined in Description Example Syntax Defined in Description Convert Case include lt ctype h gt int tolower char c int toupper char c tolower c in rts src toupper c in rts src tolower toupper ungetc Two functions convert the case of a single alphabetic character c to upper or lower case is not an uppercase letter tolower returns it unchanged is not a lowercase letter toupper returns it unchanged The functions have macro equivalents named _tolower and _toupper tolower A returns a tolower returns 4 Write Character to Stream include lt stdio h gt int ungetc int c FILE p ungetc c in rts src Writes the character c to a stream The stream is pointed to by p Runtime Support Functions The tolower fun
210. m stack 4 3 tan function tangent tanh function target processor temporary file creation function 5 76 tentative definition 3 23 test EOF function test error function text section Index 11 Index tf compiler option The C Programming Language 3 25 time 5 25 time function 5 76 time functions 5 11 asctime clock ctime 5 34 Site ea gmtime 5 44 localtime mktime strftime time time h header 5 11 __TIME__ 2 31 time_t type tm structure 5 11 tm type See broken down time TMP environment variable 2 28 overriding TMP_MAX macro tmpfile function tmpnam function _TMS320C30 _TMS320C31 _TMS320C32 2 31 _TMS320C3x 2 31 TMS320C3x C4x C language compatibility with ANSI C language 3 24 23 _TMS320C40 _TMS320C44 _TMS320C4x toascii function toieee intrinsic tokens 5 74 tolower function toupper function tp compiler option trailing comma enumerator list 3 23 trailing tokens preprocessor directives translation phases 2 34 trigonometric math function trigraph expansion trigraph sequences Index 12 type checking pointer combinations 2 19 type checking options 2 19 tf tp u compiler option u library build utility option u linker opon pas ungetc function uninitialized sections 2 70 4 3 bss 4 3 UNLINK I O
211. map directly to the low level I O functions The runtime support library includes the device drivers necessary to perform I O on the host on which the debugger is running The specifications for writing device level routines to interface with the low level routines are shown on pages B 7 to B 10 Each function must set up and maintain its own data structures as needed Some function definitions perform no action and just return Adding a Device For C I O B 3 Adding a Device For C I O The low level functions provide facilities that allow you to add and use a device for I O at runtime The procedure for using these facilities is 1 Define the device level functions as described in subsection B 2 Overview of Low Level I O Implementation on page B 3 Note Use Unique Function Names The function names OPEN CLOSE READ and so on are used by the low level routines Use other names for the device level functions that you write 2 Use the low level function add_device to add your device to the device_table The device table is a statically defined array that supports n devices where nis defined by the macro __NDEVICE found in stdio h The structure representing a device is also defined in stdio h and is composed of the following fields name is the string for device name flags specifies whether the device supports multiple streams or not function pointers are pointers to the device level functions CLOSE LSEEK
212. mizer comments into the assembly file if the com ments are available otherwise it will use the interlist utility to interlist C source into the assembly file To invoke the interlist utility outside of the shell refer to subsection 2 9 4 How the Compiler Handles Errors 2 7 How the Compiler Handles Errors One of the compiler s primary functions is to detect and report errors in the source program When the compiler encounters an error in your program it displays a message in the following format file c line n ECODE error message file c identifies the filename line n identifies the line number where the error occurs ECODE is a 4 character error code A single upper case letter identifies the error class a 3 digit number uniquely identifies the error error message is the text of the message Errors are divided into 4 classes according to severity these classes are identified by the letters W E F and I upper case i Code W Error Messages Code W errors are warnings They result from a condition that is technically undefined according to the rules of the language and code may not generate what you intended This is an example of a code W error file c line 42 W063 illegal type for register variable x Code E Error Messages Code E errors are recoverable They result from a condition that violates the semantic rules of the language Although these are normally fatal errors the c
213. modifiers cannot be used together in a single decla ration For example far static int x static near int x static int far x far int foo static far int foo Near and far data objects Global and static data objects can be accessed in the following two ways near keyword The compiler assumes that the data item can be accessed relative to the data page pointer For example sti ro _var far keyword The compiler cannot access the data item via the dp This can be required if the total amount of program data is larger than the offset allowed 32K from the DP For example ldiu cll aro sti ro aro where cl1 in the bss holds the address of the variable Keywords By default the compiler generates small memory model code which means that every data object is handled as if it were declared near unless it is actually declared far If an object is declared near it is normally loaded using relative offset addressing from the data page pointer DP which is B14 DP points to the beginning of the bss section If the options ml mb and mf are used the default assumptions change Large memory model code which means that every data object is handled as if it were declared far is then generated If you use the DATA_SECTION pragma the object is indicated as a far vari able and this cannot be overridden This ensures access to the variable since the variable might not be on the same data page as the bss section
214. mon screen oriented interface that allows you to display machine status informa tion inspect and modify C variables display C source code and monitor the execution of your program as it runs on the debugging platform Available de bugging tools include m An instruction accurate software simulator that simulates the TMS320C3x C4x functions The simulator executes linked COFF object modules An XDS extended development system emulator which is a PC resident real time in circuit emulator that features the same screen ori ented interface as the simulator An EVM evaluation module which is a plug in PC board that contains a target CPU such as a C30 that can be used to evaluate CPU performance TMS320C3x C4x C Compiler Overview 1 2 TMS320C3x C4x C Compiler Overview ANSI Standard C Optimization The TMS320C3x C4x C compiler is a full featured optimizing compiler that translates standard ANSI C programs into TMS320C3x C4x assembly language source The following list describes key features of the compiler The TMS320C3x C4x compiler fully conforms to the ANSI C standard as de fined by the ANSI specification and described in Kernighan and Ritchie s The C Programming Language second edition The ANSI standard includes recent extensions to C that are now standard features of the language These extensions provide maximum portability and increased capability The compiler uses a sophisticated optimization pass that emplo
215. mpiler produces tables of data for autoinitializing global variables The format of these tables is discussed on page 4 37 These tables are ina named section called cinit The initialization tables can be used in either of two ways J RAM Model cr linker option Global variables are initialized at oad time Use the cr linker option to select the RAM model For more information about the RAM model refer to page 4 38 J ROM Model c linker option Global variables are initialized at runtime Use the c linker option to select the ROM model For more information about the ROM model refer to page 4 37 The c and cr Linker Options Whenever you link a C program you must use either the c or the cr option These options tell the linker to use special conventions required by the C environment for example they tell the linker to select the ROM or RAM model of autoinitialization Note that when you use the shell to link programs the c option is the default The following list outlines the linking conventions used with c or cr Thesymbol_c_int00 is defined as the program entry point it identifies the beginning of the C boot routine in boot obj When you use c or cr _c_int00 is automatically referenced this ensures that boot obj is auto matically linked in from the runtime support library used The cinit output section is padded with a termination record so that the loader RAM model or the boot ro
216. msrev to the vxx option General Shell Options Option These options control the filename overall operation of the cl30 shell For more information see page 2 11 dname def 9 idir K msrevx uname VXX 2 62 Specify silicon revision see msrev in shell Effect causes the compiler shell to read options from the specified file no linking negates z predefine a constant enable symbolic debugging define include search path keep asm file specifies the silicon revision of the target chip to enable additional func tionality for more recent silicon re leases Used in conjunction with v flag Example msrev6 v31 enable new 1996 C31 parallel instructions msrev2 v32 enable new 1996 C32 parallel instructions compile only create asm file suppress progress messages quiet suppress all messages Super quiet interlist optimizer comments and assembly source statements if avail able otherwise interlist C and assembly source statements interlist C and assembly source statements undefine a constant specify processor xx 30 31 32 40 or 44 default is v30 see also msrev enable linking all options following are passed to linker Summary of Updates in This Document 3 1 Keywords Page Change or Add 3 1 Add Section 3 3 Keywords to the mini table of contents 3 7 Add Section 3 3 Keywords with subsection cregister Key
217. must have the following format space sign digits digits e E sign integer The function returns the converted string if the original string is empty or does not have the correct format the function returns a 0 If the converted string would cause an overflow the function returns HUGE_VAL if the converted string would cause an underflow the function returns 0 If the converted string causes an overflow or an underflow errno is set to the value of ERANGE The sirtol function converts a string to along integer The string must have the following format space sign digits digits e E sign integer D The sirtoul function converts a string to an unsigned long integer The string must be specified in the following format space sign digits digits e E sign integer The space is indicated by one or more of the following characters space bar horizontal or vertical tab carriage return form feed or newline Following the space is an optional sign and then digits that represent the integer portion of the number The fractional part of the number follows then the exponent in cluding an optional sign The first unrecognized character terminates the string The pointer that endptr points to is set to point to this character Runtime Support Functions 5 73 strtok strxfrm Alphabetical Summary of Runtime Support Functions Syntax Defined in Description Example Syntax Defined in Descripti
218. n clist CLK_TCK macro clock function clock_t type close file function CLOSE I O function code generator options 2 63 code E error messages code F error messages code l error messages code W error messages CODE_SECTION pragma compare strings compatibility 3 22 8 23 compiler branch delay slot filling 3 21 description error handling far calls 3 20 intrinsics support 2 invoking the 2 3 overview running as separate passes 2 54 sections compiling C code concatenate strings 63 const section 4 2 constants C language cosh function cosine 5 33 cr linker option d compiler option data section 4 3 data types C language 3 2 3 4 B 6 DATA_SECTION pragma 8 13 __ DATE __ 2 31 daylight savings time 5 11 debugging optimized code declarations C language default argument promotions defining variables in assembly language 4 25 device adding functions diagnostic sae diagnostic messages 5 4 ea NDEBUG macro See NDEBUG macro difftime function div function 5 35 div_t type 5 10 division 3 3 dspel 2 3 dynamic memory allocation e compiler option ea eo e linker option 2 24 EDOM macro 5 5 entry points _c_intO 2 69 for C code enumerator list trailing comma environment information function C_DIR 2 33 C_OPTION TMP EOF macro EPROM programmer 1 4 In
219. n line the compiler inserts line directives to synchronize line and file information in the output files with input position from the original source files If you use the pn option no line directives are inserted If you use the po option the compiler performs only the preprocessing functions listed above and then writes out the preprocessed listing file no syntax checking or code generation takes place The po option can be useful when debugging macro definitions or when host memory limitations dictate separate preprocessing refer to Parsing in Two Passes on page 2 59 The resulting preprocessed listing file is a valid C source file that can be rerun through the compiler Using Runtime Models 2 3 Using Runtime Models The compiler has three options that allow you to affect the runtime model All linked modules must use the same runtime model in order to correctly interface with other C modules assembly modules and library resident mod ules Runtime models are mutually exclusive that is you must choose a con figuration and then make sure that all the modules you link use the same model The following conventions are mutually exclusive and must be chosen before you begin to compile Mutually Exclusive Runtime Model Options big memory model mb small memory model default register argument model mr stack based model default TMS320C4x model v40 v44 TMS320C3x model v30 v31 v32 All code linked
220. n ina special typeface similar to a typewriter s Examples use a bold version of the special typeface for emphasis interactive displays use a bold version of the special typeface to distinguish commands that you enter from items that the system displays such as prompts command output error messages etc Here is a sample program listing 0011 0005 0001 field 1 2 0012 0005 0003 field 3 4 0013 0005 0006 field 6 3 0014 0006 eVen Here is an example of a system prompt and a command that you might enter C esr a user ti simuboard utilities In syntax descriptions the instruction command or directive is in a bold typeface font and parameters are in an italic typeface Portions of a syntax that are in bold should be entered as shown portions of a syntax that are in italics describe the type of information that should be entered Here is an example of a directive syntax Notational Conventions asect section name address asect is the directive This directive has two parameters indicated by sec tion name and address When you use asect the first parameter must be an actual section name enclosed in double quotes the second parameter must be an address Square brackets and identify an optional parameter If you use an optional parameter you specify the information within the brackets you don t enter the brackets themselves Here s an example of an instruction that has an optional parameter LA
221. n the command line c130 ft d temp The ft option if used overrides the TMP environment variable C Compiler Description 2 29 Controlling the Preprocessor 2 2 Controlling the Preprocessor The TMS320C3x C4x C compiler includes standard C preprocessing func tions which are built into the first pass of the compiler parser The preprocessor handles Macro definitions and expansions Lj include files J Conditional compilation Various other preprocessor directives specified in the source file as lines beginning with the character This section describes specific features of the TMS320C3x C4x preprocessor A general description of C preprocessing is in Section A12 of K amp R Controlling the Preprocessor 2 2 1 Predefined Names The compiler maintains and recognizes the predefined macro names listed in Table 2 2 Table 2 2 Predefined Macro Names Macro Name Description _LINE t expands to the current line number __FILE__ Tt expands to the current source filename __DATE__t expands to the compilation date in the form mm dd yyyy __TIME t expands to the compilation time in the form hh mm ss __STDC Tt expands to 1 identifies the compiler as ANSI standard _C3x expands to 1 if the target processor is a TMS320C3x _TMS320C3x processor otherwise it is undefined _C30 expands to 1 if target processor is defined to be TMS320C30 _TMS320C30 otherwise it is undefined _C31 expands to 1 if target process
222. nce double radians cval cos returns cval radians 3 1415927 cval cos radians return value 1 0 Runtime Support Functions 5 33 cosh ctime difftime Alphabetical Summary of Runtime Support Functions Syntax Defined in Description Example Syntax Defined in Description Syntax Defined in Description Hyperbolic Cosine include lt math h gt double cosh double x cosh c in rts src The cosh function returns the hyperbolic cosine of a floating point number x A range error occurs if the magnitude of the argument is too large double x y x 0 0 y cosh x return value 1 0 Calendar Time include lt time h gt char ctime time_t timer ctime c in rts src The ctime function converts the calendar time pointed to by timer and repre sented as a value of type time_t to a string This is equivalent to asctime localtime timer The function returns the pointer returned by the asctime function For more information about the functions and types that the time h header declares refer to subsection 5 2 13 page 5 11 Time Difference include lt time h gt double difftime time_t time1 time_t time0 difftime c in rts src The difftime function calculates the difference between two calendar times time1 minus timeO The return value is expressed in seconds For more information about the functions and types that the time h header declares refer to su
223. nction The pragma syntax is pragma INTERRUPT func Except for _c_int00 which is the name reserved for the system reset interrupt for C programs the name of the interrupt the func argument does not need to conform to a naming convention The asm Statement 3 6 The asm Statement The TMS320C3x C4x C compiler allows you to imbed TMS320C3x C4x assembly language instructions or directives directly into the assembly lan guage output of the compiler This capability is provided through an extension to the C language the asm statement The asm statement is syntactically like a call to a function named asm with one string constant argument asm assembler text The compiler copies the argument string directly into your output file The assembler text must be enclosed in double quotes All the usual character string escape codes retain their definitions For example you can insert a String directive that contains quotes asm STR string abc The inserted code must be a legal assembly language statement Like all assembly language statements the line mustbegin with a label a blank atab or acomment asterisk or semicolon The compiler performs no checking on the string if there is an error it will be detected by the assembler For more information refer to the TMS320C3x C4x Assembly Language Tools User s Guide These asm statements do not follow the syntactic restrictions of normal C statements th
224. nctions 5 39 fprintf fputc fputs fread Alphabetical Summary of Runtime Support Functions Syntax Defined in Description Syntax Defined in Description Syntax Defined in Description Syntax Defined in Description Write Stream include lt stdio h gt int fprintf FILE iop const char format fprintf c in rts src Writes to the stream pointed to by iop How to write the stream is described by a string pointed to by format Write Character include lt stdio h gt int fputc int c register FILE fp fputc c in rts src Writes a character to a stream The stream is pointed to by fp Write String include lt stdio h gt int fputs const char ptr register FILE iop fputs c in rts src Writes the string pointed to by ptr to a stream The stream is pointed to by iop Read Stream include lt stdio h gt size_t fread void ptr size_t size size_t count FILE iop fread c in rts src Reads from the stream pointed to by iop Stores the input in the array pointed to by ptr The number of objects read is count The size of the objects is size Syntax Defined in Description Example Syntax Defined in Description Alphabetical Summary of Runtime Support Functions free freopen Deallocate Memory include lt stdlib h gt void free void ptr void free8 void _ptr void free16 void _ptr memory c in rts src The free function deallocates memory space
225. nd edition of The C Programming Language by Kernighan and Ritchie is based on the ANSI standard and is used here as a reference ANSI C encompasses many of the language extensions provided by recent C com pilers and formalizes many previously unspecified characteristics of the language The TMS320C3x C4x C compiler strictly conforms to the ANSI C standard The ANSI standard identifies certain implementation defined features that may differ from compiler to compiler depending on the type of processor the runtime environment and the host environment This chapter describes how these and other features are implemented for the TMS320C3x C4x C compiler These are the topics covered in this chapter Topic Page 3 1 Characteristics of TMS320C3x C4x C ee b 2 3 2 Data Types si ictecieceniersisieniee store njerstereiaiapartelepsjayeeis EEE EEEE EEE eters 3 9 KeyWords lt cescuincss E E E dneiaaoasa i 3 4 Register VariaDles en se a 3 5 Pragma Directives cece eee eee eee eee 3 11 3 65 Theasm Statement ma E e leery ateler tele sierel yaleteleia leVsfer B 17 3 7 Initializing Static and Global Variables 3 6 FarCalll Support e e a E e E sts 3 9 Delay Slot Filling for Branches se 3 10 Compatibility with K amp R C pk Option eee eee B 22 SA ECOMMPIGGUTN Stacie nce nares rane ee rt lero nee tars 3 1 Characteristics of TMS320C3x C4x C 3 1 Characteristics of TMS320C3x C4x C The ANSI sta
226. ndard identifies some features of the C language that are af fected by characteristics of the target processor runtime environment or host environment For reasons of efficiency or practicality this set of features may differ among standard compilers This section describes how these features are implemented for the TMS320C3x C4x C compiler The following list identifies all such cases and describes the behavior of the TMS320C3x C4x C compiler in each case Each description also includes a reference to the formal ANSI standard and to the The C Programming Language by Kernighan and Ritchie K amp R Identifiers and constants Data types 3 2 J The first 100 characters of all identifiers are significant Case is significant uppercase and lowercase characters are distinct for identifiers These characteristics apply to all identifiers internal and external in all TMS320C3x C4x tools ANSI 3 1 2 K amp R A2 3 The source host and execution target character sets are assumed to be ASCII Although the compiler recognizes the syntax of multibyte characters there are no additional multibyte characters ANSI 2 2 1 K amp R A12 1 DJ Hex or octal escape sequences in character or string constants may have values up to 32 bits ANSI 3 1 3 4 K amp R A2 5 2 DD Character constants with multiple characters are encoded as the last character in the sequence For example abc cr ANSI 3 1 3 4 K amp R A2 5 2 DJ F
227. ng efficient decrement and branch Description of Compiler Optimizations A 13 Description of Compiler Optimizations Loop Unrolling instructions Induction variable analysis and strength reduction together often remove all references to your loop control variable allowing it to be eliminated entirely See Example A 2 and Example A 8 When the compiler can determine that a short loop is executed a low constant number of times it replicates the body of the loop rather than generating the loop This avoids any branches or use of the repeat registers Low and short are subjective judgments made by the compiler See Example A 7 Example A 7 Loop Unrolling int i for i 0 return sum add3 int a 3 sum 0 TMS320C30 C COMPILER KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK ac30 a7 c a7 if H opt30 02 a7 if a7 opt cg30 a7 opt a7 asm a7 tmp version 30 FP Set AR3 globl _add3
228. ng objects Duplicate Value in Memory include lt string h gt void memset void s int c size_t n memset c in rts src The memset function copies the value of c into the first n characters of the ob ject that s points to The function returns the value of s The memset function is expanded inline when the x option is used Syntax Defined in Description Alphabetical Summary of Runtime Support Functions minit Reset Dynamic Memory Pool include lt stdlib h gt void minit void void minit8 void void minit16 void memory c in rts src The minit function resets all the space that was previously allocated by calls to the malloc calloc or realloc functions Was a eer SCs Note Accessing Objects After Calling the minit Function Calling the minit function makes all the memory space in the heap available again Any objects that you allocated previously will be lost do not try to access them The memory that minit uses is in a special memory pool or heap defined in an uninitialized named section called sysmem in memory c The linker sets the Size of this section from the value specified by the heap option Default heap size is 1K words For the TMS320C32 processor 8 bit and 16 bit versions of the minit function are provided The functions minit8 and minit16 are analogous to the 32 bit version however memory is allocated from the uninitialized sections sysm8 and sysm16 respectively The linker
229. ngle 64K word memory data page 65536 words Runtime Environment 4 5 Memory Model This means that the total space for all static and global data in the program must be less than 64K and that the bss cannot cross any 64K address boundaries The compiler sets the data page pointer register DP during runtime initialization to point to the beginning of the bss Then the com piler can access all objects in the bss global and static variables and constant tables with direct addressing without modifying the DP J The big memory model does not restrict the size of the bss unlimited space is available for global and static data However when the compiler accesses any global or static object that is stored in the bss it must first ensure that the DP correctly identifies the memory page where the object is stored To accomplish this the compiler must set the DP by using an LDP or LDPK load data page pointer instruction each time a static or global data item is accessed This task produces one extra instruction word and several extra machine cycles one cycle for the LDP instruction plus one or more pipeline delay cycles if the object is accessed by the next instruction For example the following compiler generated assembly language uses the LDP instruction to set the DP to the correct page before accessing the global variable x This is a TMS320C3x example the sequence is one cycle shorter for the C4x x is a global vari
230. nitialized at load time instead of runtime realmode Sixteen bit native MS DOS mode This mode limits the available memory to 640K Calls to DOS may involve switching from protected to real mode ROM model An autoinitialization model used by the linker when linking C code The linker uses this model when you invoke the linker with the c option In the ROM model the linker loads the cinit section of data tables into memory and variables are initialized at runtime section A relocatable block of code or data that will ultimately occupy contiguous space in the TMS320 memory map section header A portion of a COFF object file that contains information about a section in the file Each section has its own header the header points to the section s starting address contains the section s size etc static A kind of variable whose scope is confined to a function or a program The values of static variables are not discarded when the function or program is exited their previous value is resumed when the function or program is re entered structure A collection of one or more variables grouped together under a single name Glossary C 5 Glossary C 6 symbol A string of alphanumeric characters that represents an address or a value symbolic debugging The ability of a software tool to retain symbolic information so that it can be used by a debugging tool such as a simulator or an emulator symbol table A portion of a
231. nt in the application See Example A 5 Autoincrement addressing Repeat blocks Parallel instructions A 4 For pointer expressions of the form p p p or p the compil er uses efficient TMS320C3x C4x autoincrement addressing modes In many cases where code steps through an array in a loop such as for i 0 i lt N i afi the loop optimizations convert the array references to indirect references through autoincremented register variable pointers See Example A 2 The TMS320C3x C4x supports zero overhead loops with the RPTS repeat single and RPTB repeat block instructions With the optimizer the compiler can detect loops controlled by counters and generate code for them using the efficient repeat forms RPTS for single instruction loops or RPTB for larger loops For both forms the iteration count can be either a constant or an expression See Example A 2 and Example A 8 Several TMS320C3x C4x instructions such as load load store operate and multiply add can be paired with each other and executed in parallel When adjacent instructions match the addressing requirements the compiler combines them in parallel Although the code generator performs this optimization the optimizer greatly increases effectiveness because operands are more likely to be in registers See Example A 2 and Example A 8 Description of Compiler Optimizations Example A 2 Repeat Blocks Autoincrement Addressing Parallel Instruct
232. nto registers Eight nine for the TMS320C4x registers are available for register variables in each function DD Registers R4 and R5 and R8 for the C4x are reserved for integer register variables in a function Tworegisters R6 and R7 are reserved for floating point register variables in a function Four registers AR4 AR7 are reserved for pointer or integer register variables Any object with a scalar type integer floating point or pointer can be de clared as a register variable The register designator is ignored for objects of other types The register storage class is meaningful for parameters as well as local vari ables If the stack based calling convention is used a parameter declared as a register is passed on the stack normally but then moved into a register upon function entry This improves access to the parameter within the function Ifa parameter is not declared as a register it will be allocated local space in the function and stored there as the function begins execution For more information about register variables refer to Section 4 3 on page 4 11 Pragma Directives 3 5 Pragma Directives Pragma directives tell the compiler s preprocessor how to treat functions The TMS320C3x C4x C compiler supports the following pragmas CODE_SECTION DATA_SECTION FUNC_CANNOT_INLINE FUNC_EXT_CALLED FUNC_IS_PURE FUNC_IS_SYSTEM FUNC_NEVER_RETURNS FUNC_NO_GLOBAL_ASG FUNC_NO_IND_ASG INTERRUPT
233. nts are passed in the registers in the above list in order E All arguments that are not assigned to registers either because of type incompatibility or because all registers have been exhausted are pushed onto the stack in reverse order right to left A fifth register ARO may be used to return structures and unions by address ARO may also be used to return pointers Table 4 3 lists the functions contained in the runtime support assembly files that conform to the modified calling convention 4 18 Table 4 3 Runtime Support Functions Using Modified Calling Convention Function Assembly File _C_int00 boot asm _main _ exit _frexp frexp30 asm _ldexp Idexp30 asm _longjmp setjmp asm _setimp _modf modf30 asm _sqrt sqrt30 asm DIV_F DIVI arith410 asm DIV_U MOD MOD_U MPY 1 MPY_X INV_F30 invf asm INV_F40 INV_LD invid asm 4 4 3 Responsibilities of a Called Function Function MPY_1I30 MPY_K30 MPY_LD DIV_130 DIV_140 DIV_F30 DIV_F40 DIV_U30 DIV_U40 DIV_LD MOD 130 MOD 140 MOD_U30 MOD_U40 Function Structure and Calling Conventions Assembly File mpyi asm mpyk asm mpyld asm divi asm divf asm divu asm divid asm modi asm modu asm A called function must perform certain tasks Step 1 below helps to manage the local frame If the function has no local variables no stack arguments and no need for local temporary storage Steps 1 and 6 are not taken 1 The call
234. o compile enter c130 gk mi function This compiles and produces symbolic debugging directives keeps the assembly language file and allows normal optimization To produce an interlist file enter clist r function This interlists and removes debugging directives from the file The output from this example is function cl Linking C Code 2 10 Linking C Code The TMS320C3x C4x C compiler and assembly language tools provide two methods for linking your programs you can link object files using the linker alone J you can compile assemble and link in one step by using the shell This is useful when you have a single source module This section describes how to invoke the linker with each method It also discusses special requirements of linking C code including the runtime support libraries specifying the initialization model and allocating the program into memory 2 10 1 Invoking the Linker The TMS320C3x C4x C compiler and assembly language tools support modular programming by allowing you to compile and assemble individual modules and then link them together The general syntax for invoking the linker is Ink30 options filename filenamen Ink30 is the command that invokes the linker options can appear anywhere on the command line or in a linker command file Options are discussed in Table 2 1 page 2 6 filenames can be object files linker command files or archive libraries The defau
235. odel of Autoinitialization Object File Memory Initialization ROM Boot Routine bss Section RAM 4 40 Chapter 5 Runtime Support Functions Some of the tasks that a C program must perform such as I O floating point arithmetic dynamic memory allocation string operations and trigonometric functions are not part of the C language itself The runtime support functions which are included with the C compiler are standard ANSI functions that perform these tasks The runtime support library rts src contains the source for these functions as well as for other functions and routines If you use any of the runtime support functions be sure to build the appropriate library according to the desired runtime model using the library build utility then include that library as linker input when you link your C program These are the topics covered in this chapter Topic Page 5 1 Runtime Support Libraries pp 5 2 a Header E a E E E ay etcere 5 3 Summary of Runtime Support Functions and Macros 5 13 By AU ei Gee ara 5 21 5 1 Runtime Support Libraries 5 1 Runtime Support Libraries Nine runtime support libraries are included with the TMS320C3x C4x C compiler eight object libraries containing object code for the runtime support and a source library containing source code for the functions in the object libraries Runtime Library Processor Option s Used rts30 lib TMS320C3x m
236. of inline expansion performed X0 X2 X no inline expansion Defeats the default expansions listed below fthe x0 shell option is specified the compiler treats intrinsic functions as regular function calls See Section 2 8 on page 2 54 for further information on intrinsics is the default value The intrinsic operators are inlined wherever they are called This is true whether or not the optimizer is invoked and whether or not a x option is specified except x0 Intrinsic operators are listed on page 2 54 creates the preprocessor symbol _ INLINE assigns it the value 1 and invokes the optimizer at level 2 thereby enabling definition controlled inline expansion If a function has been defined or declared as inline it will be expanded inline whenever the optimizer is called and the x option is not equal to x0 Setting the x option to x2 automatically invokes the optimizer and thus causes the automatic expansion of functions defined or declared as inline as well as causing the other optimizations defined at level 2 which is the default level for the optimizer The _INLINE preprocessor symbol has been used to control the expansion of the runtime library modules They will be expanded if _ INLINE is equal to 1 but will be called if INLINE is not equal to 1 Other functions may be set up to use _INLINE in the same way For more information see subsection 2 5 3 The __INLINE Preprocessor Symbol If
237. of type integer or pointer The cregister keyword is not al lowed on objects of any floating point type or on any structure or union object The cregister keyword does not imply that the object is volatile If the control register being referenced is volatile that is can be modified by some external control then the object should be declared with the volatile keyword also To use a control register in Table 3 2 you must declare each register with or without volatile as follows extern cregsiter volatile unsigned int register Once you have declared the register you can use the register name directly See TMS320C3x C4x CPU and Instruction Set Reference Guide for detailed information on the control registers TMS320C3x C4x C Language 3 7 Keywords Example 3 1 Define and Use Control Registers extern cregisger volatile unsigned extern cregister volatile unsigned extern cregisger volatile unsigned xtern cregister volatile unsigned unsigned myfunc unsigned int mask ST amp mask 0 Do nothing wait return IOF 3 3 2 The near and far Keywords The C3x C4x C compiler extends the C language with the near and far key words to specify how global and static variables are accessed and how func tions are called Syntactically the near and far keywords are treated as storage class modifiers They can appear before after or in between the storage class specifiers and types Two storage class
238. ompiler can recover and generate an output file if you use the pe option Refer to subsection 2 7 1 for more information This is an example of a code E error file c line 66 E056 illegal storage class for function f Code F Error Messages Code F errors are fatal They result from a condition that violates the syntactic or semantic rules of the language The compiler cannot recover and therefore does not generate output for code F errors This is an example of a code F error file c line 71 F090 structure member a undefined C Compiler Description 2 51 How the Compiler Handles Errors Code l Error Messages Code I errors are implementation errors They occur when one of the compiler s internal limits is exceeded These errors are usually caused by extreme behavior in the source code rather than by explicit errors In most cases code errors cause the compiler to abort immediately Most code messages contain the maximum value for the limit that was exceeded Those limits that are absolute are also listed in Section 3 11 on page 3 24 This is an example of a code error file c line 99 1015 block nesting too deep max 20 Other Error Messages 2 7 1 The compiler also reports other errors such as incorrect command line syntax or inability to find specified files These errors are usually fatal and are identified by the symbol gt gt preceding the message This is an example of such
239. on 5 74 Break String into Token include lt string h gt char strtok char s1 char s2 strtok c in rts src Successive calls to the strtok function break s1 into a series of tokens each delimited by a character from s2 Each call returns a pointer to the next token The first call to strtok uses the string s1 Successive calls use a null pointer as the first argument The value of s2 can change at each invocation It is impor tant to note that s1 is altered by the strtok function After the first invocation of strtok in the example below the pointer stra points to the string excuse because strtok has inserted a null character where the first space used to be In the comments the notation 0 represents the null character char stra excuse me while I kiss the sky char ptr ptr strtok stra ptr gt excuse 0 ptr strtok 0 ptr gt me 0 ptr strtok 0 ptr gt while 0 Convert Characters include lt string h gt size_t strxfrm char tostring const char fromstring size_t n strxfrm c in rts src Converts the characters of one string into another string The n number of characters pointed to by fromstring are converted into the n characters pointed to by tostring Syntax Defined in Description Example Syntax Defined in Description Example Alphabetical Summary of Runtime Support Functions tan tanh Tangent
240. on 3 5 7 The FUNC_NEVER_RETURNS Pragma The FUNC_NEVER_RETURNS pragma specifies to the optimizer that the function never returns to its caller The pragma must appear before any declaration or reference to the function that you want to keep The syntax of the pragma is pragma FUNC_NEVER_RETURNS func The argument func is the name of the C function that does not return 3 5 8 The FUNC_NO GLOBAL ASG Pragma The FUNC_NO_GLOBAL_ASG pragma specifies to the optimizer that the function makes no assignments to named global variables and contains no asm statements The pragma must appear before any declaration or reference to the function that you want to keep The syntax of the pragma is pragma FUNC NO GLOBAL_ASG func The argument func is the name of the C function that makes no assignments TMS320C3x C4x C Language 3 15 Pragma Directives 3 5 9 The FUNC NO IND ASG Pragma The FUNC_NO_IND_ASG pragma specifies to the optimizer that the function makes no assignments through pointers and contains no asm statements The pragma must appear before any declaration or reference to the function that you want to keep The syntax of the pragma is pragma FUNC_NO_IND_ASG func The argument func is the name of the C function that makes no assignments 3 5 10 The INTERRUPT Pragma The INTERRUPT pragma enables you to handle interrupts directly with C code The argument func is the name of a fu
241. on 2 3 Compiling C Code The normal progress information consists of a banner for each compiler pass and the names of functions as they are defined The example below shows the output from compiling a single module without the q option 130 symtab symtab TMS320C3x 4x ANSI C Compiler Version x xx Copyright c 1987 1997 Texas Instruments Incorporated symtab c gt main symtab c gt lookup TMS320C3x 4x ANSI C Codegen Version x xx Copyright c 1987 1997 Texas Instruments Incorporated symtab c gt main symtab c gt lookup TMS320C3x 4x COFF Assembler Version x xx Copyright c 1987 1997 Texas Instruments Incorporated PASS 1 PASS 2 No Errors No Warnings 2 1 2 Specifying Filenames 2 4 The input files specified on the command line can be C source files assembly source files or object files The shell uses filename extensions to determine the file type Extension File Type asm abs or s extension begins with s assembly language source file c or no extension C source file 0 extension begins with o object file Files without extensions are assumed to be C source files and a c extension is assumed You can use the e option to change these default extensions causing the shell to associate different extensions with assembly source files or object files You can also use the f option on the command line to override these file type interpretations for ind
242. one and a variable of this type called _tz You can change the time zone by modifying this structure either at runtime or by editing tmzone c and changing the initialization The default time zone is U S central standard time The basis for all the functions in time h are two system functions clock and time Time provides the current time in time_t format and clock provides the system time in arbitrary units The value returned by clock can be divided by the macro CLOCKS _ PER_SEC to convert it to seconds Since these functions and the CLOCKS _PER_SEC macro are system specific only stubs are provided in the library To use the other time functions you must supply custom versions of these functions Summary of Runtime Support Functions and Macros 5 3 Summary of Runtime Support Functions and Macros Refer to the following pages for information about functions and macros Function or Macro Error Message Macro ss Character Typing Conversion Functions sssaaa anans Floating Point Math Functions i Variable Argument Functions and Macros General Utilities 2 0 0 0 cette eens String FUNCIONS 0 5 becca eecas dere ma we eed ees oh eeea ee aes Setjmp Function and Longjmp Macro 000ee eee eee eee TIM FUNCHONS ge a a nd bese Oy Like see de bo a ed Runtime Support Functions 5 13 Summary of Runtime Support Functions and Macros Error Message Macro assert h Description void assert int expression Inserts diagn
243. ons and Shell Options i 2 58 Optimizer Options and Shell Options pp 2 61 Code Generator Options and Shell Options pp 2 63 Sections Created by the Compiler pp 2 70 TMS320C3x C4x C Data Types i 3 4 Valid Control Registers sa sds Di ee ee ee ee ee a a 3 7 Absolute Compiler Limits ss ee a eee es Register Use and Preservation Conventions 000 cece eee eee e eens 4 11 Registers Reserved for Register Variables i 4 12 Runtime Support Functions Using Modified Calling Convention 4 4 19 Summary of Runtime Support Arithmetic Functions 0000 eee eee eee 4 34 Macros That Supply Integer Type Range Limits limits h i 5 6 Macros That Supply Floating Point Range Limits float h 0 00 e eee 5 7 Examples How the Runtime Support Library Uses the INLINE Symbol 0005 An Interlisted Assembly Language File i 2 49 Define and Use Control Registers i 3 8 Using the CODE_SECTION Pragma i Using the DATA_SECTION Pragma i 3 13 An Assembly Language Function Called From C i 4 25 Accessing a Variable Defined in bss From C i 4 26 Accessing a Variable Not Defined in bss From GC et 4 27 Accessing an Assembly Language Constant From C ee 4 28 Register Variables and Register Tracking Targeting pp A 3 Repeat Blocks Autoincrement Addressing Parallel Instructions Strength Reduction Induction Variable Elimination Register Variables and Loop Test Replacement TMS320C3x C4x Delayed Branch
244. ons is a single definition for the object a For most K amp R compilers this sequence is illegal because ais defined twice ANSI prohibits but K amp R allows objects with external linkage to be redeclared as static extern int a static int a illegal unless pk used Unrecognized escape sequences in string and character constants are explicitly illegal under ANSI but ignored under K amp R char c q same as q if pk used error if not ANSI specifies that bit fields must be of type integer or unsigned With pk bit fields can be legally declared with any integer type For example struct s short f 2 illegal unless pk used K amp R syntax allows assignments to structures returned from a function i 123 illegal unless pk used K amp R syntax allows a trailing comma in enumerator lists enum a b c illegal unless pk used K amp R syntax allows trailing tokens on preprocessor directives endif NAME illegal unless pk used TMS320C3x C4x C Language 3 23 Compiler Limits 3 11 Compiler Limits 3 24 Due to the variety of host systems supported by the TMS320C3x C4x C compiler and the limitations of some of these systems the compiler may not be able to successfully compile source files that are excessively large or com plex Most of these conditions occur during the first compilation pass parsing When such a condition occurs the parser issues
245. opportunities to apply other optimizations See Example A 8 and Example A 9 The optimizer inlines small functions not de clared as inline when invoked with the o3 option The size of code growth al lowed may be changed using the oi size option Example A 8 Inline Function Expansion part one inline blkcpy char to char from int n if n gt 0 do to fromt while n 0 struct s int a b c 10 initst struct s ps chart 12 blkcpy char ps t 12 Description of Compiler Optimizations A 15 Description of Compiler Optimizations Example A 9 Inline Function Expansion part two TMS320C30 C COMPILER Version X XX i KKEKKKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKKKKKKAKKKK KKK KKK KK KK H ac30 mr a8 c a8 if gt opt30 r 02 a8 if a8 opt cg30 p a8 opt a8 asm a8 tmp version 30 FP Set AR3 globl _blkcpy
246. option and one that doesn t Note that if you do not specify the z option the code generator deletes the input intermediate file C Compiler Description 2 63 Invoking the Tools Individually 2 9 4 2 64 Invoking the Interlist Utility The fourth step in compiling a TMS320C3x C4x C program is optional After you have compiled a program you can run the interlist utility To run the interlist utility from the command line the syntax is clist asmfile outfile options clist is the command that invokes the interlist utility asmfile _ is the filename of assembly language output from the compiler outfile names the interlisted output file If you omit this the file has the same name as the assembly file with an extension cl options control the operation of the utility as follows b removes blanks and useless lines lines containing comments or lines containing only or r removes symbolic debugging directives q suppresses banner and status information The interlist utility uses line directives produced by the code generator to associate assembly code with C source For this reason when you compile the program you must use the g shell option to specify symbolic debugging if you want to interlist it If you do not want the debugging directives in the output use the r interlist option to remove them from the interlisted file The following example shows how to compile and interlist function c T
247. or information about the representation of data types refer to Section 3 2 ANSI 3 1 2 5 K amp R A4 2 D The type size_t which is assigned to the result of the sizeof operator is equivalent to unsigned int ANSI 3 3 3 4 K amp R A7 4 8 DJ The type ptrdiff_t which is assigned to the result of pointer subtraction is equivalent to int ANSI 3 3 6 K amp R A7 7 Conversions Expressions Declarations Preprocessor Characteristics of TMS320C3x C4x C Int to float conversions use the TMS320C3x C4x FLOAT instruction which produces an exact representation However the value may be trun cated when written to memory resulting in a loss of precision towards negative infinity ANSI 3 2 1 3 K amp R A6 3 Pointers and integers can be freely converted ANSI 3 3 4 K amp R A6 6 When two signed integers are divided and either is negative the quotient is negative A signed modulus operation takes the sign of the dividend the first operand For example 10 f 3 3 10 10 3 3 1 10 3 3 3 3 1 ANSI 3 3 5 K amp R A7 6 A right shift of a signed value is an arithmetic shift that is the sign is pre served ANSI 3 3 7 K amp R A7 8 The register storage class is effective for all character short integer and pointer types ANSI 3 5 1 K amp R A8 1 Structure members are not packed into words with the exception of bit fields Each member is aligned on a 32 bit word boundary ANSI 3 5 2 1 K
248. or is defined to be TMS320C31 _TMS320C31 otherwise it is undefined _C32 expands to 1 if target processor is defined to be TMS320C32 _TMS320C32 otherwise it is undefined _C4x expands to 1 if the target processor is a TMS320C4x _TMS320C4x processor otherwise it is undefined _C40 expands to 1 if the target processor is a TMS320C40 _TMS320C40 processor otherwise it is undefined _C44 expands to 1 if the target processor is a TMS320C44 _TMS320C44 processor otherwise it is undefined _INLINE expands to 1 under the x or x2 optimizer option undefined otherwise _REGPARM expands to 1 if the register argument runtime model is used undefined otherwise _BIGMODEL expands to 1 if the mb option is used undefined otherwise Specified by the ANSI standard You can use macro names in the same manner as any other defined name For example printf s Ss __TIME_ DATE__ could translate to a line such as printf s s Jan 14 1997 13 58 17 C Compiler Description 2 31 Controlling the Preprocessor The preprocessor produces self explanatory error messages The line number and the filename where the error occurred are printed along with a diagnostic message You can predefine additional names from the command line by using the d option c130 dNAME dREGS 6 c This has the same effect as including these lines at the beginning of each source file define NAME 1 d
249. or not you invoke the optimizer These optimizations are always enabled and are not affected by the optimization level you choose For more information about the meaning and effect of specific optimizations refer to Appendix A 2 4 2 Definition Controlled Inline Expansion Option x Option When the optimizer is invoked the x optimizer option controls inline expansion of functions that have been declared as inline by inhibiting or allowing the expansion of their code in place of calls That is code for the function will be inserted inlined into your function at each place it is called whenever the optimizer is invoked and the x option is not equal to x0 The x2 option automatically invokes the optimizer at the default level level 2 if the o option is not specified separately and defines the _INLINE preproces sor symbol as equal to 1 which causes expansion of functions declared as in line and controlled by the _INLINE symbol For more information about _INLINE see subsection 2 5 3 page 2 46 Inlining makes a program faster by eliminating the overhead caused by function calls but inlining sometimes increases code size For more information see Section 2 5 Function Inlining page 2 43 2 4 3 Using the Optimizer with the Interlist Option os option Optimization makes normal source interlisting impractical because the optimizer extensively rearranges your program Therefore the optimizer writes reconstructe
250. or object files If the fr option is not specified the shell will place object files in the current directory To specify an object file directory insert the directory s pathname on the command line after the fr option c130 fr d object permits you to specify a directory for assembly files If the fs option is not specified the shell will place assembly files in the current directory To specify an assembly file directory insert the directory s pathname on the command line after the fs option c1500 fs d assembly permits you to specify a directory for temporary intermediate files The ft option overrides the TMP environment variable described in subsection 2 1 5 To specify a temporary di rectory insert the directory s pathname on the commandline after the ft option c130 ft d temp C Compiler Description 2 15 Compiling C Code Parser Options 2 16 treats code E errors as warnings Normally the code generator does not run if the parser detects any code E errors When you use the pe option the parser treats code E errors as warnings allowing complete compilation For more information about errors and about pe refer to Section 2 7 on page 2 51 produces a function prototype listing file The parser creates a file containing the prototype of every procedure in all corresponding C files Each function prototype file is named as its corresponding C file with a pro extension pf i
251. or shell utility is invoked with the x2 or x option It allows you to write code so that it will run whether or not inlining is used It is used by standard header files included with the compiler to control the declaration of standard C runtime functions The _INLINE symbol is used in the string h header file to declare the function correctly regardless of whether inlining is used The _INLINE symbol is turned off in the memcpy source before the header file is included because it is unknown whether the rest of the module is compiled with inlining If the rest of the modules are compiled with inlining enabled and the string h header is included all references to memcpy will be inlined and the linker will not have to use the memcpy in the runtime support library to resolve any references Otherwise the runtime support library code will be used to resolve the references to memcpy and function calls will be generated You will want to use the _INLINE preprocessor symbol in the same way so that your programs will run regardless of whether inlining mode is selected for any or all of the modules in your program Example 2 1 on page 2 47 illustrates how the runtime support library uses the _INLINE symbol Function Inlining Example 2 1 How the Runtime Support Library Uses the _INLINE Symbol BRK RK KK RK RA A A A A RA A A A AR A OR AR RO OR RK STRING H HEADER FILE
252. or the environment variable C_DIR to identify a directory name i Shell Option Controlling the Preprocessor The i shell option names an alternate directory that contains include files The format for the i option is cl30 i pathname You can use up to 32 i options per invocation each i option names one pathname In C source you can use the include directive without specifying any path information for the file instead you can specify the path information with the i option For example assume that a file called source c is in the current directory This file contains one of the following directive statements include alt h or include lt alt h gt The table below lists the complete pathname for alt c and shows how to invoke the compiler select the row for your host system Host Pathname for alt c Invocation Command DOS or OS 2 c dsp files alt h cl30 ic dsp files source c UNIX dsp files alt h cl30 i dsp files source c C_DIR Environment Variable The compiler uses the environment variable C_DIR to name alternate directories that contain include files To specify the same directory for include files as in the previous example set C_DIR with one of these commands Host Enter DOS or OS 2 set C_DIR c dsp files UNIX setenv C_DIR dsp files Then you can include alt h include alt h or include lt alt h gt and invoke the compiler without the i option c130 source c
253. ostic messages into programs Character Typing Conversion Description Functions ctype h int isalnum char c t Tests c to see if it s an alphanumeric ASCII character int isalpha char c t Tests c to see if it s an alphabetic ASCII character int isascii char c t Tests c to see if it s an ASCII character int iscntrl char c t Tests c to see if it s a control character int isdigit char c t Tests c to see if it s a numeric character int isgraph char c t Tests c to see if its any printing character except a space int islower char c t Tests c to see if it s a lowercase alphabetic ASCII character int isprint char c t Tests c to see if it s a printable ASCII character including spaces int ispunct char c t Tests c to see if it s an ASCII punctuation character int isspace char c t Tests c to see if it s an ASCII spacebar tab horizontal or vertical carriage return formfeed or newline character int isupper char c t Tests c to see if it s an uppercase ASCII alphabetic character int isxdigit char c t Tests c to see if it s a hexadecimal digit char toascii char c t Masks c into a legal ASCII value char tolower int char c t Converts c to lowercase if it s uppercase char toupper int char c t Converts c to uppercase if it s lowercase Floating Point Math Functions math h Description double acos double x Returns the arccosine of x double asin double x Returns the arcsine of x double atan double x Returns t
254. other modules This disables some of the 03 optimizations interlists optimizer comments into the compiler s assembly language output For more information see Section 2 6 page 2 49 allows the compiler to use zero overhead loop instructions RPTS and RPTB to control unsigned loop counters To use this option you must be certain that these loops will iterate fewer than 231 times C Compiler Description 2 27 Compiling C Code 2 1 4 Using the C_OPTION Environment Variable An environment variable is a system symbol that you define and assign to a string You may find it useful to set the shell default options using the C_OPTION environment variable if you do this these default options and or input filenames are used every time you run the shell Setting up default options with the C_OPTION environment variable is especially useful when you want to run the shell consecutive times with the same set of options and or input files After the shell reads the entire command line and the input filenames it reads the C_OPTION environment variable and processes it Options specified with the environment variable are specified in the same way and have the same meaning as they do on the command line For example if you want to always run quietly enable symbolic debugging and link then set up the C_OPTION environment variable as follows Host Enter DOS or OS 2 set C_OPTION aqg z UNIX setenv C_OPTION qg z You may w
255. output module strips symbol table information and line number entries from the output module sets the C system stack size to size words and defines a global symbol that specifies the stack size Default 1K words places the unresolved external symbol symbol into the output module s symbol table generates version n COFF format generates a warning when an output section that is not specified with the SECTIONS directive is created forces rereading of libraries and resolves back references C Compiler Description 2 25 Compiling C Code Optimizer Options 2 26 oisize oln causes the compiler to optimize the intermediate file that is produced by the parser n denotes the level of optimization There are three levels of optimizations 00 01 02 and 03 If you do not indicate a level 0 1 2 3 after the o option the optimizer defaults to level 2 For more information about the optimizer refer to Section 2 4 on page 2 38 and Appendix A controls automatic inlining of functions not defined or de clared as inline at optimization level 3 You specify the size limit for the largest function that will be inlined times the number of times it is called If no size is specified the optimizer will inline only very small functions Setting the size to 0 oi0 disables automatic inlining completely Note that this option controls only the inlining of functions that have not been explicitly defined
256. p function is expanded inline if the x option is used The functions return one of the following values lt 0 if s1 is less than s2 0 if s1 is equal to s2 gt 0 if s1 is greater than s2 char stra why ask why char strb Just do it char strce why ask why if stremp stra strb gt 0 statements here will be executed if strcoll stra strc 0 statements here will be executed also Syntax Defined in Description Example Syntax Defined in Description Example Alphabetical Summary of Runtime Support Functions strcpy strcspn String Copy include lt string h gt char strcpy char s1 char s2 strcpy c in rts src The strcpy function copies s2 including the terminating null character into si If you attempt to copy strings that overlap the function s behavior is undefined The function returns a pointer to s1 The strcpy function is expand ed inline if the x option is used In the following example the strings pointed to by a and b are two separate and distinct memory locations In the comments the notation 0 represents the null character char a The quick black fox char b jumps over a gt The quick black fox 0 b gt jumps over 0 ef strcpy a b a gt jumps over 0 b gt jumps over 0 E Find Number of Unmatching Characters include lt string h gt
257. p_buf argument to restore a previously saved environment Converts a time to a string Description Determines the processor time used Converts time to a string Returns the difference between two calendar times Converts local time to Greenwich Mean Time Converts time_t value to broken down time Converts broken down time to a time_t value Formats a time into a character string Returns the current calendar time 5 4 Functions Reference Function or Macro add_device asctime asin atexit atof atoi atol bsearch calloc CON ws sme clearerr clock div fflush fgetc fgets Functions Reference This section contains an alphabetical list of the functions and macros declared in the header files The following table lists the functions and macros and directs you to the detailed description of the function or macro Function or Macro fopen fseek fsetpos ftell fwrite getc getchar getenv gets Page Function or Macro memcmp memcpy memmove putc remove rename rewind scanf setbuf setjmp Setvbuf sin sinh Page Function or Macro Page strchr strcmp strcoll strcpy strcspn strerror strftime strlen strncat strncmp strncpy strpork strrchr
258. pen function 5 39 FOPEN_MAX macro 5 9 FP register 4 4 fpos_t data type fprintf function fputc function fputs function fr file specifier option 2 15 fread function free function free16 function free8 function freopen function described frexp function frieee arctan A fs file specifier option fscanf function fseek function fsetpos function ft file specifier option ftell function 5 43 FUNC_CANNOT_INLINE pragma 3 13 FUNC_EXT_CALLED pragma FUNGC_IS_PURE pragma FUNC_IS_SYSTEM pragma FUNC_NEVER_RETURNS pragma FUNC_NO_GLOBAL_ASG pragma FUNC_NO_IND_ASG pragma function call conventions 4 1 function calls using the stack function prototypes listing file fwrite function g compiler option 2 12 g linker option general utilit functions 5 10 5 17 abort generating a preprocessed listing file generating symbolic debugging directives get file position function 5 43 getc function getchar function getenv function gets function 5 44 global variables reserved space gmtime function gregorian time 5 11 h library build utility option h linker option header files 5 45 12 assert h header 5 4 ctype h header errno h header 5 5 file h header float h header 5 6 limits h header math h header 6 8 setjmp h header stdarg h header 5 8 stddef h header stdio h header 5 9 Index
259. pt 7 cg30 p a5 opt ad asm a5 tmp version 30 FP Set AR3 globl _simp FUNCTION DEF _simp x _simp AR2 assigned to parameter j LDI 2 R0 LSH RO AR2 R1 ADDI R1 AR2 R2 LDI 3 R1 LSH R1 AR2 R3 LSH R2 AR2 RC ADDI R3 RC LDI 3 AR2 CALL _call EPIO_1 RETS KEK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KEK KKK KK KKK KK KK KKK KKKKKKAK KKK KKK KKK KK UNDEFINED REFERENCES kkkkxkxkxkxkxk xkx xkxkxkxkxkxkxkxkxkxkxkxkxkxkxk xk kxkxkxkxkxkxkxkxkxkxkxkxkxkxkxkxkxkkxkxk kxkxkxkxkxkxkxkxkxkxkxk xkxkxkxkxkxkxkxkxkxkkxx kxx globl _call end Description of Compiler Optimizations A 11 Description of Compiler Optimizations Branch optimizations control flow simplification A 12 The compiler analyzes the branching behavior of a program and rearranges the linear sequences of operations basic blocks to remove branches or redundant con
260. ptions The c option is especially helpful when you have specified z in the C_OPTION environment variable and want to selectively disable linking with c on the command line The n option causes the shell to stop the process after com pilation The c linker option has a different function than and is independent of the c shell option By default the shell automatically uses the c linker option that tells the linker to use C linking conventions ROM model of initialization If you want to use cr RAM model of initialization rather than c you can pass cr as a linker option instead C Compiler Description 2 67 Linking C Code 2 10 3 Controlling the Linking Process Regardless of the method you choose for invoking the linker special requirements apply when linking C programs You must D include the compiler s runtime support library specify the initialization model D determine how you want to allocate your program into memory This section discusses how these factors are controlled and provides an example of the standard default linker command file For more information about how to operate the linker refer to Chapter 8 of the TMS320C3x C4x Assembly Language Tools User s Guide Runtime Support Libraries All C programs must be linked with a runtime support library This archive library contains standard C library functions such as malloc and strcpy as well as functions used by the compiler
261. q04164 SDSsq04166 SDSsq04172 SDSsq04373 SDSsq04202 SDSsq04215 SDSsq04219 SDSsq04227 SDSsq04261 SDSsq04296 SDSsq04298 SDSsq04301 SDSsq04257 SDSsq04338 SDSsq04378 Description The year tm_year in ret src will print as 3 digits after year 2000 Compiler generates incorrect code using register passing model PRTS30 macros for SWW control are incorrect Compiler allocating RS RC RE inside c_intxx s C4x 32 Bit FP Divide Routine DIV_F40 has error Codegen adds errant adds into assembly code With mf compiler generates bad shifts Incorrect code generated for calls to ISR and functions ST not popped last compiler code calls MOD_140 instead of MOD_U40 Incorrect code generated for array reference using 02 INCOMPATIBLE ADDRESSING MODES generated with 02 switch used Assembler swaps operands for MPYF3 ADDF3 RTS has general errors nuisances Compiler inserts unneeded aligns into const section wastes space Compiler uses inefficient FP divide vs 4 70 Compiler is generating illegal code Compiler does not account for second word of long double when opti mizing Change or Add Summary of Updates in This Document The following is the list of bugs closed for this release Bugs SDSsq02750 SDSsq02751 SDSsq02917 SDSsq02633 SDSsq02964 SDSsq02965 SDSsq02966 SDSsq02967 SDSsq02969 SDSsq03152 SDSsq03153 SDSsq03247 SDSsq03257 SDSsq03258 SDSsq03333 SDSsq03492 SDSsq03570 SDSsq03644 SDSsq03645 SDSsq03788
262. r and provides an alphabetical reference of the runtime support functions st Runtime Support Libraries ses hes nents 5 2 Contents xiv SLI Modifying a Library Function srs 5 3 5 1 2 Building a Library With Different Options 0 0c cee eee eee 5 3 5 2 Header FileS 0 sedi ue dood saiad dda eda asca aad dake hee aren 5 4 5 2 1 Diagnostic Messages assert h 0 eee 5 4 5 2 2 Character Typing and Conversion ctype h pp 5 5 523 Error Reporting errno h soma 5 5 5 2 4 Low Level I O Functions file h i 5 5 5 2 5 Limits float h and limits h 0 5 6 5 2 6 Floating Point Math math h 0 0 eee ee 5 8 5 2 7 Nonlocal Jumps setjmp h sine i eee eee 5 8 5 2 8 Variable Arguments stdarg h i 5 8 5 2 9 Standard Definitions stddef h 00 ccs 5 9 5 2 10 stdio hR l O Functions ss aor a si ete 5 9 5 2 11 General Utilities Stdlib h 7 5 10 5 2 12 String Functions string h si 5 11 5 2 13 Time Functions time h oi eee eee 5 11 5 3 Summary of Runtime Support Functions and Macros si 5 13 5 4 Functions Reference 0 5 21 Library Build Utility 4 Describes the utility that custom makes runtime support libraries for the options used to com pile code This utility can also be used to install header files in a directory and to create custom libraries from source archives 6 1 Invoking the Library Build Utility sss 6 2 6 2 Options Summary Description of Compiler Optimizations i
263. r char memchr void s int c size_t n t mememp void s1 void s2 size_t n t memcpy void s1 void s2 size_t n t memmove void s1 void s2 size_t n memset void s int c size_t n t streat char s1 char s2 T strchr char s int c t stremp char s1 char s2 t strcoll char s1 char s2 strepy char s1 char s2 T strespn char s1 char s2 strerror int errnum strlen char s t strncat char s1 char s2 size_t n strncmp char s1 char s2 size_t n strncpy char s1 char s2 size_t n strrehr char s char c t strpbrk char s1 char s2 strspn char s1 char s2 strstr char s1 char s2 strtok char s1 char s2 Expands inline if x is used Macro Expands inline unless x0 is used Summary of Runtime Support Functions and Macros Description Finds the first occurrence of c in the first n characters of s Compares the first n characters of s1 to s2 Copies n characters from s1 to s2 Moves n characters from s1 to s2 Copies the value of c into the first n characters of s Appends s2 to the end of s1 Finds the first occurrence of character c ins Compares strings and returns one of the following values lt 0 if s1 is less than s2 0 if s1 is equal to s2 gt 0 if s1 is gt s2 Compares strings and returns one of the following values de pending on the locale lt 0 if s1 is less than s2 0 if s1 is equal to s2 gt 0 if s1
264. r passes all arguments to functions on the stack When you invoke the compiler with the mr option some or all of the arguments are passed in registers This results in less overhead for function calls in your program Ue Oe eee er Note All Functions Must Be Prototyped When using the register argument model all functions must be prototyped The compiler must be able to see the types of function parameters when the function is called If there is a function call with no prototype visible the compiler probably will generate incorrect code for the call The pf option will generate prototypes for all functions you define The pw2 option will issue a warning for a function call that has no prototype in scope The runtime support libraries rts30r lib rts30gr lib rts40r lib and rts40gr lib shipped with the compiler are compatible with the register argument model Technical details of both models are explained in Section 4 4 on page 4 15 The library build utility is described in Chapter 6 C Compiler Description 2 37 Using the C Compiler Optimizer 2 4 Using the C Compiler Optimizer The compiler package includes an optimization program that improves the execution speed and reduces the size of C programs by doing such things as simplifying loops rearranging statements and expressions and allocating variables into registers The optimizer runs as a separate pass between the parser and the code generator The easiest
265. r the stream pointed to by iop Read Next Characters include lt stdio h gt char fgets char ptr register int size register FILE iop fgets c in rts src Reads the specified number of characters from the stream pointed to by iop The characters are placed in the array named by ptr The number of characters read is size 1 Syntax Defined in Description Example Syntax Defined in Description Example Syntax Defined in Description Alphabetical Summary of Runtime Support Functions floor fmod fopen Floor include lt math h gt double floor double x floor c in rts src The floor function returns a floating point number that represents the largest integer less than or equal to x The floor function is expanded inline if the x option is used double answer 34 0 4 0 answer answer answer answer floor 3 1415 floor 3 5 Floating Point Remainder include lt math h gt double fmod double x double y fmod c in rts src The fmod function returns the remainder after dividing x by y an integral num ber of times If y 0 the function returns 0 double x Y T x 11 0 y 5 0 r fmod x y fmod returns 1 0 Open File include lt stdio h gt FILE fopen const char file const char mode fopen c in rts src Opens the file that file points to How to open the file is described by a string pointed to by mode Runtime Support Fu
266. ream that p points to Syntax Defined in Description Syntax Defined in Description Example Alphabetical Summary of Runtime Support Functions clock cos Processor Time include lt time h gt clock_t clock void clock c in rts src The clock function determines the amount of processor time used It returns an approximation of the processor time used by a program since the program began running The return value can be converted to seconds by dividing by the value of the macro CLOCKS PER_SEC If the processor time is not available or cannot be represented the clock func tion returns the value of 1 _ _ SSS_ _ Sve i a a __ ___ lt lt lt _i i i ji Note Writing Your Own Clock Function The clock function is target system specific so you must write your own clock function You must also define the CLOCKS PER_ SEC macro accord ing to the granularity of your clock so that the value returned by clock num ber of clock ticks can be divided by CLOCKS_PER_SEC to produce a value in seconds sal For more information about the functions and types that the time h header de clares refer to subsection 5 2 13 page 5 11 Cosine include lt math h gt double cos double x cos c in rts src The cos function returns the cosine of a floating point number x The angle x is expressed in radians An argument with a large magnitude may produce a result with little or no significa
267. red as int cmp const void ptrl const void ptr2 The cmp function compares the objects that ptr1 and ptr2 point to and returns one of the following values lt 0 if ptr1 is less than ptr2 0 if ptr1 is equal to ptr2 gt 0 if ptr1 is greater than ptr2 In order for the search to work properly the comparison must return lt 0 0 gt 0 include lt stdlib h gt include lt stdio h gt int list 1z 3 4y 6y By 9f int diff const void const void 0 main int key 8 int p bsearch amp key list 6 1 idiff p points to list 4 int idiff const void il const void i2 return int il int 12 Syntax Defined in Description Example Alphabetical Summary of Runtime Support Functions calloc Allocate and Clear Memory include lt stdlib h gt void calloc size_t nmemb size_t size void calloc8 size_t num size _t_ size void calloc16 size_t num size_t_ size memory c in rts src The calloc function allocates size bytes for each of nmemb objects and re turns a pointer to the space The function initializes the allocated memory to all Os If it cannot allocate the memory that is if it runs out of memory it re turns a null pointer 0 The memory that calloc uses is in a special memory pool or heap defined in an uninitialized named section called sysmem in memory c The linker sets the size of this section from the value specified by the heap option Defa
268. reg for the C Com piler Passing g to asm30 does not work with current Debuggers Command file for Ink30 does not allow embedded in file name Archiver does not allow a default obj extension sym debug information contains wrong offset get incorrect results for long doubles divide operation TMS320C8x User s Guide documents gsrev6 switch Codegen creates illegal parallel instruction subf3 stf Compiler generate decomposition error on sample code Logical AND operator bug in v 5 00 works ok in v 4 70 optimization level 2 is not as effective as optimization level 1 Optimization appears to use direct instead of indirect addressing Hex3 byte option doesn t work with 5 0 worked fine with 4 7 see detail file s C Compiler generates wrong Assembly code for the line Statement COMPILER ERROR Unsupported constant operand for LDP optimizer generates wrong starting address for structure element When linking a debugger MemBIk Save obj file gt gt out of memory aborting Assembler Generates incorrect P parallel addressing mode 01 instead of 11 MPYF3 SUBF3 Far function call generates invalid addresses in big memory configura tion Compiler removes circular buffer references from asm statements pragma DATA_SECTION generates code incorrectly for v5 0 when small mem model Summary of Updates in This Document D 7 Summary of Updates in This Document Bug number SDSsq04151 SDSsq04155 SDSs
269. ros are used when the number and type of arguments may vary each time a function is called The type va_list is a pointer type that can hold information for va_start va_end and va_arg A variable argument function can use the macros declared by stdarg h to step through its argument list at runtime when it knows the number and types of arguments actually passed to it Note Variable Argument Functions Must Have Prototypes A variable argument function must have a prototype to ensure that the arguments are passed correctly Header Files 5 2 9 Standard Definitions stddef h The stddef h header defines two types and two macros The types include DD ptrdiff t a signed integer type that is the resul from the subtraction of two pointers size_t an unsigned integer type that is the data type of the sizeofoperator The macros include The NULL macro which expands to a null pointer constant 0 The offsetof type identifier macro which expands to an integer that has type size_t The result is the value of an offset in bytes to a structure member identifier from the beginning of its structure type These types and macros are used by several of the runtime support functions 5 2 10 stdio h l O Functions The stdio h header defines types and macros and declares functions Type Declarations The following table lists the types defined in stdio h Type Description size_t An unsigned integer
270. rs define macros that expand to useful limits and parameters of the TMS320C3x C4x numeric representations Table 5 1 and Table 5 2 list these macros and the limits with which they are associated Table 5 1 Macros That Supply Integer Type Range Limits limits h Macro CHAR BIT SCHAR_MIN SCHAR_MAX UCHAR_MAX CHAR _MIN CHAR_MAX SHRT_MIN SHRT_MAX USHRT_MAX INT_MIN INT_MAX UINT_MAX LONG_MIN LONG_MAX ULONG_MAX Value 32 2147483648 2147483647 4294967295 SCHAR_MIN SCHAR_MAX 2147483648 2147483647 4294967295 2147483648 2147483647 4294967295 2147483648 2147483647 4294967295 Description Number of bits in type char Minimum value for a signed char Maximum value for a signed char Maximum value for an unsigned char Minimum value for a char Maximum value for a char Minimum value for a short int Maximum value for a short int Maximum value for an unsigned short int Minimum value for an int Maximum value for an int Maximum value for an unsigned int Minimum value for a long int Maximum value for a long int Maximum value for an unsigned long int Note Negative values in this table are defined as expressions in the actual header file so that their type is correct Macro Value FLT_RADIX 2 FLT ROUNDS 1 FLT_DIG 6 DBL_DIG 6 LDBL_DIG 8 FLT_MANT_DIG 24 DBL_MANT_DIG 24 LDBL_MANT_DIG 32 FLT_MIN_EXP 126 DBL_MIN_EXP LDBL_MIN_EXP FLT_MAX_EXP 128 DBL_MAX_EXP LDBL_MAX_EXP FLT_EPSILON 1 19209
271. rted support is pro vided for conversion to and from IEEE single and double precision format for the TMS320C4x processors through the assembly language functions TOIEEE and FRIEEE See the TMS320C 4x User s Guide for more infor mation on these instructions The size representation and range of each scalar data type are listed in the table below Table 3 1 TMS320C3x C4x C Data Types Type Size Representation Minimum ea re char signed char 32 bits ASCII 2147483648 2147483647 unsigned char 32 bits ASCII 0 4294967295 short 32 bits 2s complement 2147483648 2147483647 unsigned char 32 bits binary 0 4294967295 int signed int 32 bits 2s complement 2147483648 2147483647 unsigned int 32 bits binary 0 4294967295 long signed long 32 bits 2scomplement 2147483648 2147483647 unsigned long 32 bits binary 0 4294967295 enum 32 bits 2s complement 2147483648 2147483647 float 32 bits TMS320C3x C4x 5 877472e 39 3 4028235e38 double 32 bits TMS320C3x C4x 5 877472e 39 3 4028235e38 long double 40 bits TMS320C3x C4x 5 87747175e 39 3 4028236684e38 pointers 32 bits binary 0 OxFFFFFFFF 3 2 1 Data Types Many of the range values are available as standard macros in the header file limits h which is supplied with the compiler lt _ 48 9 ey ee fy 0 OT Note A TMS320C3x C4x Byte Is 32 Bits The ANSI definition specifies that the sizeof operator yields the number of bytes required to store an object ANSI further stipulates th
272. rting define name def at the top of each C source file If the optional def is omitted dname sets name equal to 1 g causes the compiler to generate symbolic debugging direc tives that are used by the C source level debuggers and or the interlist utility idir adds dir to the list of directories to be searched for include files You can use this option a maximum of 32 times to de fine several directories be sure to separate i options with spaces Note that if you don t specify a directory name the preprocessor ignores the i option For more information refer to subsection 2 2 2 on page 2 32 K keeps the assembly language file Normally the shell de letes the output assembly language file after assembling completes but using k allows you to retain the assembly language output from the compiler n causes the shell to compile only If you use n the specified source files are compiled but not assembled or linked This option overrides z and c The output of n is assembly language output from the compiler 2 12 S uname VXX Z Compiling C Code suppresses banners and progress information from all the tools Only source filenames and error messages are out put suppresses all output except error messages interlists optimizer comments with assembly language out put if the comments are available otherwise this option invokes the interlist utility which interlists C sourc
273. s C based on the ANSI C standard Use the Kernighan and Ritchie book as a supplement to this manual Before you can use this book you should read the TMS320C3x C4x Code Generation Tools Getting Started Guide to install the C compiler tools How to Use This Manual Notational Conventions How to Use This Manual Notational Conventions The goal of this book is to help you learn how to use the Texas Instruments C compiler tools specifically designed for the TMS320C3x 4x devices This book is divided into three distinct parts E m Introductory information in chapter one provides an overview of the TMS320C3x 4x development tools Compiler description in chapter two describes how to operate the C compiler and the shell program and discusses specific characteristics of the C compiler as they relate to the ANSI C specification It contains tech nical information on the TMS320C3x 4x architecture and includes information needed for interfacing assembly language to C programs It describes libraries and header files in addition to the macros functions and types they declare Finally it describes the library build utility Reference material in chapters three through six and the glossary pro vides supplementary information on TMS320C3x 4x specific optimiza tions and definitions of terms used in the book This document uses the following conventions m Program listings program examples and interactive displays are show
274. s from the stream pointed to by iop and stores the input to the array pointed to by ptr Opens the file that file points to using the stream that iop points to mode points to a string describing how to open the file Reads from the stream pointed to by iop Sets the file position indicator for the stream pointed to by iop Sets the file position indicator for the stream that iop points to pos the pointer pos must be a value from fgetpos on the same stream Obtains the current value of the file position indicator for the stream that iop points to Writes a block of data from the memory pointed to by pir to the stream that iop points to A macro that calls fgetc A macro that calls fgetc and supplies stdin as the argument Maps the error number ins to a string and prints the error message Performs the same function as fprintf but uses stdout as its output stream A macro that performs like fputc Writes a character to the standard output device Writes a string pointed to by ptn to the standard output device Makes the file pointed to by file no longer available by that name Renames the file pointed to by old to the name pointed to by new Sets the file position indicator for a stream to the beginning of the file pointed to by iop Reads the stream from the standard input device Specifies the buffer used by the stream pointed to by iop Defines and associates a buffer with a stream MO Functions continued int sprintf char str
275. s strncmp Compare Strings include lt string h gt int strncmp char s1 char s2 size_t n strncmp c in rts src The strnemp function compares up to n characters of s2 with s1 The function returns one of the following values lt 0 if s1 is less than s2 0 if s1 is equal to s2 gt 0 if s1 is greater than s2 char stra why ask why char strb just do it char stre why not size_t size 4 if stremp stra strb size gt 0 statements here will get executed if TERE TEN strc size 0 statements here will get executed also Runtime Support Functions 5 69 strncpy Alphabetical Summary of Runtime Support Functions Syntax Defined in Description Example 5 70 String Copy include lt string h gt char strncpy char s1 char s2 size_t n strncpy c in rts src The strncpy function copies up to n characters from s2 into s1 If s2 is n characters long or longer the null character that terminates s2 is not copied If you attempt to copy characters from overlapping strings the function s behavior is undefined If s2 is shorter than n characters strncpy appends null characters to s1 so that s1 contains n characters The function returns the val ue of s1 Note that strb contains a leading space to make it five characters long Also note that the first five characters of strc are an a space the word am and another space so that after the se
276. s useful when conforming code to the ANSI C standard or generating a listing of procedures defined relaxes certain requirements that are stricter than those required by earlier K amp R compilers and that are newly im posed by the ANSI C standard This facilitates compatibility between existing K amp R compatible programs and the TMS320C3x ANSI compiler The effects of the pk options are described in Section 3 10 on page 3 22 generates a preprocessed listing file The compiler writes a modified version of the source file to an output file called file pp This file contains all the source from include files and expanded macros It does not contain any comments For more information refer to subsection 2 2 3 on page 2 34 pwn Compiling C Code when used with the o3 option combines source files into one intermediate file called a module to perform program level optimization instead of file level optimization The module proceeds to the optimization and code generation passes of the compiler Because the compiler can now see the entire C program it performs several optimizations that are not usually done during file level optimization If a particular argument in a function always has the same value the compiler replaces the argument with the value and passes the value instead of the argu ment lfareturnvalue of a function is never used the compiler deletes the return code in the function Ifa function is not c
277. se these registers correctly For more information about using these registers see Section 4 3 page 4 11 for more information about the stack see Section 4 4 page 4 15 The stack size is set by the linker The linker also creates a global symbol __STACK_SIZE and assigns it a value equal to the size of the stack in words The default stack size is 1K 400h words This size allows the stack to fit into one of the on chip RAM blocks You can change the size of the stack at link time by using the Stack option on the linker command line and specifying the size of the stack as a constant immediately after the option For more information about the stack option refer to the TMS320C3x C4x Assembly Language Tools User s Guide At system initialization the SP is set to a designated address for the bottom of stack This address is the first location in the stack section Since the position of the stack depends on where the stack section is allocated the actual position of the stack is determined at link time If you allocate the stack as the last section in memory highest address the stack has unlimited space for growth within the limits of system memory Fr rr Note Stack Overflow The compiler provides no means to check for stack overflow during compila tion or at runtime A stack overflow will disrupt the runtime environment causing your program to fail Be sure to allow enough space for the stack to grow a 4 1 3 D
278. should be declared with no arguments Interrupt handling functions should not be called directly 4 6 1 Saving Registers During Interrupts When C code or assembly code is interrupted all registers must be preserved including the status registers A problem arises with the extended precision registers RO R7 RO R11 on the C4x these registers can contain either integer or floating point values and an interrupt routine cannot determine the type of value in a register Thus an interrupt routine must preserve all 40 bits of any of these registers that it modifies This involves saving both the integer part lower 32 bits and the floating point part upper 32 bits The following code illustrates the entry and exit sequences for an interrupt ser vice routine that has two local variables and uses registers FP SP ST R3 R4 and AR4 PUSH FP save old FP LDI SP FP set up new FP ADDI 2 SP allocate local frame PUSH ST Save ST PUSH R3 Save lower 32 bits of R3 PUSHF R3 Save upper 32 bits of R3 PUSH R4 Save lower 32 bits of R4 PUSHF R4 Save upper 32 bits of R3 PUSH AR4 Save AR4 Interrupt Handling Exit POP AR4 restore AR4 POPF R4 restore upper 32 bits of R4 POP R4 restore lower 32 bits of R4 POPF R3 restore upper 32 bits of R3 SUBI Zy OP deallocate local frame r r r r POP R3 restore lower 32 bits of R3 f POP FP restore Frame Pointer POP ST restore STatus register reti Notice
279. sing them as FP IRn Stack arguments are addressed in a similar way but with negative offsets from the FP The return address is stored at the location directly below the FP so the first argument is addressed as FP 2 Other arguments are addressed with increasing offsets up to a maximum of 255 words The IR registers are also used to access arguments with offsets larger than 255 SSS hl Note Avoid Locals and Arguments With Large Offsets It is desirable to avoid using locals and arguments with offsets larger than 255 words However if you must use locals and or arguments with large offsets the sequence used to access these variables is LDI offset IRn FP IRn This sequence incurs one additional instruction and three additional clock cycles each time it is used If you must use a larger local frame try to put the most frequently used variables within the first 255 words of the frame ee When register arguments are used it is critically important that the caller and callee agree both in type and number of arguments so that the called function can find the arguments Rules for argument passing are described in subsection 4 4 2 Arguments passed in registers can remain in those registers as long as the register is not needed for expression evaluation If registers con taining arguments must be freed for expression evaluation they can be copied to the local frame or other registers at function entry When you are no
280. sor 8 bit and 16 bit versions of the bmalloc function are provided The functions bmalloc8 and bmalloc16 are analogous to bmalloc however memory is allocated from the uninitialized sections Sysm8 and sysm16 respectively The linker creates a sysm8 or sysm16 section when a size is specified using the heap8 or heap16 option It will create a section of the default size 1K of 8 bit or 16 bit words when the bmalloc8 and bmalloc16 functions are used and the heap8 and heap16 options are not For more information refer to subsection 4 1 3 Dynamic Memory Allocation on page 4 4 Runtime Support Functions 5 29 bsearch Alphabetical Summary of Runtime Support Functions Syntax Defined in Description Example Array Search include lt stdlib h gt void bsearch void key void base size_t nmemb size_t size int compar void bsearch c in rts src The bsearch function searches through an array of nmemb objects for a member that matches the object that key points to Argument base points to the first member in the array size specifies the size in bytes of each member The contents of the array must be in ascending sorted order If a match is found the function returns a pointer to the matching member of the array if no match is found the function returns a null pointer 0 Argument compar points to a user defined function that compares key to the array elements The comparison function should be decla
281. src The atexit function registers the function that is pointed to by fun to be called without arguments at normal program termination Up to 32 functions can be registered When the program exits through a call to the exit function a call to abort or a return from the main function the functions that were registered are called without arguments in reverse order of their registration Runtime Support Functions 5 27 atof atoi atol Alphabetical Summary of Runtime Support Functions atof atoi atol Convert ASCII to Number Syntax include lt stdlib h gt double atof char nptr int atoi char nptr long int atol char nptr Defined in atof c and atoi c in rts src Description Three functions convert strings to numeric representations The atof function converts a string into a floating point value Argument nptr points to the string the string must have the following format space sign digits digits e E sign integer The atoi function converts a string into an integer Argument nptr points to the string the string must have the following format space sign digits The atol function converts a string into a long integer Argument nptr points to the string the string must have the following format space sign digits The space is indicated by one or more of the following characters a space character a horizontal or vertical tab a carriage return a form feed or a newline Following th
282. ssembler is the assembly language file produced by the code generator The assembler produces a COFF object file The assembler is described fully in the TMS320C3x C4x Assembly Language Tools User s Guide The inputs for the interlist utility are the assembly file produced by the compiler and the C source file The utility produces an expanded assembly source file containing statements from the C file as assembly language comments Section 2 6 on page 2 49 describes the interlisting file and subsection 2 9 4 on page 2 64 describes the use of the interlist utility The input for the linker is the COFF object file produced by the assembler The linker produces an executable object file Section 2 10 describes how to run the linker The linker is described fully in the TMS320C3x C4x Assembly Language Tools User s Guide 2 9 1 Invoking the Parser The first step in compiling a TMS320C3x C4x C program is to invoke the C parser The parser reads the source file performs preprocessing functions checks the syntax and produces an intermediate file that can be used as input for the code generator To invoke the parser enter ac30 input file output file options ac30 is the command that invokes the parser input file names the C source file that the parser uses as input If you don t supply an extension the parser assumes that the file s extension is c output file names the intermediate file that the parser creates If you don
283. ster 4 4 specifying filenames sprintf function sqrt function square root srand function SS compiler pion 2 13 p 13 P 49 2 50 sscanf function stack reserved space stack linker option stack management 4 4 stack pointer Stack section STACK_SIZE constant static varabies Baal reserved space stdarg h header __STDC__ 2 31 stddef h header 5 9 stden macro 5 10 stdin macro 5 10 stdio h header ore stdlib h header 5 10 5 17 stdout macro 5 10 store object function 5 38 strcat function 5 63 strchr function 5 64 strcmp function 5 64 strcoll function 5 64 strcpy function 5 65 strespn function 5 65 strerror function 5 66 sirftime function 5 66 string copy 5 70 Index strtok string h header strlen function strncat function strncmp function strncpy function strpbrk function strrchr function strspn function strstr function strtod function strtok function strtol function strtoul function structure members strxfrm function STYP_CPY flag 2 70 suppress all output except error messages banner information line and file information linker option suppressing warning messages 2 52 switch section 2 74 2 75 symbolic debugging symbolic debugging directives 2 12 Sysmem section 4 3 system constraints MEMORY_SIZE STACK _SIZE system initialization autoinitialization syste
284. strates a C function called main which calls an assembly language function called asmfunc The asmfunc function takes its single argument adds it to the C global variable called gvar and returns the result Note that this example can be used with either of the argument passing conventions In the assembly language code in Example 4 1 note the underscores on all the C symbol names Note also how the DP must be set only when accessing global variables in the big model For the small model the LDP instruction can be omitted To use this example with either the large or small model use the predefined symbol BIGMODEL to conditionally assemble the LDP statement Interfacing C With Assembly Language Example 4 1 An Assembly Language Function Called From C a C Program extern int asmfunc declare extern asm function int gvar define global variable main int i i asmfunc i call function normally b Assembly Language Program FP set AR3 FP is AR3 global _asmfunc Declare external function global _gvar Declare external variable _asmfunc if REGPARM 0 standard runtime model PUSH FP Save old FP LDI SP FP Point to top of stack LDI FP 2 AR2 Load argument into AR2 endif Both runtime models if BIGMODEL LDP _gvar Set DP to page of gvar endif BIG MODEL ONLY LDI _gvar RO ADDI AR2 RO RO gvar argument if REGP
285. string h gt char strstr char s1 char s2 strstr c in rts src The strstr function finds the first occurrence of s2 in s1 excluding the terminating null character If strstr finds the matching string it returns a pointer to the located string if it doesn t find the string it returns a null pointer If s2 points to a string with length 0 strstr returns s1 char stra so what do you want for nothing char strb what char ptr ptr strstr stra strb The pointer ptr now points to the w in what in the first string strtod strtol strtoul Syntax Defined in Description Alphabetical Summary of Runtime Support Functions strtod strtol strtoul Convert String to Numeric Value include lt stdlib h gt double strtod char nptr char endptr long int strtol char nptr char endptr int base unsigned long int strtoul char nptr char endptr int base strtod c in rts src strtol c in rts src and strtoul c in rts src Three functions convert ASCII strings to numeric values For each function argument nptr points to the original string Argument endptr points to a pointer the functions set this pointer to point to the first character after the converted string The functions that convert to integers also have a third argument base which tells the function on which base to interpret the string The sirtod function converts a string to a floating point value The string
286. t access them from C Object code for them is provided in any of the runtime object libraries provided listed in Section 2 3 on page 2 35 Any of these functions that your program needs are linked in automatically if you name one of these libraries as input at link time The source code for these functions is provided in the source library rts src The source code has comments that describe the operation and timing of the functions You can extract inspect and modify any of the math functions be sure you follow the special calling conventions and register saving rules out lined in this section Table 4 4 summarizes the runtime support functions used for arithmetic Runtime Environment 4 33 Runtime Support Arithmetic Routines Table 4 4 Summary of Runtime Support Arithmetic Functions Function MPY_130 MPY_K30 MPY_LD DIV_I30 DIV_l40 DIV_U30 DIV_U40 DIV_F30 DIV_F40 DIV_LD INV_F30 INV_F40 INV_LD MOD 130 MOD _ 140 MOD_U30 MOD_U40 Description Integer multiply Integer multiply by constant 40 bit float multiply Integer divide Integer divide Unsigned integer divide Unsigned integer divide Floating point divide Floating point divide 40 bit float divide Floating point reciprocal Floating point reciprocal 40 bit float reciprocal Integer modulo Integer modulo Unsigned integer modulo Unsigned integer modulo Defined In mpyi asm mpyk asm mpyld asm divi asm divi asm divu asm divu asm divf asm divf asm
287. t addressing With the small memory model it would be necessary to require that the bss and the const sections be on the same data page if the values were placed in the const section The CONST table and the const section are not the same The CONST table contains the following Initializing Static and Global Variables Integer constant expressions wider than 16 bits DD Floating point constant expressions with exponents larger than 4 bits or mantissas larger than 11 bits J Integer local variable initializers wider than 16 bits D Floating point local variable initializers with exponents larger than 4 bits or mantissas larger than 11 bits Addresses of global variables Addresses of string constants The const section contains the following Tables for switch statements D String constants that do not initialize global variables The CONST table when using big model TMS320C3x C4x C Language 3 19 Far Call Support 3 8 Far Call Support A function can be declared with the keyword far to signify to the compiler that calls to that function should be made using a 32 bit far call an indirect call through a register instead of a label The resulting assembly code will load the address of the function into a register and then call unconditionally to that reg ister The far call allows address offsets of greater than 16 bits to be used when calling that function at the cost of one additional instruction
288. t supply a filename for the output file the parser uses the input filename with an extension of if options affect parser operation Each option available for the standalone parser has a corresponding shell option that performs the same function Table 2 4 shows the shell options the parser options and the corresponding functions C Compiler Description 2 57 Invoking the Tools Individually Table 2 4 Parser Options and Shell Options ac30 Option name dname def i i dir k Iname lowercase L mb mr f 2 58 Shell Option name p dname def uname VXX pw0 or pw pwi pw2 Function causes the parser to read options from the specified file enable trigraph expansion predefine macro name treat code E errors as warnings prototype declared functions define include search path allow K amp R compatibility generate pp file use big memory model use register argument runtime model suppress line directives preprocess only compile all input modules into a single output module suppress progress messages quiet write parser error messages to file relax prototype checking relax pointer combination undefine macro name select CPU version suppress all warning messages enable serious warning messages default enable all warning messages disable inline expansion expand abs fabs and labs inline default define _
289. t using the optimizer the compiler needs the argument passing registers for expression evaluation so the arguments are copied to a local frame at function entry When you are using the optimizer the compiler attempts to keep register argumenis in their original registers Runtime Environment 4 21 Interfacing C With Assembly Language 4 5 4 5 1 4 22 Interfacing C With Assembly Language There are three ways to use assembly language in conjunction with C code Use separate modules of assembled code and link them with compiled C modules see subsection 4 5 1 page 4 22 This is the most versatile method Use inline assembly language embedded directly in the C source see subsection 4 5 3 page 4 28 Li Modify the assembly language code that the compiler produces Note Assembler Support for Runtime Models The two argument passing runtime models use different function structure and calling conventions Assembly language functions called by C need to retrieve arguments according to the runtime model that was used to compile the code The compiler and assembler provide support for the two runtime models in the form of two predefined symbols The assembler symbol REGPARM is set to 1 when mr is used and is set to 0 otherwise The compiler symbol _REGPARM is defined to be if mr is used and is set to 0 otherwise Example 4 1 on page 4 25 shows how to use these symbols to write code that will work with either
290. ter for which islower or isupper is true isascii identifies ASCII characters any character from 0 127 iscntrl identifies control characters ASCII characters 0 31 and 127 isdigit identifies numeric characters between 0 and 9 inclusive isgraph identifies any non space character islower identifies lowercase alphabetic ASCII characters isprint identifies printable ASCII characters including spaces ASCII characters 32 126 ispunct identifies ASCII punctuation characters isspace identifies ASCII spacebar tab horizontal or vertical carriage re turn form feed and new line characters isupper identifies uppercase ASCII alphabetic characters isxdigit identifies hexadecimal digits 0 9 a f A F The C compiler also supports a set of macros that perform these same functions The macros have the same names as the functions but are prefixed with an underscore for example _isascii is the macro equivalent of the isascii function In general the macros execute more efficiently than the functions Runtime Support Functions 5 45 Idexp localtime log Alphabetical Summary of Runtime Support Functions Syntax Defined in Description Example Syntax Defined in Description Syntax Defined in Description Example Multiply by a Power of Two include lt math h gt double Idexp double x int exp Idexp30 asm in rts src The Idexp function multiplies a floating point number x by a power of 2 gi
291. th this op tion calls to runtime support assembly arithmetic functions such as MPY _130 DIV_130 etc will use 32 bit far calls of the form LDI amp MPY_I30 Rx CALLU Rx rather than the traditional 16 bit displacement form of CALL MPY_130 See Section 3 8 on page 3 20 for more informa tion on far calls TMS320C3x only enables short multiplies generating MPYI instructions for integer multiplies rather than runtime support calls If your application does not need 32 bit integer multiplication use mm to enable the MPYI instruc tion it is significantly faster because it performs 24x24 bit multiplication using a single instruction rather than a call to a 32 bit library function For more information refer to Section 4 7 on page 4 32 C Compiler Description 2 21 Compiling C Code mn mtc 2 22 re enables the optimizations disabled by g If you use the g option to generate symbolic debugging information many code generator optimizations are disabled because they disrupt the debugger performs speed optimizations at the cost of increased code size The mp option causes the code generator to increase code size when doing so will increase perfor mance This is most often seen in copying rather than mov ing instructions into branch delay slots from the destination block Refer to Section 3 9 on page 3 21 for further informa tion on how the compiler handles branch delay slots When this option is specified t
292. that file points to mode points to a string describing how to open the file Runtime Support Functions 5 15 Summary of Runtime Support Functions and Macros I O Functions continued a int fprintf FILE iop const char format int fputc int c register FILE fp int fputs const char ptr register FILE iop size_t fread void ptr size_t size size_t count FILE iop FILE freopen const char file const char mode register FILE iop int fscanf FILE iop const char fmt int fseek register FILE iop long offset int ptrname int fsetpos FILE iop const fpos_t pos long ftell FILE iop size_t fwrite const void ptr size_t size size_t count register FILE iop int getc FILE p int getchar void void perror const char s int printf const char format int putc int x FILE p int putchar int x int puts const char ptr int remove const char file int rename const char old const char new void rewind register FILE iop int scanf const char format void setbuf register FILE iop char buf int setvbuf register FILE iop 5 16 register char buf register int type register size t_size Description Writes to the stream that iop points to Writes a single character c to the stream that fp points to Writes the string pointed to by ptr points to the stream pointed to by iop Read
293. the following _SSA The device supports only one open stream at a time _MSA The device supports multiple open streams More flags can be added by defining them in stdio h Function pointers to the device drivers are called by the low level functions to perform I O on the specified device You must declare these functions with the interface specified in subsection B 2 Overview of Low Level I O Implementation on page B 3 The device drivers for the host that the C3x C4x debugger is run on are included in the C I O library Runtime Support Functions 5 23 add_device Alphabetical Summary of Runtime Support Functions Example This example does the following Adds the device mydevice to the device table Opens a file named teston that device and associate it with the file fid D Writes the string Hello world into the file Lj Closes the file include lt stdio h gt Declarations of the user defined device drivers
294. the function pointed to by fun to be called without arguments at normal program termination Converts a string to a floating point value Converts a string to an integer value Converts a string to a long integer value Allocate memory on a boundary 8 bit version TMS320C32 only 16 bit version TMS32C32 only Searches through an array of n objects for the object that key points to Allocates and clears memory for n objects each of size bytes 8 bit version TMS320C32 only 16 bit version TMS320C32 only Divides numer by denom producing a quotient and a remainder Runtime Support Functions 5 17 Summary of Runtime Support Functions and Macros General Utilities continued void exit int status void free void ptr void free8 void _prt void free16 void _prt long labs long j Idiv_t Idiv long numer long denom int Itoa long n char buffer void malloc size_t size void malloc8 amp size_t_size void malloc16 size_t_ size void minit void void minit8 void void minit16 void void qsort void base size_tn size_t _ size int _compar void int rand void void realloc void ptr size_t size void realloc8 void _ptr size_t _ size void realloc16 void _ptr size_t _size void srand unsigned seed double strtod char nptr char endptr long strtol char nptr char endptr int base unsigned long strtoul char nptr char endptr int b
295. tion autoinitialization 2 69 4 6 RAM model ROM model ax compiler option b interlist utility option 2 64 b linker option base 10 oar ad big memory model _BIGMODEL bit fields 3 3 block linker directive using to force bss into a 64K data page bmalloc function bmalloc16 function bmalloc8 function boot obj 2 68 branch delay slot jaa broken down time 5 52 bsearch function bss section 2 70 forcing into a 64K data page 2 36 Index 1 Index buffer define and associate function specification function BUFSIZE macro c compiler option extension 2 4 2 57 C language characteristics c library build utility option 6 2 c linker option 2 66 2 69 C source statements and assembly language C_DIR environment variable _c into C_OPTION environment variable 2 12 2 28 _Cax Seat time boeza 5 34 5 52 5 76 calloc function calloc16 ra calloc8 function ceil function cg30 character conversion functions a number of characters 5 74 eon ation multiple characlor Eaa read functions single character character constants 3 23 character sets character typing isalnum 5 45 ispunct isspace isupper Index 2 conversion functions 5 5 5 14 isxdigit toascii tolower toupper Cinit section Cl extension clear EOF race ee clearerr functio
296. tion stores the power in the int pointed to by exp If value is 0 both parts of the result are 0 double fraction int exp fraction frexp 3 0 amp exp after execution fraction is 75 and exp is 2 Read Stream include lt stdio h gt int fscanf FILE iop const char format fscanf c in rts src Reads from the stream pointed to by iop How to read the stream is described by a string pointed to by format Set File Position Indicator include lt stdio h gt int fseek register FILE iop long offset int ptr fseek c in rts src Sets the file position indicator for the stream pointed to by iop The position is specified by ptr For a binary file use offset to position the indicator from ptr For a text file offset must be 0 Alphabetical Summary of Runtime Support Functions fsetpos ftell fwrite getc Syntax Defined in Description Syntax Defined in Description Syntax Defined in Description Syntax Defined in Description Set File Position Indicator include lt stdio h gt int fsetpos FILE iop const fpos_t pos fsetpos c in rts src Sets the file position indicator for the stream pointed to by iop to pos The pointer pos must be a value from fgetpos on the same stream Get Current File Position Indicator include lt stdio h gt long ftell FILE iop ftell c in rts src Gets the current value of the file position indicator for a stream The stream is po
297. tle differently The compiler will try to fill delay slots with J conditional load instructions that include known safe source operands such as local auto variables parameters and constants If you know that all memory will return an appropriate value when accessed you can use the ms shell option to inform the compiler that these constraints are not necessary when filling delay slots D instructions located immediately following the delay slots of the conditional block i e instructions that will be executed if the condition is false instructions located at the destination block i e instructions that will be executed if the condition is true If the shell option mp is used the compiler will try to copy instructions rather than moving them which can lead to significant increases in speed If the compiler cannot fill any or at least a majority of the delay slots it will con dense the delayed branch into a non delayed branch instruction unless the mp option has been specified Any instructions found in the delay slots will be placed before the branch instruction The compiler makes this change in an attempt to conserve code size by deleting the NOPs that would normally be placed in the empty delay slots If the mp option has been specified the compiler will not condense delayed branches in this manner but will leave branches even with only one slot filled in an attempt to take advantage of cycle savings
298. to manage the C environment To link a library simply use the option on the command line lnk30 c filenames I ESZO lip L ELIO IID wr or lnk30 cr filenames ES30a dib i FLIPS 0 AID zrs Eight versions of the standard C runtime support libraries are included with the compiler Refer to section 2 3 for further information on the included runtime support libraries Generally the libraries shouldbe specified as the last filename on the command line because the linker searches libraries for unresolved references in the order that files are specified on the command line If any object files follow a library references from those object files to that library will not be resolved You can use the x option to force the linker to reread all libraries until references are resolved Whenever you specify a library as linker input the linker includes and links only those library member that resolve undefined references All C programs must be linked with an object module called boot obj When a program begins running it executes boot obj first boot obj contains code and data for initializing the runtime environment the linker automatically extracts boot obj and links it when you use c or cr and include rts lib in the link Chapter 5 describes additional runtime support functions that are included in rts lib These functions include ANSI C standard runtime support Linking C Code Initialization RAM and ROM Models The C co
299. together in any program including assembly language and library modules must agree on these three options Mixed model code may link without error but it will not run correctly The linker will issue an error mes sage if you try to link TMS320C4x code with TMS320C3x code The big and small memory models are further explained in subsection 2 3 1 page 2 36 Register argument and stack based models are explained in subsection 2 3 2 page 2 37 With these exceptions compiler options including runtime model options do not affect compatibility with other modules Eight runtime libraries are shipped with the compiler All are compiled for the small memory model convention Runtime Library Processor Model Option s Used rts30 lib TMS320C3x small memory model stack based model rts30g lib TMS320C3x stack based model includes symbolic debugging information rts30r lib TMS320C3x register argument model rts30gr lib TMS320C3x register argument model includes symbolic debugging information rts40 lib TMS320C4x small memory model stack based model rts40g lib TMS320C4x stack based model includes symbolic debugging information rts40r lib TMS320C4x register argument model rts40gr lib TMS320C4x register argument model includes symbolic debugging information C Compiler Description 2 35 Using Runtime Models Refer to Section 5 1 for further information If you want to use a model that is incompatible with these you must build a compatible version o
300. trolling the Preprocessor es 2 3 Using Runtime Modelsm reece e ee eeeneees 2 35 2 4 Using the C Compiler Optimizer cs 2 5 Function Inlining 00 e cece ete eee eens 2 6 Using the Interlist Utility 0 2 7 How the Compiler Handles Errors se 2 51 fs USS soncdcenonnbassncnadanboocndencapnoconannonooaeocnne 2 9 Invoking the Tools Individually 0 ccc eee cence eee 210 Linking C Code m a a hse ences eeneeece ee epcinn 2 1 Compiling C Code 2 1 Compiling C Code The cl30 shell program is a utility that lets you compile assemble and optionally link in one step The shell runs one or more source modules through the following The compiler which includes the parser the optimizer and the code generator The assembler which generates a COFF object file The linker which links your files to create an executable object optional file The linker can be invoked as part of the larger process or you can compile and assemble various files with the shell and link at a later time For more information about the floating point assembler and linker refer to the TMS320C3x C4x Assembly Language Tools User s Guide By default the shell compiles and assembles files however if you use the z option the shell also links your files Figure 2 1 illustrates the path the shell takes with and without the z option Figure 2 1 The cl30 Shell Program Overview C Compiler Pase Optimizer Optional Code G
301. ty When using the TMS320C3x C4x C compiler you can compile your code under a number of different configurations and options which are not neces sarily compatible with one another Since it would be cumbersome to include all possible combinations in individual runtime support libraries this package includes the source file rts src that contains all runtime support functions and all floating point support functions By using the mk30 utility described in this chapter you can custom build your own runtime support libraries for the options you select These are the topics covered in this chapter Topic Page 6 1 Invoking the Library Build Utility 00cceeeeeeeeees 6 2 6 2 Options Summary 6 1 Invoking the Library Build Utility 6 1 Invoking the Library Build Utility The general syntax for invoking the library utility is mk30 options src_arch 1 lobj lib1 src_arch2 lobj lib2 mk30 options src_arch lobj lib is the command that invokes the utility can appear anywhere on the command line or in a command file Options are discussed in Section 6 2 and below is the name of a source archive file For each source archive named mk30 will build an object library according to the runtime model specified by the command line options is the optional object library name If you do not specify a name for the library mk30 uses the name of the source archive and appends a ib suffix
302. ty 2 49 2 64 library build utility 6 2 linker optimizer parser isalnum function isalpha function isascii function 5 45 iscntrl function isdigit function 5 45 isgraph function islower function 5 45 isprint function ispunct function isspace function Index 6 isupper function isxdigit function isxxx function 5 45 k compiler option k library build utility option K amp R 2 16 compatibility 3 5 25 l library build utility option linker option 2 66 L_tmpnam macro 5 9 labs function as intrinsic ldexp function Idiv function Idiv_t type libraries library build utility 1 4 6 16 6 optional a library options limits compiler3 24 floating pat yix p25 integer types pa limits h header 5 6 line and file information suppressing line directive LINE _2 31 linker invocation 2 65 Ink30 command options heap 2 24 pie 16 Z z enabling option linker command file 2 74 linking C code 2 6 42 75 linking with the shell program 2 66 listing file ing 2 16 generating 2 16 localtime baer 5 4 5 46 5 52 log function 5 46 log10 function long double data longjmp function type low level I O functions LSEEK I O function ltoa function m linker option ma compiler option 2 20 macro expansions 2 34 macro definitions macros Index malloc
303. type that is the data type of the sizeof operator fpos_t An unsigned long type that can uniquely specify every position within a file FILE A structure type to record all the information necessary to control a stream Runtime Support Functions 5 9 Header Files Macro Declarations The following table lists the macros defined in stdio h Macro Description NULL Expands to a null pointer constant 0 Originally defined in stddef h It is not redefined if it was already defined BUFSIZ Expands to the size of the buffer that setbuf uses EOF The end of file marker FOPEN_MAX Expands to the largest number of files that can be open at FILENAME_MAX one time Expands to the length of the longest file name in characters L_tmpnam Expands to the longest filename string that tmpnam can generate SEEK_CUR Expand to indicate the position current start of file or SEEK_SET end of file respectively in a file SEEK_END TMP_MAX Expands to the maximum number of unique filenames that tmpnam can generate stderr Pointers to the standard error input and output files re stdin spectively stdout 5 2 11 General Utilities stdlib h The stdlib h header declares several functions one macro and two types The macro is named RAND_MAX The types include ov ta structure type that is the type of the value returned by the div function div_t a structure type that is the type of the value returned by the Idiv function
304. uctions directives and macro directives The assembler substitutes absolute operation codes for symbolic operation codes and absolute or relocatable addresses for symbolic addresses assignment statement A statement that assigns a value to a variable autoinitialization The process of initializing global C variables contained in the cinit section before beginning program execution binding Associating or linking together two complementary software objects block A set of declarations and statements that are grouped together with braces C 1 Glossary C 2 bss One of the default COFF sections You can use the bss directive to reserve a specified amount of space in the memory map that can later be used for storing data The bss section is uninitialized C compiler A program that translates C source statements into TMS320C3x C4x assembly language source statements COFF common object file format A binary object file format that promotes modular programming by supporting the concept of sections comment A source statement or portion of a source statement that is used to document or improve readability of a source file Comments are not compiled assembled or linked they have no effect on the object file constant A numeric value that can be used as an operand cross reference lister A debugging tool that accepts linked object files as input and produces cross reference listings as output cross referenc
305. uences of the form 2 C where cis a character The ANSI C standard defines these sequences for the purpose of compiling programs on sys tems with limited character sets By default the compiler does not recognize trigraphs use p to enable trigraphs For more information refer to the ANSI specification subsection 2 2 1 1 or K amp R A 12 1 controls function inlining done by the optimizer when func tions have been defined or declared as inline The possibilities are D x0 disables all inlining x1 inlines all intrinsic operators default J X2 or X invokes the optimizer at level 2 and defines the _INLINE preprocessor symbol which causes all functions defined or declared as inline to be expanded in line Note that x1 is the default inlining option It occurs whether or not the optimizer is invoked and whether or not any x options are specified The last option may be specified as x or x2 interchangeably See Section 2 5 on page 2 43 for more details Type Checking Options tf Compiling C Code relaxes type checking on redeclarations of prototyped functions In ANSI C if a function is declared with an old format declaration such as int func and then later declared with a prototype such as int func float a char b this generates an error because the parameter types in the prototype disagree with the default argument conversions which convert float to double and char to int
306. ult heap size is 1K words For the TMS320C32 processor 8 bit and 16 bit versions of the calloc function are provided The functions calloc8 and calloc16 are analogous to calloc how ever memory is allocated from the uninitialized sections sysm8 and sysm16 respectively The linker creates a sysm8 or sysm16 section when a size is specified using the heap8 or heap16 option It will create a section of the default size 1K of 8 bit or 16 bit words when the calloc8 and calloc16 functions are used and the heap8 and heap16 options are not For more information refer to subsection 4 1 3 Dynamic Memory Allocation on page 4 4 This example uses the calloc routine to allocate and clear 10 bytes ptr calloc 10 2 Allocate and clear 20 bytes Runtime Support Functions 5 31 ceil clearerr Alphabetical Summary of Runtime Support Functions Syntax Defined in Description Example Syntax Defined in Description Ceiling include lt math h gt double ceil double x ceil c in rts src The ceil function returns a floating point number that represents the smallest integer greater than or equal to x The ceil function is inlined if the x2 option is used double answer answer ceil 3 1415 answer 4 0 answer ceil 3 5 answer 3 0 Clear EOF and Error Indicators include lt stdio h gt void clearerr FILE p clearerr c in rts src Clears the EOF and error indicators for the st
307. ult type is a signed version of the wider type This affects options that perform differently when applied to signed or unsigned operands Namely comparisons division and mod and right shift In this example assume that short is narrower than int unsigned short u int i if u lt i SIGNED comparison unless pk used D ANSI prohibits two pointers to different types from being combined in an operation In most K amp R compilers this situation is only a warning Such cases are still diagnosed when pk is used but with less severity int p char q p error without pk warning with pk Even without pk a violation of this rule is acode E recoverable error An alternative to using pk to work around this situation is to use pe which converts code E errors to warnings D External declarations with no type or storage class identifier only are ille gal in ANSI but legal in K amp R a illegal unless pk used Compatibility With K amp R C pk Option ANSI interprets file scope definitions that have no initializers as tentative definitions in a single module multiple definitions of this form are fused together into a single definition Under K amp R each definition is treated as a separate definition resulting in multiple definitions of the same object and usually an error For example int a int a illegal if pk used OK if not Under ANSI the result of these two declarati
308. ults in variables manipulated in or around the inserted code Directives that change sections or otherwise affect the assembly environment can also be troublesome Be especially careful when you use the optimizer with asm statements Although the optimizer cannot remove asm statements it can significantly rearrange the code order near asm statements possibly causing undesired results The asm command is provided so that you can access features of the hardware which by definition C is unable to access ES The asm statement is also useful for inserting comments in the compiler output simply start the assembly code string with an asterisk as shown below asm this is an assembly language comment Runtime Environment 4 29 Interrupt Handling 4 6 Interrupt Handling Interrupts can be handled directly with C functions by using a special naming convention c_intnn nn is a two digit interrupt number between 00 and 99 For example c_int01 Using one of these function names defines an interrupt routine When the compiler encounters one of these function names it generates code that allows the function to be activated from an interrupt trap Note that c_int00 is the C boot routine and should not be used as an interrupt routine See Section 4 8 on page 4 36 for further information on this routine A C interrupt routine is like any other C function in that it can have local variables and register variables however it
309. ure 4 2 Register Argument Conventions int fl int a int b int c function call AR2 R2 R3 lt where parameters are placed int f 2 int a float b int c struct Ad float e Int f call AR2 R2 RC RS R3 RE lt parameters int 3 float a int b float c int d float e call R2 AR2 R3 RC STACK lt parameters int f4 struct x a int b int C int d int e int f int g int h AR2 R2 R3 RC RS RE STACK STACK Notice how R2 and R3 are allocated first to any floats in the argument list Then a second pass allocates remaining arguments to remaining registers Runtime Environment 4 17 Function Structure and Calling Conventions If a function is declared with an ellipsis indicating that it can be called with varying numbers of arguments the convention is modified slightly The last explicitly declared argument is passed on the stack so that its stack address can act as a reference for accessing the undeclared arguments For example int vararg int a int b AR2 STACK STACK STACK STACK 2 The caller calls the function 3 The caller pops the arguments that were passed on the stack if any Register Argument Model for Runtime Support Functions The runtime support assembly asm files use a modified version of the register argument calling convention Four registers R1 R2 R3 and R4 are used to pass arguments as follows m Integer floating point and pointer argume
310. used There are three levels available D on0 do not produce an information file Restores the default behavior of the optimizer if you have used one of the other two options in a command file an environment variable etc on1 produce an optimization information file on2 produce a verbose optimization information file m m specifies whether functions in other files can call this file s EXTERN functions or modify this files EXTERN variables Level 3 optimization combines this information with its own file level analysis to decide whether to treat this file s EXTERN function and variable definitions as if they had been declared STATIC The following levels are defined op0 signals the optimizer that functions in this module may be called by other modules and variables declared within the module may be altered by other modules This disables some of the 03 optimizations op1 signals the optimizer that no functions in this module will be called by other modules and no interrupt functions declared elsewhere will call functions defined in this module This is the default when 03 is used J op2 or op signals the optimizer that no functions in this module are called by other modules and no variable declared in this module will be altered by another module op3 signals the optimizer that functions in this module may be called by other modules but no variables declared within the module may be altered by
311. ush Syntax Defined in Description Syntax Defined in Description Syntax Defined in Description Syntax Defined in Description Close File include lt stdio h gt int fclose FILE iop fclose c in rts src Flushes the stream that iop points to When the stream is flushed the function closes the file associated with the stream Test EOF Indicator include lt stdio h gt int feof FILE p feof c in rts src Tests the EOF indicator for a stream The stream is pointed to by p Test Error Indicator include lt stdio h gt int ferror FILE p ferror c in rts src Tests the error indicator for a stream The stream is pointed to by p Flush I O Buffer include lt stdio h gt int fflush register FILE iop fflush c in rts src Flushes the MO buffer for a stream The stream is pointed to by iop Runtime Support Functions 5 37 fgetc fgetpos fgets Alphabetical Summary of Runtime Support Functions Syntax Defined in Description Syntax Defined in Description Syntax Defined in Description Read Next Character include lt stdio h gt int fgetc register FILE fp fgetc c in rts src Reads the next character in a stream the stream is pointed to by fp Store Object include lt stdio h gt int fgetpos FILE iop foos_t pos fgetpos c in rts src Stores the object pointed to by pos The object is stored to the current value of the file position indicator fo
312. utine ROM model knows when to stop reading the initialization tables J Inthe RAM model cr option m The linker sets the symbol cinit to 1 This indicates that the initialization tables are not in memory so no initialization is performed at runtime C Compiler Description 2 69 Linking C Code mM The STYP_COPY flag 010h is set in the cinit section header STYP_COPY is the special attribute that tells the loader to perform autoinitialization directly and not to load the cinit section into memory The linker does not allocate space in memory for the cinit section Note that a loader is not included as part of the C compiler package J Inthe ROM model c option the linker defines the symbol cinit as the starting address of the cinit section The C boot routine uses this symbol as the starting point for autoinitialization Sections Created by the Compiler The compiler produces five relocatable blocks of code and data These blocks called sections can be allocated into memory in a variety of ways to conform to a variety of system configurations The compiler creates two basic kinds of sections initialized and uninitialized Table 2 7 summarizes the sections Table 2 7 Sections Created by the Compiler Name Type Contents bss Uninitialized global and static variables Cinit Initialized initialization values for explicitly initialized global and static variables const Initialized global and static constant
313. variable i word 1 Length of data 1 word word _i Address in bss word 23 Data to initialize i Initialization record for variable a word 5 Length of data 5 words word _a Address in bss word 127374 5 Data to initialize a The cinit section contains only initialization tables in this format If you are interfacing assembly language modules to your C program do not use the cinit section for any other purpose When you link a program with the c or cr option the linker links together the cinit sections from all the C modules and appends a null word to the end of the entire section This appears as a record with a size field of 0 and marks the end of the initialization tables Initializing Variables in the RAM Model The RAM model specified with the cr linker option allows variables to be initialized at oaa time instead of at runtime This can enhance performance by reducing boot time and by saving the memory used by the initialization tables The RAM option requires the use of a smart loader to perform the initialization as it copies the program from the object file into memory In the RAM model the linker marks the cinit section with a special attribute STYP_CPY equals 1 This means that the section is notloaded into memory and does not occupy space in the memory map The linker also sets the sym bol cinit to 1 to indicate to the C boot routine that the initialization tables are not present in m
314. variables that are explicitly initialized and string literals stack Uninitialized software stack text Initialized executable code and floating point constant Sysmem Uninitialized memory for malloc functions When you link your program you must specify where to locate the sections in memory In general initialized sections can be linked into ROM or RAM uninitialized sections must be linked into RAM Refer to subsection 4 1 1 on page 4 2 for a complete description of how the compiler uses these sections The linker provides MEMORY and SECTIONS directives for performing this process For more information about allocating sections into memory refer to Chapter 9 in the TMS320C3x C4x Assembly Language Tools User s Guide Sizing the Stack and Heap The linker provides four options that allow you to specify the size of the stack and sysmem sections 2 70 Linking C Code stackxxxx sets the size of the stack section to xxxx words The value xxxx must be constant heapxxxx sets the size of the sysmem section to xxxx words The value Xxxx must be constant heap8xxxx sets the size of the sysm8 section to xxxx words for C32 8 bit memory support The value of xxxx must be constant heap16xxxx sets the size of the sysm16 section to xxxx words for C32 16 bit memory support The value of xxxx must be constant The linker always includes the stack section and includes the sysmem Sysm8 or sysm16 sections onl
315. ven by exp and returns x x 2 XP The exponent exp can be a negative or a positive value A range error may occur if the result is too large double result result is 48 0 result ldexp 1 5 5 result is 0 75 result ldexp 6 0 3 Local Time include lt time h gt struct tm localtime time_t timer localtime c in rts src The localtime function converts a calendar time represented as a value of type time_tinto a broken down time in a structure The function returns a point er to the structure representing the converted time For more information about the functions and types that the time h header declares refer to subsection 5 2 13 page 5 11 Natural Logarithm include lt math h gt double log double x log c in rts src The log function returns the natural logarithm of a real number x A domain error occurs if x is negative a range error occurs if x is 0 float x y x 2 718282 y log x Return value 1 0 Syntax Defined in Description Example Syntax Defined in Description Example Alphabetical Summary of Runtime Support Functions log10 ltoa Common Logarithm include lt math h gt double log10 double x log10 c in rts src The log10 function returns the base 10 logarithm or common logarithm of a real number x A domain error occurs if x is negative a range error occurs if x is 0 float x y x 10 0 y log x Return value 1 0
316. via the FIX instruction However the intrinsic gives you expression by expression control over this effect The intrinsic performs the fast conversion whether or not the shell option is specified The ansi_ftoi intrinsic causes the compiler to perform an ANSI compatible floating point to integer conversion via a standard sequence of instructions The intrinsic gives you expression by expression control over this effect Note that the ansi_ftoi intrinsic overrides the mc shell op tion the compiler will perform the ANSI compatible conversion even if the mc shell option is specified The fast_imult intrinsic is similar to the mm shell option in that both cause the compiler to use 24 bit multiplication via the MPYI instruction However the intrinsic gives you expression by expression control over this effect The intrinsic performs the 24 bit multiplication whether or not the shell option is specified If the fast_invf instrinsic is used the compiler will use the 16 bit RCPF instruction rather than a 32 bit call to the INV_F40 function C Compiler Description 2 55 Invoking the Tools Individually 2 9 Invoking the Tools Individually Compiler The TMS320C3x C4x C compiler offers you the versatility of invoking all of the tools at once using the shell or invoking each of the tools individually To satisfy a variety of applications you can invoke the compiler parser optional optimizer and code generator the assembler and the lin
317. voking the Code Generator The third step in compiling a TMS320C3x C4x C program is to invoke the C code generator As Figure 2 3 on page 2 56 shows the code generator converts the intermediate file produced by the parser into an assembly language source file for input to the TMS320 floating point assembler You can modify this output file or use it as input for the assembler The code generator produces re entrant relocatable code which after assembling and linking can be stored in ROM To invoke the code generator as a standalone program enter cg30 input file output file tempfile options cg30 is the command that invokes the code generator input file names the intermediate file that the code generator uses as input If you don t supply an extension the code generator assumes that the extension is if If you don t specify an input file the code generator will prompt you for one output file names the assembly language source file that the code generator creates If you don t supply a filename for the output file the code generator uses the input filename with the extension of asm tempfile names a temporary file that the code generator creates and uses The default filename for the temporary file is the input filename appended to an extension of tmp The code generator deletes this file after using it options affect the way the code generator processes the input file Each option available for the standalone
318. word and subsection near and far keywords 3 1 1 The cregister Keyword The TMS320C3x C4x compiler extends the C language by adding the cregis ter keyword to allow high level language access to control registers When you use the cregister keyword on an object the compiler compares the name of the object to a list of standard control registers for the C3x C4x see Table 3 2 If the name matches the compiler generates the code to reference the control register If the name does not match the compiler issues an error Table 3 2 Valid Control Registers Register Description IE CPU DMS interrupt enable register IF CPU interrupt flag register IOF I O flags ST Status register The cregister keyword can only be used in file scope The cregister keyword is not allowed on any declaration within the boundaries of a function It can only be used on objects of type integer or pointer The cregister keyword is not al lowed on objects of any floating point type or on any structure or union object The cregister keyword does not imply that the object is volatile If the control register being referenced is volatile that is can be modified by some external control then the object should be declared with the volatile keyword also To use a control register in Table 3 2 you must declare each register with or without volatile as follows extern cregsiter volatile unsigned int register Once you have declared the register you can
319. xternal objects far data flag disable RPTS instructions use far calls for runtime support assembly calls enable short multiply CC3x only reenable optimizer options disabled by g perform speed operations at the cost of conservatively increased code size use TI register argument model assume all memory is accessible when optimizing see page 2 22 generate Ada compatible frame structure generate legacy Tartan C function names Effect create absolute listing predefine a constant produce assembly listing file keep labels as symbols undefine a constant produce cross reference file C Compiler Description 2 9 Compiling C Code Table 2 1 Compiler Options Summary Table Continued 2 10 Linker Options These options are valid only when the compiler has been invoked with the z option for linking They control the linking process They must follow the z option on the command line and the z option must follow all other options and file names on the command line For more information see page 2 23 Options a ar heap size heap8 size heap16 size i dir l ib m file n o file 9 s stack size usym vval W X Effect generate absolute output generate relocatable output disable the merging of symbolic debug information use ROM initialization use RAM initialization define entry point define fill value keep named global
320. y if you use memory allocation functions such as malloc malloc8 or malloc16 The default size for all sections is 1K 1024 words Note however that the sysm8 and sysm16 sections are not created unless the 8 bit or 16 bit memory support functions are linked Allocating the bss and const Section When you use the small memory default model the sum of the entire bss and const section must fit within a single 64K word long data page and must not cross any 64K address boundaries Use the linker s block qualifier to help guarantee the correct allocation of bss and const Sample Linker Command File The compiler package includes two sample linker command files called c30 cmd and c40 cmd that can be used to link C programs To link your program using a command file enter the following command lnk30 object files o output file m map file c30 cmd Figure 2 4 shows the contents of c30 cmd Figure 2 5 shows the contents of c40 cmd To link your program using the TMS320C4x command file enter the following command lnk30 object files o output file m map file c40 cmd C Compiler Description 2 71 Linking C Code Figure 2 4 Sample Linker Command File for TMS320C 3x C Programs KK KK I I A IA IA IA A IA A IA IA I IA I IA IA IA A I I A A A I A I Oe He C30 CMD v4 60 COMMAND
321. ynamic Memory Allocation 4 4 The runtime support library supplied with the compiler contains several functions such as malloc calloc and realloc that allow you to dynamically allocate memory for variables at runtime Dynamic allocation is not a standard part of the C language it is provided by standard runtime support functions Memory is allocated from a global pool or heap that is defined in the sysmem section You can set the size of the sysmem section by using the Memory Model heap option when you link your program Specify the size of the memory pool as a constant after the heap option on the linker command line The linker also creates a global symbol _ SYSMEM_SIZE and assigns it a value equal to the size of the heap in words The default size is 1K words For more information on the heap option refer to the TMS320C3x C4x Assembly Language Tools User s Guide Dynamically allocated objects are not addressed directly they are always accessed with pointers and the memory pool is in a separate section therefore the dynamic memory pool can have an unlimited size even in the small memory model This allows you to use the more efficient small memory model even if you declare large data objects To conserve space in the bss you can allocate large arrays from the heap instead of declaring them as global or static For example instead of a declaration such as struct big table 10000 use a pointer and call the m
322. ys several advanced techniques for generating efficient compact code from C source General optimizations can be applied to any C code and TMS320C3x C4x specific optimizations take advantage of the particular features of the TMS320C3x C4x architecture For more information about the C compiler s optimization techniques refer to Section 2 4 on page 2 38 and to Appendix A ANSI Standard Runtime Support The compiler package comes with eight complete runtime libraries All library functions conform to the ANSI C library standard The libraries include functions for string manipulation dynamic memory allocation data conver sion timekeeping and trigonometry plus exponential and hyperbolic functions Functions for I O and signal handling are not included because these are target system specific For more information refer to Chapter 5 Assembly Source Output The compiler generates assembly language source that is easily inspected enabling you to see the code generated from the C source files Big and Small Memory Models The compiler supports two memory models The small memory model enables the compiler to efficiently access memory by restricting the global data space to a single 64K word data page The big memory model allows unlimited data space For more information refer to subsection 2 3 1 on page 2 36 Compiler Shell Program The compiler package includes a shell program which enables you to compile assemble and link pro

"TMS320C3x/C4x Optimizing C Compiler User's Guide"

Contents

Download Pdf Manuals

Related Search

Related Contents

&quot;TMS320C3x/C4x Optimizing C Compiler User's Guide&quot;

Contents

Download Pdf Manuals

Related Search

Related Contents

"TMS320C3x/C4x Optimizing C Compiler User's Guide"