Home

VisualDSP 3.5 C Compiler and Library Manual for

Contents

1. Sig Value Definition STGPWRDWN Power down interrupt STGIRQ2 Interrupt 2 SIGIRQL1 Interrupt 1 level sensitive SIGIRQLO Interrupt 0 level sensitive SIGSPORTOXMIT Signal Sport 0 transmit STGSPORTORECY Signal Sport 0 receive SIGIRQE Level sensitive SIGBDMA Byte DMA interrupt SIGSPORTIXMIT Signal Sport 1 transmit SIGIRQ1 Interrupt 1 STGSPORTIRECV Signal Sport 1 receive STGIRQO Interrupt 0 SIGTIMER Timer interrupt SIGABRT Software abort signal SIGILL Software illegal signal SIG Software segmentation signal SIGTERM Software termination signal SIGFPE Software floating point exception signal 3 72 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library The interrupt function causes the receipt of the signal number sig to be handled in one of the following ways e SIG_DFL The default action is taken e SIG_IGN The signal is ignored e Function Address The function pointed to by func is executed The function pointed to by func is executed each time the interrupt is received The interrupt function must be called with the SIG_IGN argu ment to disable interrupt handling Interrupts are not nested by the default start up file Error Conditions The interrupt function returns SIG_ERR and sets errno equal to SIG_ERR if the requested interrupt is not recognized Example include lt signal h gt void handler int sig Interr
2. Figure 1 1 Project Options Compile Property Page VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler There are four sub pages you can access General Preprocessor Proces sor and Warning Most page options have a corresponding compiler command line switch described in Compiler Command Line Switches The Additional options field in each sub page is used to enter the appro priate file names and options that do not have corresponding controls on the Compile tab but are available as compiler switches Use the VisualDSP online Help to get more information on compiler options you can specify from the VisualDSP environment Compiler Command Line Switches Table 1 2 lists the command line switches accepted by the cc218x com piler A detailed description of each of these switches follows the table Table 1 2 Compiler Command Line Switches Switch Name Description filename Reads command line input from the file on page 1 18 A name tokens Asserts the specified name as a predicate on page 1 18 alttok Allows alternative keywords and sequences in sources on page 1 19 bss Causes the compiler to put global zero initialized data into a on page 1 20 separate BSS style section build lib Directs the librarian to build a library file on page 1 20 C Retains preprocessor comments in the output file must run on page 1 20 with the E or
3. VisualDSP 3 5 C Compiler and Library Manual 1 51 for ADSP 218x DSPs C Compiler Language Extensions C Compiler Language Extensions The compiler supports a set of extensions to the ISO ANSI standards for the C language These C extensions add support for DSP hardware and allow some C programming features This section contains e Inline Function Support Keyword inline on page 1 55 e Inline Assembly Language Support Keyword asm on page 1 56 e Dual Memory Support Keywords pm dm on page 1 71 e Placement Support Keyword section on page 1 76 e Boolean Type Support Keywords bool true false on page 1 77 e Pointer Class Support Keyword restrict on page 1 77 e Variable Length Array Support on page 1 78 e Non Constant Aggregate Initializer Support on page 1 80 e Indexed Initializer Support on page 1 80 e Aggregate Constructor Expression Support on page 1 82 e Preprocessor Generated Warnings on page 1 83 e C Style Comments on page 1 83 e ETSI Support on page 1 86 e Pragmas on page 1 99 e GCC Compatibility Extensions on page 1 117 1 52 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler The additional keywords that are part of these C extensions do not con flict with any ISO ANSI C keywords The formal definitions of these extension keywords are prefixed with a leading double underscore Unless the no extra
4. VisualDSP 3 5 C Compiler and Library Manual 3 161 for ADSP 218x DSPs C Run Time Library Reference timer_set initialize ADSP 218x DSP timer Synopsis d Finclude lt misc h gt int timer_set unsigned int tperiod unsigned int tcount int tscale Description This function is an Analog Devices extension to the ANSI standard The timer_set function sets the ADSP 218x DSP timer registers TPERIOD and TCOUNT The function returns a 1 if the timer is enabled a 0 if the timer is disabled The TSCALE value is used to set the TSCALE register For a complete description of the ADSP 218x DSP timer refer to the ADSP 218x DSP Hardware Reference Each interrupt call takes approximately 50 cycles on entrance and 50 cycles on return If tperiod and tcount are set too low you may incur initializing overhead that could create an infinite loop Error Conditions The timer_set function does not return an error condition Example d Finclude lt misc h gt if timer_set 1000 1000 1 1 timer_on enable timer See Also timer_off timer_on 3 162 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library tolower convert from uppercase to lowercase Synopsis include lt ctype h gt int tolower int c Description The tolower function converts the input character to lowercase if it is uppercase otherwise it returns the character Error Conditions The tolower function d
5. VisualDSP 3 5 C Compiler and Library Manual 3 103 for ADSP 218x DSPs C Run Time Library Reference memcpy copy characters from one object to another Synopsis include lt string h gt void memcpy void sl const void s2 size_t n Description The memcpy function copies n characters from the object pointed to by s2 into the object pointed to by s1 The behavior of memcpy is undefined if the two objects overlap The memcpy function returns the address of s1 Error Conditions The memcpy function does not return an error condition Example include lt string h gt char a SRC char b DEST result memcpy b a 3 D SRCT 7 See Also memmove strcpy strncpy 3 104 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs memmove copy characters between overlapping objects Synopsis d Finclude lt string h gt void memmove void sl const void s2 Description C Run Time Library size_t n The memmove function copies n characters from the object pointed to by s2 into the object pointed to by s1 The entire object is copied correctly even if the objects overlap The memmove function returns a pointer to s1 Error Conditions The memmove function does not return an error condition Example d Finclude lt string h gt char ptr str ABCDE ptr str 2 memmove str str 3 See Also memcpy strcpy strncpy str ABABC Visual
6. WISUAUBDSP 23 5 C Compiler and Library Manual for ADSP 218x DSPs Revision 4 1 October 2003 Part Number 82 000400 03 ANALOG peewee gt DEVICES Norwood Mass 02062 9106 Copyright Information 2003 Analog Devices Inc ALL RIGHTS RESERVED This docu ment may not be reproduced in any form without prior express written consent from Analog Devices Inc Disclaimer Analog Devices Inc reserves the right to change this product without prior notice Information furnished by Analog Devices is believed to be accurate and reliable However no responsibility is assumed by Analog Devices for its use nor for any infringement of patents or other rights of third parties which may result from its use No license is granted by impli cation or otherwise under the patent rights of Analog Devices Inc Trademark and Service Mark Notice The Analog Devices logo VisualDSP and the VisualDSP logo are registered trademarks of Analog Devices Inc All other brand and product names are trademarks or service marks of their respective owners CONTENTS CONTENTS PREFACE gtr 0 E E een EE N E EE E P EE E E EEA XXV LEE SARI sneren ANR XXV Manual Contents eee seisten xxvi Whats New m tie Mantal ends ccecerteersrndined tennteaatenienannrss xxvi Tebmecal or Customer Suppt cccream eona xxvii Supported Processi soros rana n EE xxvii Produce Informatioi secessus ia N xxviii My galog CON scistdesassusrtinsiese
7. Substitute a type name corresponding to the type of the next argument for the type parameter in each call to va_arg After processing the list call va_end The header file stdarg h defines a pointer type called va_list that is used to access the list of variable arguments The function calling va_arg is responsible for determining the number and types of arguments in the list It needs this information to determine how many times to call va_arg and what to pass for the type parameter each time There are several common ways for a function to determine this type of information The standard C printf function reads its first argument looking for sequences to determine the number and types of its extra arguments In the example below all of the arguments are of the same type char and a termination value NULL is used to indicate the end of the argument list Other methods are also possible VisualDSP 3 5 C Compiler and Library Manual 3 165 for ADSP 218x DSPs C Run Time Library Reference If a call to va_arg is made after all arguments have been processed or if va_arg is called with a type parameter that is different from the type of the next argument in the list the behavior of va_arg is undefined Error Conditions The va_arg macro does not return an error condition Example include lt stdarg h gt include lt string h gt include lt stdlib h gt char concat char sl int len 0 char result
8. fp associative The fp associative switch directs the compiler to treat floating point multiplication and addition as associative full version The full version display version switch directs the compiler to display version information for all the compilation tools as they process each file 9 The g generate debug information switch directs the compiler to out put symbols and other information used by the debugger VisualDSP 3 5 C Compiler and Library Manual 1 23 for ADSP 218x DSPs Compiler Command Line Reference When the g switch is used in conjunction with the enable optimization 0 switch the compiler performs standard optimizations The compiler also outputs symbols and other information to provide limited source level debugging through VisualDSP This combination of options provides line debugging and global variable debugging You can invoke this switch by selecting the Generate debug infor mation check box in the VisualDSP Project Options dialog box Compile tab General category When g and 0 are specified no debug information is available for local variables and the standard optimizations can sometimes re arrange program code in a way that inaccurate line number information may be produced For full debugging capabilities use the g switch without the 0 switch H The H list headers switch directs the compiler to output only a list of the files included by the preprocessor via the in
9. Error Conditions The 10g function returns a zero and sets errno to EDOM if the input value is negative Example d Finclude lt math h gt double y y log 1 0 y 0 0 See Also exp log10 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 3 97 C Run Time Library Reference log10 base 10 logarithm Synopsis d Finclude lt math h gt double logl0 double float logl0f float Description The 10g10 function returns the base 10 logarithm of its input Error Conditions The 10g10 function indicates a domain error sets errno to EDOM and returns a zero if the input is negative Example d Finclude lt math h gt double y y 10g10 100 0 fe y 2 0 See Also log pow 3 98 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library longjmp second return from setjmp Synopsis include lt setjmp h gt void longjmp jmp_buf env int return_val Description The longjmp function causes the program to execute a second return from the place where set jmp env was called with the same jmp_buf argument The longjmp function takes as its arguments a jump buffer that contains the context at the time of the original call to set jmp It also takes an inte ger return_val which set jmp returns if return_val is non zero Otherwise set jmp returns a 1 If env was not initialized through a previous call to set jmp or the function
10. d Finclude lt math h gt double x y y tanh x See Also cosh sinh VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 3 159 C Run Time Library Reference timer_off disable ADSP 218x DSP timer Synopsis d Finclude lt misc h gt unsigned int timer_off void Description This function is an Analog Devices extension to the ANSI standard The timer_off function disables the ADSP 218x DSP timer and returns the current value of the TCOUNT register Error Conditions The timer_off function does not return an error condition Example d Finclude lt misc h gt unsigned int hold_tcount hold_tcount timer_off hold_tcount contains value of TCOUNT register AFTER timer has stopped See Also timer_on timer_set 3 160 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library timer_on enable ADSP 218x DSP timer Synopsis d Finclude lt misc h gt unsigned int timer_on void Description This function is an Analog Devices extension to the ANSI standard The timer_on function enables the ADSP 218x DSP timer and returns the current value of the TCOUNT register Error Conditions The timer_on function does not return an error condition Example d Finclude lt misc h gt unsigned int hold_tcount hold_tcount timer_on hold_tcount contains value of TCOUNT register when timer starts E See Also timer_off timer_set
11. map filename The map generate a memory map switch directs the linker to output a memory map of all symbols The map file name corresponds to the filename argument For example if the filename argument is test the map file name is test xml The xm1 extension is added where necessary mem The mem invoke memory initializer switch causes the compiler to invoke the Memory Initializer tool after linking the executable The MemInit tool can be controlled through the f1ags mem switch on page 1 23 no alttok The no alttok disable alternative tokens switch directs the compiler to not accept alternative operator keywords and digraph sequences in the source files This is the default mode For more information see alttok on page 1 19 VisualDSP 3 5 C Compiler and Library Manual 1 29 for ADSP 218x DSPs Compiler Command Line Reference no bss The no bss switch causes the compiler to keep zero initialized and non zero initialized data in the same data section rather than separating zero initialized data into a different BSS style section See also the bss switch on page 1 19 no builtin The no builtin no builtin functions switch directs the compiler to rec ognize only built in functions that begin with two underscores __ Note that this switch influences many functions This switch also predefines the __NO_BUILTIN preprocessor macro For more information on built in functions see Compiler
12. 0 abs 1 The 0 is replaced with operand zero result the first operand The 1 is replaced with operand one x e The output operand is the C variable result The letter c is the operand constraint for the variable This con strains the output to an ALU result register The compiler generates code to copy the output from the register to the variable result if necessary The in c indicates that the operand is an output e The input operand is the C variable x The letter c is the operand constraint for the variable This con 1 60 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler strains x to an ALU register If x is stored in different kinds of registers or in memory the compiler generates code to copy the values into an register before the asm construct uses them Assembly Construct Operand Description The second and third arguments to the asm construct describe the oper ands in the assembly language template There are several pieces of information that need to be conveyed for cc218x to know how to assign registers to operands This information is conveyed with an operand con straint The compiler needs to know what kind of registers the assembly instructions can operate on so it can allocate the correct register type You convey this information with a letter in the operand constraint string which describes the class of allowable registers Table 1 7 on page 1 65 describe
13. 3 5 C Compiler and Library Manual for ADSP 218x DSPs INDEX Symbols assert directive 1 19 pragma align num 1 101 pragma alloc 1 109 2 30 pragma altregisters 1 103 pragma const 1 110 2 29 pragma hdrstop 1 115 pragma interrupt 1 102 pragma linkage_name 1 107 pragma loop_count 2 33 pragma loop_count min max modulo 1 104 pragma make_auto_static 1 108 pragma no_alias 1 105 2 34 pragma no_pch 1 116 pragma once 1 116 pragma optimize_ off for_speed for_space 2 33 pragma optimize_as_cmd_line 1 106 pragma optimize_for_space 1 106 pragma optimize_for_speed 1 106 pragma optimize_off 1 106 pragma pad alignopt 1 102 pragma pure 1 110 2 30 pragma regs_clobbered 2 31 pragma regs_clobbered string 1 111 pragma result_alignment 1 114 pragma retain_name 1 107 pragma system_header 1 116 pragma vector_for 1 104 pragma weak_entry 1 108 IDL file 1 131 xml extension 1 29 filename command file compiler switch 1 18 __alignof__ type name construct 1 123 __attribute__ keyword 1 124 __builtin_aligned declaration 2 6 __GROUPNAME _ macro 1 41 _ HOSTNAME _ macro 1 41 _ MACHINE _ macro 1 41 __NO_BUILTIN preprocessor macro 1 30 __NO_STD_LIB macro 1 32 _ REALNAME _ macro 1 41 __SIGNED_CHARS __ macro 1 40 1 43 __SILICON_REVISION__ macro 1 39 __ SYSTEM __ macro 1 41 __USERNAME _ macro 1 41 VisualDSP 3 5 C Compiler and Library Manual I 1 for AD
14. 3 5 C Compiler and Library Manual 1 115 for ADSP 218x DSPs C Compiler Language Extensions pragma no_pch The pragma no_pch overrides the pch precomiled headers switch on page 1 35 for a particular source file It directs the compiler not to look for a pch file and not to generate one for the specified source file pragma once The pragma once which should appear at the beginning of a header file tells the compiler that the header is written in such a way that including it several times has the same effect as including it once For example pragma once ifndef FILE_H tdefine FILE_H contents of header file dFendif In this example the pragma once is actually optional because the compiler recognizes the i fndef define endif idiom and will not reopen a header that uses it pragma system_header The pragma system_header identifies an include file as the file supplied with VisualDSP The pragma tells the compiler that every function and variable declared in the file but not in files included in the file is the vari able or function with that name from the VisualDSP library The compiler will take advantage of any special knowledge it has of the behavior of the library 1 116 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler GCC Compatibility Extensions The compiler provides compatibility with the C dialect accepted by ver sion 3 2 of the GNU C Compiler Many of
15. C Run Time Model and Environment The Device ID field is a unique identifier for the device known to the user Device IDs are used globally across an application The data field is a pointer for any private data the device may need it is not used by the run time libraries The function pointed to by the init field is invoked by the run time library when the device is first registered It returns a nega tive value for failure positive value for success The functions pointed to by the open close write and read fields are the functions that provide the same functionality used in the default I O device Seek is another function at the same level for those devices which support such functionality Ifa device does not support an operation such as seeking writing on read only devices or reading write only devices then a function pointer must still be provided the function must arrange to always return failure codes when the operation is attempted A new device can be registered with the following call int add_devtab_entry DevEntry_t entry If the device is successfully registered the init routine of the device is called with entry as its parameter add_devtab_entry returns the DevicelD of the device registered If the device is not successfully registered a negative value is returned Reasons for failure include but are not limited to e The DevicelD is the same as another device already registered e There are no more space
16. Legal code Illegal Dual Memory Space Type Cast Example VisualDSP 3 5 C Compiler and Library Manual 1 73 for ADSP 218x DSPs C Compiler Language Extensions int pm x int dm y int dm a X Y3 Compiler will flag error x ba Compiler will flag error Memory Keywords and Function Declarations Pointers Functions always reside in program memory Pointers to functions always point to program memory The following listing shows some sample func tion declarations with pointers Dual Memory Support Keyword Function Declaration With Pointers Syntax Examples int uye function y resides in pm and returns a a pointer to an integer which resides in d int pm y function y resides in pm and returns a EJ pointer to an integer which resides in p a int dm y function y resides in pm and returns a pointer to an integer which resides in d RT int pm y function y resides in pm and returns a x pointer to a pointer residing in pm that ey points to an integer which resides in dm ey 1 74 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Memory Keywords and Function Arguments The compiler checks whether calls to prototyped functions for memory space specifications are consistent with the function prototype The fol lowing example shows sample code tha
17. The template is the only mandatory argument to asm All other arguments are optional An operand constraint string followed by a C expression in paren theses describes each operand For output operands it must be possible to assign to the expression that is the expression must be legal on the left side of an assignment statement A colon separates e The template from the first output operand e The last output operand from the first input operand e The last input operand from the clobbered registers A comma separates operands and registers within arguments The number of operands in arguments must match the number of operands in your template The maximum permissible number of operands is ten 0 1 2 3 4 5 6 7 8 and 9 VisualDSP 3 5 C Compiler and Library Manual 1 59 for ADSP 218x DSPs C Compiler Language Extensions The compiler cannot check whether the operands have data types that are reasonable for the instruction being executed The com piler does not parse the assembler instruction template interpret the template nor verify whether the template contains valid input for the assembler ASM Construct Template Example The following example shows how to apply the asm construct template to the ADSP 218x assembly language abs instruction int result x asm 40 abs 41 q result d x ee In the previous example note the following points e The template is
18. able on the architecture An important aspect of this is that the compiler optimizer is not inhibited in any way by the use of these intrinsics Because of the varying nature of the architectures these basic intrinsic functions cannot be standardized across all the architectures However a set of standard functions for manipulating fractional data has been defined by the ITU International Telecommunications Union and ETSI Euro pean Telecommunications Standards Institute Referred to as the ETSI Standard Functions these have been very widely used to implement telecommunications packages such as GSM EFR and AMR Vocoders and have become a de facto industry standard These functions have been implemented on ADSP 218x DSPs The ETSI standard is aimed at DSP processors with 16 bit inputs satu rated arithmetic and 32 bit accumulators Calling ETSI Library Functions To use an ETSI function call the function by name and give the appropri ate arguments The names and arguments for each function appear on the function s reference page The names and arguments for each function appear in ETSI Header File on page 1 91 Like other functions you use ETSI functions should be declared Declara tions are supplied in the header file ETSI_fract_arith h which must be included in any source files where ETSI functions are called The function names are C function names If you call C run time library functions from an assembly language p
19. int io_space_read const unsigned int addr These functions are fully described in io_space_read on page 3 75 and io_space_write on page 3 77 1 84 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Read Write of Non Memory Mapped Registers The inclusion of sysreg h allows the use of built in functions that gener ate efficient inline instructions to implement read and write of values from and to non memory mapped registers The DSP has status registers which track and control machine status modes These registers are ASTAT SSTAT MSTAT ICNTL IMASK and IFC The prototypes for these functions are as defined in sysreg h void sysreg_write const int sysreg const int value int sysreg_read const int sysreg The sysreg parameter for these functions should be a member of the SysReg enumeration defined in sysreg h This enumeration is used to map the actual registers to a small constant defined as a user friendly name An example call of sysreg read of IMASK might be dFinclude lt sysreg h gt int value sysreg_read sysreg_IMASK These functions are fully described in sysreg_read on page 3 154 and sysreg_write on page 3 156 Interrupt Control The inclusion of sysreg h allows the use of built in functions that gener ate the instructions to enable and disable interrupts The prototypes for these functions are as defined in sysreg h void enable_interrupts void
20. 1 72 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Memory space specification keywords cannot qualify type names and structure tags but you can use them in pointer declarations The follow ing listing shows examples of memory space specification keywords in typedef and struct statements Dual Memory Support Keyword typedef amp struct Examples typedef float pm PFLOATP PFLOATP defines a type which is a pointer to a if float which resides in pm EJ struct s int x int y int z static pm struct s mystruct 10 9 8 Note that the pm specification is not used in XJ the structure definition The pm specification A is used when defining the variable mystruct Memory Keywords and Assignments Type Conversions Memory space specifications limit the kinds of assignments your program can make e You may make assignments between variables allocated in different memoty spaces e Pointers to program memory must always point to pm Pointers to data memory must always point to dm You may not mix addresses from different memory spaces within one expression Do not attempt to explicitly cast one type of pointer to another The following listings show a code segment with variables in different memory spaces being assigned and a code segment with illegal mixing of memory space assignments Legal Dual Memory Space Variable Assignment Example int pm x int dm y KS
21. 1 73 Memory Keywords and Function Declarations Pointers 1 74 Memory Keywords and Function Arguments 0 eee 1 75 Memory Keywords and Macros sccscamcsicnnencencie 1 75 PM and DM Compiler Support for Standard C Library Functions 1 76 Placement Support Keyword section ccicinsaccisssseeisticceneaceiaians 1 76 Boolean Type Support Keywords bool true false 00 1 77 Pointer Class Support Keyword restrict onic 1 77 Vatiable Length Atray Support eunsssercnscercsosd asorsitanrcansioascasans 1 78 Non Constant Aggregate Initializer Support esseere 1 80 Indexed Initializer SUpport acs cae ctiececcsccad ncasenddabedensecotstasietead 1 80 Aggregate Constructor Expression Support ricrirssrsiriniirenen 1 82 Preprocessor Genetated Warnings caciasiisuniisaviciidonasanies 1 83 ie CORES sossen nn 1 83 Compiler Bulin Funcion sosna a 1 83 PO Spas for Read WINTE arseeni iien EEE 1 84 VisualDSP 3 5 C Compiler and Library Manual ix for ADSP 218x DSPs CONTENTS Read Write of Non Memory Mapped Registers 005 1 85 eterna CONN screener teeters 1 85 ETA SOOO aa AA 1 86 ETS Suppor OVON aca R 1 86 Calling ETSI Library Punetions acsnenininangriibininiri 1 88 Using the ETSI Buile lim Paice rorersrmisnseriercennirecer 1 89 Linkime ETSI Library Puactint cacusncacsnnceimenee 1 89 Working with ETSI Library Source Code seisrisisnsnsssss 1 90 ETSI Support Tor Data Types eunice 1 90 ETSI Perder THU pannorna ana ENR AA 1 91 Pa
22. 2 4 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Achieving Optimal Performance from C Source Code The particular advantage of statistical profiling is that it is completely unobtrusive Other forms of profiling insert instrumentation into the code perturbing the original optimization code size and register alloca tion to some degree The best methodology is usually to compile with both optimization and debug information generation enabled In this way you can obtain a pro file of the optimized code while retaining function names and line number information This will give you accurate results that correspond directly to the C source Note that the compiler optimizer may have moved code between lines You can obtain a more accurate view of your application if you build it optimized but without debug information generation You will then obtain statistics that relate directly to the assembly code The only prob lem with doing this may be in relating assembly lines to the original source Do not strip out function names when linking since keeping func tion names means you can scroll through the assembly window to instructions of interest In very complicated code you can locate the exact source lines by count ing the loops unless they are unrolled Looking at the line numbers in the assembly file use the save temps switch on page 1 39 to retain com piler generated assembly files which will have the s filena
23. L M N can be obtained from the Literature Center at 1 800 ANALOGD 1 800 262 5643 or downloaded from the website Data sheets without the suffix can be downloaded from the website only no hard copies are available You can ask for the data sheet by a part name or by product number xxxii VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Preface If you want to have a data sheet faxed to you call 1 800 446 6212 Follow the prompts and a list of data sheet code numbers will be faxed to you Call the Literature Center first to find out if requested datasheets are available Contacting DSP Publications Please send your comments and recommendation on how to improve our manuals and online Help You can contact us dsp techpubs analog com Notation Conventions The following table identifies and describes text conventions used in this manual Additional conventions which apply only to specific chapters may appear throughout this document Example Description Close command Text in bold style indicates the location of an item within the File menu VisualDSP environment s menu system For example the Close command appears on the File menu this that Alternative required items in syntax descriptions appear within curly brackets and separated by vertical bars read the example as this or that this that Optional items in syntax descriptions appear within b
24. Library Functions in the math C Run Time Library h Header File Cont d frexp isinf isnan Idexp log log10 modf pow sin sinh tan tanh Table 3 22 Library Functions in the misc h Header File timer_off timer_on timer_set Table 3 23 Library Functions longjmp setjmp Table 3 24 Library Functions in the setjmp h Header File in the signal h Header File clear_interrupt interrupt raise signal Table 3 25 Library Functions in the stdarg h Header File va_arg va_end va_start Table 3 26 Supported Library Functions in the stdio h Header File clearerr fclose feof ferror fflush fgetc fgetpos fgets fopen fprintf fputc fputs fread freopen fscanf fseek fsetpos ftell fwrite getc getchar VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 3 15 Documented Library Functions Table 3 26 Supported Library Functions in the stdio h Header File gets perror putc putchar puts remove rename rewind scanf setbuf setvbuf sprintf sscanf ungetc vfprintf vprintf vsprintf Table 3 27 Library Functions in the stdlib h Header File abort abs atexit atof atoi atol bsearch calloc div exit free labs Idiv malloc qsort rand realloc srand strtod strtodf strtol strtoul Table 3 28 Library Functions
25. The empty bits of the 32 bit result are zero filled If the second parameter is negative the shift performed is to the right with sign extended The result is saturated in cases of overflow and underflow Long shift right fract32 L eshr fract32 fractl6 This function arithmetically shifts the 32 bit first parameter to the right by the value given in the 16 bit second parameter with sign extension If the shifting value is negative the source is shifted to the left The result is saturated in cases of overflow and underflow Long shift right with rounding fract32 Lushr_r fract32 fractl6 This function performs the shift right operation as per L_shr but with rounding Long subtract fract32 L sub fract32 fract32 This function returns the 32 bit saturated result of the subtraction of two 32 bit parameters first second VisualDSP 3 5 C Compiler and Library Manual 1 97 for ADSP 218x DSPs C Compiler Language Extensions Long subtract with carry fract32 Lisub_c fract32 fract32 This function performs 32 bit subtraction of the two input parameters Uses the Carry flag as additional input when using the ETSI flag variables Compose long fract32 L_Comp fractl6 fractl6 This function composes a fract32 type value from the given fract16 high first parameter and low second parameter components The sign is provided with the low half the result is calculated to be high lt lt 16 low lt lt 1 Multiply two
26. for ADSP 218x DSPs C Run Time Library See Also strcmp strcoll strncpy VisualDSP 3 5 C Compiler and Library Manual 3 153 for ADSP 218x DSPs C Run Time Library Reference sysreg read read from non memory mapped register Synopsis include lt sysreg h gt int sysreg_read const int Description The sysreg_read function causes the compiler to emit instructions to read the non memory mapped register which is passed as a parameter and to set the value read from that register as a return value The input parameter for sysreg_read should be a member of the SysReg enumeration defined in sysreg h This enumeration is used to map the non memory mapped actual registers to a small constant defined as a user friendly name The enumerated variables defined are sysreg_ASTA arithmetic status sysreg_SSTA shifter status sysreg_MSTA multiplier status sysreg_ICNTL interrupt control sysreg_IMASK interrupts enabled mask sysreg_IFC interrupt force and clear The sysreg_read function is implemented as a compiler built in the emitted instructions will be inlined at the point of sysreg_read use The inclusion of the sysreg h include file is mandatory when using sysreg_read Error Conditions The sysreg_read function does not return raise or set any error conditions 3 154 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library Example d Finclude lt sysreg h gt mai
27. function 3 169 val global add global names compiler switch 1 43 variable argument macros 1 121 variable length argument list finishing 3 168 3 169 initializing 3 169 variable length array support 1 78 1 121 INDEX verbose display command line compiler switch 1 43 version display version switch 1 43 VIDL source text 1 131 VisualDSP compiler C language extensions 1 53 IDDE 1 3 1 10 mixed C assembly reference 1 132 simulator 1 141 3 11 volatile and asm C program constructs 1 68 W w disable all warnings switch 1 45 W override error message compiler switch 1 44 warnings new in this release A 7 warn protos prototypes warning compiler switch 1 45 Wdriver limit maximum process errors compiler switch 1 44 Werror limit maximum compiler errors compiler switch 1 44 white space character test see isspace function Wremarks enable diagnostic warnings compiler switch 1 44 write operation 3 11 write files enable driver I O redirection compiler switch 1 45 VisualDSP 3 5 C Compiler and Library Manual I 23 for ADSP 218x DSPs INDEX write opts compiler switch 1 45 writes array element 2 19 writing macros 1 129 non memory mapped register 3 156 Wterse enable terse warnings compiler switch 1 45 X xref cross reference list compiler switch 1 46 Z zero length arrays 1 121 1 24 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs
28. its body must be included in every file in which the function is used The normal way to do this is to place the inline definition in a header file Usually it will also be declared static In some cases the compiler does not output object code for the function for example the address is not needed for an inline function called only from within the defining program However recursive calls and functions whose addresses are explicitly referred to by the program are compiled to assembly code The compiler only inlines functions even those declared using the inline keyword when optimizations are enabled using the 0 switches as described on page 1 32 VisualDSP 3 5 C Compiler and Library Manual 1 55 for ADSP 218x DSPs C Compiler Language Extensions Inline Assembly Language Support Keyword asm The cc218x asm construct lets you code ADSP 218x processor s assem bly language instructions within a C function and to pass declarations and directives through to the assembler The asm construct is useful for expressing assembly language statements that cannot be expressed easily or efficiently with C constructs The asm keyword allows you to code complete assembly language instructions or you can specify the operands of the instruction using C expressions When specifying operands with a C expression you do not need to know which registers or memory locations contain C variables The compiler does not analyze code
29. sample coeffs 2 coeffs 7 p p l aa p p O eeee wo ool coeffs 4 effs 1 oeffs 9 effs 6 4 lt gt gt zl aol coeffs 3 coeffs 0 ffs 8 coeffs 5 lt lt O n 1th section nth section K 5 N 2 K 5 N 1 coeff s K 2 coeffs K 2 eooec5e gt gt gt gt i si Ji gat coeffs K 4 coeffs Kt 1 oeffs Kt 4 coeffs Kt1 al 21 coeffs K 3 coeffs K coeffs Kt 3 coeffs K lt gt lt gt O 3 32 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library N the number of biquad sections The algorithm shown here is adapted from Oppenheim Alan V and Ronald Schafer Digital Signal Processing Englewood Cliffs New Jersey Prentice Hall 1975 See Also fir iir VisualDSP 3 5 C Compiler and Library Manual 3 33 for ADSP 218x DSPs C Run Time Library Reference bsearch perform binary search in a sorted array Synopsis include lt stdlib h gt void bsearch const void key const void base size_t nelem size_t size int compare const void const void Description The bsearch function executes a binary search operation on a pre sorted array where e key is a pointer to the element to search for e base points to the start of the array e nelem is the number of elements in the array e size is the size of each element of the array e compare points to the function used to compare two elements It takes as parameters a pointer to the key and a pointer to a
30. switch turns on Interprocedural Analysis IPA in the compiler This option enables optimization across the entire program including between source files that were compiled sep arately The ipa option should be applied to all C files in the program For more information see Interprocedural Analysis on page 1 50 Spec ifying ipa also implies setting the 0 switch on page 1 32 You can invoke this switch by selecting the Interprocedural optimization check box in the VisualDSP Project Options dia log box Compile tab General category jump dm pm same The jump select jump table memory type switch directs the compiler to place jump tables in data memory jump dm or program memory jump pm or the same memory section as the function to which it applies jump same Jump tables are storage that might be required to 1 26 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler hold in memory target addresses for branch instruction used in complex if then else statements or switch statements The default storage mem ory for jump tables is data memory L directory directory The L library search directory switch directs the linker to append the directory to the search path for library files library The 1 link library switch directs the linker to search the Jibrary for functions when linking The library name is the portion of the file name between the 1ib prefi
31. that called set jmp has since returned the behavior is undefined Also automatic variables that are local to the original function calling set jmp that do not have volatile qualified type and that have changed their value prior to the longjmp call have indeterminate value Error Conditions The longjmp function does not return an error condition Example include lt setjmp h gt d Finclude lt stdio h gt d Finclude lt errno h gt d Finclude lt stdlib h gt VisualDSP 3 5 C Compiler and Library Manual 3 99 for ADSP 218x DSPs C Run Time Library Reference jmp_buf env int res if res setjmp env 0 printf Problem d reported by func res exit EXIT_FAILURE func void func void if errno 0 longjmp env See Also setymp errno 3 100 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library malloc allocate memory Synopsis d include lt stdlib h gt void malloc size_t size Description The malloc function returns a pointer to a block of memory of length size The block of memory is uninitialized Error Conditions The malloc function returns a null pointer if it is unable to allocate the requested memory Example d Finclude lt stdlib h gt int ptr ptr int malloc 10 ptr points to an array of length 10 See Also calloc free realloc VisualDSP 3 5 C Compiler and Library Manual 3
32. the alignment returned takes into account alignment requested by pragmas and the default variable allocation rules Keyword for Specifying Names in Generated Assembler asm The asm keyword can be used to direct the compiler to use a different name for a global variable or function For example int N asm C11045 tells the compiler to use the label C11045 in the assembly code it gener ates wherever it needs to access the source level variable N By default the compiler would use the label _N The asm keyword can also be used in function declarations but not func tion definition However a definition preceded by a declaration has the desired effect For example extern int f int int asm func VisualDSP 3 5 C Compiler and Library Manual 1 123 for ADSP 218x DSPs C Compiler Language Extensions int f int a int b k Function Variable and Type Attribute Keyword __attribute__ The __attribute__ keyword can be used to specify attributes of functions variables and types as in these examples void func void __attribute__ section fred int a __attribute__ aligned 8 typedef struct int al4 __attribute__ aligned 4 Q The __attribute__ keyword is supported and therefore code written for GCC can be ported All attributes accepted by GCC on ix86 are accepted The ones that are actually interpreted by the compiler are described in the sections of this manual describing the corresponding pr
33. the behavior is undefined If ptr is a null pointer realloc imitates malloc If size is zero and ptr is not a null pointer real loc imitates free Error Conditions If memory cannot be allocated ptr remains unchanged and realloc returns a null pointer Example d Finclude lt stdlib h gt int ptrsg ptr int malloc 10 intervening code ptr int realloc ptr 20 the size is now 20 See Also calloc free malloc 3 114 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library setjmp define a run time label Synopsis include lt setjmp h gt int setjmp jmp_buf env Description The setjmp function saves the calling environment in the jmp_buf argu ment The effect of the call is to declare a run time label that can be jumped to via a subsequent call to longjmp When set jmp is called it immediately returns with a result of zero to indi cate that the environment has been saved in the jmp_buf argument If at some later point 1ongjmp is called with the same jmp_buf argument longjmp will restore the environment from the argument The execution will then resume at the statement immediately following the correspond ing call to set jmp The effect is as if the call to setjmp has returned for a second time but this time the function returns a non zero result The effect of calling longjmp will be undefined if the function that called setjmp has returned in the inte
34. tpragmapragma directive pragma directive operands new line Pragma operators have the following syntax _Pragma string literal When processing a pragma operator the compiler effectively turns it into a pragma directive using a non string version of string literal This means that the following pragma directive fpragma inkage_name mylinkname can also equivalently be expressed using the following pragma operator _Pragma inkage_name mylinkname The examples in this manual use the directive form VisualDSP 3 5 C Compiler and Library Manual 1 99 for ADSP 218x DSPs C Compiler Language Extensions The C compiler supports pragmas for Arranging alignment of data Defining functions that can act as interrupt handlers Changing the optimization level midway through a module Changing how an externally visible function is linked Header file configurations and properties Giving additional information about loop usage to improve optimizations The following sections describe the pragmas that support these features Data Alignment Pragmas on page 1 101 Interrupt Handler Pragmas on page 1 102 Loop Optimization Pragmas on page 1 103 General Optimization Pragmas on page 1 105 Linking Control Pragmas on page 1 106 Stack Usage Pragma on page 1 108 Function Side Effect Pragmas on page 1 109 Header File Control Pragmas on page 1 115 The compiler will issue a warning when it encounte
35. 1 104 pragma no_alias When immediately preceding a loop the no_alias pragma asserts that no load or store in the loop accesses the same memory as any other This helps to produce shorter loop kernels as it permits instructions in the loop to be rearranged more freely See pragma no_alias on page 1 105 for more information 2 34 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Achieving Optimal Performance from C Source Code Useful Optimization Switches These are the compiler switches useful during the optimization process Switch Name Description const read write Specifies that data accessed via a pointer to const data may be modi on page 1 20 fied elsewhere flags link e Specifies linker section elimination on page 1 23 ipa Turns on inter procedural optimization Implies use of 0 on page 1 26 May be used in conjunction with 0s or Ov no fp associative Does not treat floating point multiply and addition as an associative on page 1 31 0 Enables code optimizations and optimizes the file for speed on page 1 32 0S Optimizes the file for size on page 1 33 0v num Controls speed vs size optimizations sliding scale on page 1 33 save temps on page 1 39 Saves intermediate files for example s VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 2 35 Useful Optimization Switches 2 36 VisualDSP 3
36. 1 127 sas LD ses E E E AE E EE E E 1 127 LANGUAGE G ssciprsnsninkoksdiksa AERAR 1 127 UNE sprenneiaipii oninia at 1 127 NO BUILTIN serenon 1 127 eNO LONG LONG een er nN 1 127 IGNE D CHARS Pasear 1 127 xii VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs CONTENTS 6 h E O E E A E E E E 1 128 A VERSION o a 1 128 SENIE a R A teas 1 128 sean e E E E 1 128 Header Files puisncaictnkiininn aak 1 128 Writiag Preprocessor MACS siinciscccrentincivienmintiieranes dole Preprocessing of IDL Filet c ccnnucnciamuineiances 1 131 Soe Time Model and Environment carencccsennssenei 1 132 Using the Run Time Header econo noecnuions 1 133 Interrupt Table and nterface sicsrrinssiiseiireinissssienansenins 1 133 Autobuffering Support svsandancsororsninereiisi unien 1 134 e edo neaeneeeeeees 1 136 Stick Frome Desci pio cic cieeieees 1 137 General System Wide Speciieatwons sesccssseecesseessvssaiesiesids 1 138 At a procedure call the following must be true 1 139 At an interrupt the following must be true 0 1 139 Reira Values ati ican teias sate tiara kti okki 1 139 Procedure Call and Ce snnscersrenreriotrnorirren 1 140 IN Ie eta oe seere ete eater aaa naaw nee 1 140 To Reimo froma PROCS aac scenscancecsiennconscrnncisaisancese 1 140 Pile NN cerasana a EASE 1 141 Extending I O Support To New Devices c c ccssccecsrassccusens 1 141 Miscellaneous Informatio si cstneniiuobesissadiasiusinicaterincanlanieiianteiies
37. 1 143 Repiser CAIRO secticite entities 1 144 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs xiii CONTENTS Callee Preserved Registers Preserved cccsscsvcsesseerannstvans 1 144 Dedicated Te cnt 1 144 Caller Save Registers Serah cdecesacersnonstnserseinvseennense 1 144 Circular Butfer Length eg iterg sccrodecsncsnesevsesoioceeseassecs 1 144 Mode Status MSTAT Register crcnonurnossinkpticmiia 1 145 Complete List of REPETE scnscsncrsinecremmsnierninencontenianrce 1 145 Cand Assembly Language Interlace scscroren 1 148 Calling Assembly Subroutines from C Programs 00 1 148 Calling C Routines from Assemby Programs cceseeeee 1 151 Using Mixed C Assembly Support Macros eceeeeee 1 152 CCI T E S ET E 1 153 Git 20 ee 1 153 oda sg nesrin 1 153 Cee Gioia nts ee aeeeeaes 1 153 TGs bo See eRe RTER EEC aACE STR UT EE Cen ote RRC Ne UPTO Ce rRen Tee 1 153 PETES a eee 1 154 PN I cdc een 1 154 SRST PERSE oeraccieietncanemnnanedeen 1 154 FOCI TRAURRERE rio 1 154 pariksi TEST ce tcancesarrencnnutcuntsnatintarernnatcuntinentavabenta 1 154 Ee FEE ees ERA 1 155 ge lirsi ORR CORT ea asi i 1 155 Peel E E a E E 1 155 Using Mixed C Assembly Naming Conventions 00 1 155 xiv VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs CONTENTS Compan bi C ail parine t 1 156 ACHIEVING OPTIMAL PERFORMANCE FROM C SOURCE CODE Generol wid lines ariari a ena 2 3 H
38. 1 29 memchr find first occurrence of character function 3 102 memcmp compare objects function 3 103 memcpy copy characters from one object to another function 3 104 memmove copy characters between overlapping objects function 3 105 memory data placement in 2 15 memory see calloc free malloc memcmp memcpy memset memmove memchar realloc functions memory initializer 1 23 1 31 invoking 1 29 memory keywords function arguments 1 75 macros 1 75 memset set range of memory to a character function 3 106 minimum code size 2 27 misc h header file 3 10 missing operands in conditional expressions 1 120 INDEX mixed C assembly C run time model 1 132 calling C from assembler 1 151 naming conventions 1 155 programming 1 132 asm constructs 1 56 1 57 1 61 1 67 1 68 1 70 support macros 1 152 mixed C assembly programming asm constructs 1 57 1 68 MM generate make rules and compile compiler switch 1 28 Mo processor output file compiler switch 1 28 modf separate integral and fractional parts function 3 107 MQ compiler switch 1 28 MSB extraction 1 87 MSTAT mode status register 1 145 Mt filename output make rule compiler switch 1 28 multidimensional arrays 1 79 multi line asm C program constructs 1 67 N naming conventions C and assembly 1 155 next argument in variable list 3 165 no alttok disable alternative tokens compiler switch 1 29 no bss compiler switch 1 30 VisualDSP 3 5 C
39. 101 for ADSP 218x DSPs C Run Time Library Reference memchr find first occurrence of character Synopsis include lt string h gt void memchr const void sl int c size_t n Description The memchr function compares the range of memory pointed to by s1 with the input character c and returns a pointer to the first occurrence of c A null pointer is returned if c does not occur in the first n characters Error Conditions The memchr function does not return an error condition Example include lt string h gt char ptr ptr memchr TESTING E 7 ptr points to the E in TESTING See Also strchr strrchr 3 102 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library memcmp compare objects Synopsis d Finclude lt string h gt int memcmp const void sl const void s2 size_t n Description The memcmp function compares the first n characters of the objects pointed to by s1 and s2 It returns a positive value if the s1 object is lexically greater than the s2 object a negative value if the s2 object is lexically greater than the s1 object and a zero if the objects are the same Error Conditions The memcmp function does not return an error condition Example d Finclude lt string h gt char stringl ABC char string2 BCD int result result memcmp stringl string2 3 result lt 0 See Also strcmp strcoll strncmp
40. 1024 int imag_outputIN fpragma align 1024 int real_outputIN int block exponent block exponent ifft1024 real_input imag_input real_output imag_output See Also fftN VisualDSP 3 5 C Compiler and Library Manual 3 65 for ADSP 218x DSPs C Run Time Library Reference iir infinite impulse response IIR filter Synopsis d Finclude lt filters h gt int iir int sample int pm a_coeffs int float pm b_coeffs int dm statel int taps Description This function is an Analog Devices extension to the ANSI standard The iir function implements an infinite impulse response IIR filter based on the Oppenheim and Schafer direct form II The function returns the filtered response of the input data sample The characteristics of the filter are dependent upon a set of coefficients a delay line and the length of the filter The length of filter is specified by the argument taps The set of IIR filter coefficients is composed of a coefficients and b coefficients The ag coefficient is assumed to be 1 0 and the remaining a coefficients should be scaled accordingly and stored in the array a_coeffs in reverse order The length of the a_coeffs array is taps and therefore a_coeffs 0 should contain atapo and a_coeffs taps 1 should contain a The b coefficients are stored in the array b_coeffs also in reverse order The length of the b_coeffs is taps 1 and so b_coeffs 0 will contain Draps and b_coeffs taps
41. 12345 DM _global_p I0 _asmfunc end For a more complicated function you might find it useful to fol low the general run time model and use the run time stack for local storage etc A simple C program passed through the com piler will provide a good template to build on Alternatively you may find it just as convenient to use local static storage for temporaries Calling C Routines from Assemby Programs You may want to call a C callable library and other functions from within an assembly language program As discussed in Calling Assembly Subrou tines from C Programs on page 1 148 you may want to create a test function to do this in C and then use the code generated by the compiler as a reference when creating your assembly language program and the argument setup Using volatile global variables may help clarify the essen tial code in your test function The run time model defines some registers as scratch registers and others as preserved or dedicated The contents of the scratch registers may be changed without warning by the called C function If the assembly lan guage program needs the contents of any of those registers you must save their contents before the call to the C function and then restore those con tents after returning from the call Do not use the dedicated registers for other than their intended purpose the compiler libraries debugger and interrupt routines all depend on having a stack availab
42. 2 using pointers void va_ptr const short al const short b short outL int n int Ts short pout out const short pa a pb b for i S 09 7 lt ns 447 pout pat pb VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Achieving Optimal Performance from C Source Code Trying Pointer and Indexed Styles One might hope that the chosen style would not make any difference to the generated code but this is not always the case Sometimes one version of an algorithm will generate better optimized code than the other but it is not always the same style that is better Tip Try both pointer and index styles The pointer style introduces additional variables that compete with the surrounding code for resources during the compiler optimizer s analysis Array accesses on the other hand must be transformed to pointers by the compiler and sometimes it does not do the job as well as you could do by hand The best strategy is to start with array notation If the generated code looks unsatisfactory try using pointers Outside the critical loops use the indexed style since it is easier to understand Function Inlining The function inlining may be used in two ways e By annotating functions in the source code with the inline key word In this case function inlining is only performed when optimization is enabled e By turning on automatic inlining with the 0a switch on page 1 33
43. 3 108 DEONET AA 3 109 PRISE E E E E E T E E E E E E 3 111 E T E E AA S T E 3 113 XX VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs INE oS earn S 3 115 IGUAL EEE A A A A A O 3 116 BI Sel E E 3 120 E E E ania A EA A E E E T ET 3 122 IC E E E E A E A E EE T ee 3 123 SEE iaa BPtn err Be eran Scr w har Mel ereMote ment ce aro Ne attc mse ts re 3 124 E ENETEIA A INET OO A A T 3 125 Et aie oe aie ea eneoee 3 126 at eee ene n ee ete PvE eS TOR ITE Spe neve Tt stUCEPE COREE trot 9fPERENTEPER U nT oR TTR OPED NOS 3 127 E a ET E E E EETA E OAE E A A ET 3 128 Ea E E I E E E A EN E E oladaameaiieaals 3 129 SGN coreeana EEE E 3 130 TOE E E A 3 131 a EA AEA O EEA EE NE 3 132 Oe RR EAE R N 3 133 SEP casual bli aiok eriei 3 134 E E EE E E E E EE 3 135 Pies eee eee 3 136 a S E EE E A EA A E AAA 3 137 S a oleaedicantancuesehdueassabannastuddaldpsatanvaneadduianiedn 3 138 DT d E TOU NEY EAU FET ETOAC ES POVEPEERY YORE CEE TETTEE te 3 139 URGED ction cw icing wait nbn 3 140 ROU onenen ntori mide neaimedeninaiteasesi 3 143 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs xxi Ce ean 3 148 PEI EEEE E AEAEE E 3 150 Ps E E E A E E E EE 3 152 Sere ad aakongiksi aiei a R 3 154 ee WINS E E E E T 3 156 tah sited ee 3 158 A EEEN NE A EA A EE AN EA O ET 3 159 MT a S uaeemobaaaatdes 3 160 COET O aa E AE 3 161 POE SE A EEA A E A E EEE OE T E E 3 162 E ca EE E E tier E E E A E E ET at ones ere 3 163 GOPE oneng
44. 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library sysreg h The sysreg h header file defines a set of functions that provide efficient system access to registers modes and addresses not normally accessible from C source See Compiler Built in Functions on page 1 83 for more information on these functions VisualDSP 3 5 C Compiler and Library Manual 3 13 for ADSP 218x DSPs Documented Library Functions Documented Library Functions The following tables list the library functions documented in this chapter These tables list the functions for each header file separately how ever the reference pages for these library functions are in alphabetical order Table 3 18 Library Functions in the ctype h Header File isalnum isalpha iscntrl isdigit isgraph islower isprint ispunct isspace isupper isxdigit tolower toupper Table 3 19 Library Functions in the ffts h Header File FFEN fft1024 fft512 fft256 ffr128 fft64 fft32 fft16 fft8 ifftN ifft1024 ifft512 ifft256 ifft128 ifft64 ifft32 ifft16 ifft8 Table 3 20 Library Functions in the filters h Header File biquad demean_buffer fir iir Table 3 21 Library Functions in the math h Header File acos asin atan atan2 ceil cos cosh cot exp fabs floor fmod 3 14 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Table 3 21
45. C Compiler and Library Manual for ADSP 218x DSPs ceil ceiling Synopsis d Finclude lt math h gt double ceil double x float ceilf float x Description C Run Time Library The ceil functions return the smallest integral value expressed as double that is not less than its input Error Conditions The ceil functions do not return an error condition Example d Finclude lt math h gt double y float x y ceil 1 05 ceilf 1 05 x ll See Also floor Ly 2 0 y soy oh AY VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 3 37 C Run Time Library Reference clear_interrupt clear a pending signal Synopsis d Finclude lt signal h gt int clear_interrupt int sig Description The clear_interrupt function sets a bit in the IFC Interrupt Force and Clear register to clear a pending interrupt The sig argument must be one of the processor signals shown below for the ADSP 218x DSPs Table 3 30 ADSP 218x DSP Signals Sig Value Definition SIGTIMER Timer interrupt STGIRQO Interrupt 0 SIGSPORTLRECV Signal Sport 1 receive SIGIRQ1 Interrupt 1 SIGSPORTIXMIT Signal Sport 1 transmit SIGBDMA Byte DMA interrupt SIGIRQE Level sensitive SIGSPORTORECV Signal Sport 0 receive SIGSPORTOXMIT Signal Sport 0 transmit SIGIRQ2 Interrupt 2 Error Conditions The clear_interrupt fu
46. C Run Time Library See Also interrupt raise VisualDSP 3 5 C Compiler and Library Manual 3 119 for ADSP 218x DSPs C Run Time Library Reference sin sine Synopsis include lt math h gt double sin double x float sinf float x fractl6 sin_frl6 fractl6 x Description The sin function returns the sine of the argument x The input is inter preted as a radian the output is in the range 1 1 The sin_fr16 function inputs a fractional value in the range 1 0 1 0 corresponding to 1 2 7 2 The domain represents half a cycle which can be used to derive a full cycle if required see Notes below The result in radians is in the range 1 0 1 0 Error Conditions The sin function does not return an error condition Example dFinclude lt math h gt double y y sin 3 14159 y 0 0 Notes The domain of the sin_fr16 function is restricted to the fractional range 0x8000 0x7fff which corresponds to half a period from 1 2 to 77 2 It is possible however to derive the full period using the following proper ties of the function 3 120 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library sine 0 1 2 sine T 3 2 T Sine m 2 0 sine T 2 T The function below uses these properties to calculate the full period from 0 to 27 of the sine function using an input domain of 0 0x7fff include lt math h gt fractl6 sin2pi_fr16
47. Compiler and Library Manual I 15 for ADSP 218x DSPs INDEX no builtin no builtin functions compiler switch 1 30 no def disable defaults compiler switch 1 30 no extra keywords disable short form keywords compiler switch 1 30 no fp associative compiler switch 1 31 no mem not invoking memory initializer compiler switch 1 31 non constant initializer support compiler 1 80 non memory mapped registers 1 85 non unit stride avoiding 2 21 no std ass disable standard assertions compiler switch 1 31 no std def disable standard macro definitions compiler switch 1 31 no std inc disable standard include search compiler switch 1 31 no std lib disable standard library search compiler switch 1 32 no widen muls disable widening multiplications compiler switch 1 32 O O enable optimization compiler switch 1 32 o output file compiler switch 1 33 Oa automatic function inlining compiler switch 1 33 obsolete warning switches A 8 obsolete modified switches A 5 OldAsmCall declaration 1 157 open operation 3 11 operand constraints 1 62 optimization code 1 49 2 27 controlling 1 49 default 1 49 interprocedural analysis 1 50 IPA 1 50 IPA option 1 26 pragmas 1 50 1 105 reset 1 106 switches 1 32 2 35 optimizer 1 49 1 103 2 4 optimizing asm C program constructs 1 68 for space 1 106 2 27 2 33 for speed 1 106 2 27 2 33 Os optimize for size compiler switch 1 33 outer loop 2 19
48. DSPs C Run Time Library See Also acos sin VisualDSP 3 5 C Compiler and Library Manual 3 43 for ADSP 218x DSPs C Run Time Library Reference cosh hyperbolic cosine Synopsis d Finclude lt math h gt double cosh double Description The cosh function returns the hyperbolic cosine of its argument Error Conditions The cosh function returns the IEEE constant Inf if the argument is out side the domain Example d Finclude lt math h gt double x y y cosh x See Also sinh 3 44 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library cot cotangent Synopsis d Finclude lt math h gt float cotf float a double cot double a Description This function calculates the cotangent of its argument a which is mea sured in radians If a is outside of the domain the function returns 0 Algorithm c cot a Domain x 9099 9099 VisualDSP 3 5 C Compiler and Library Manual 3 45 for ADSP 218x DSPs C Run Time Library Reference demean_buffer remove the mean of a data buffer Synopsis include lt filters h gt int demean_buffer int input_buffer int old_mean int length Description The demean_buffer routine removes a DC bias from input signals and the mean from a buffer of data It can also execute a notch filter on the input based on an adaptive filter See Adaptive Signal Processing from Prentice Hall 1985 deme
49. For example the following command line cc218x proc ADSP 2189 0 Wremarks o program dxe source c runs cc218x with the following switches proc ADSP 2189 Specifies the processor 0 Specifies optimization for the compiler Wremarks Selects extra diagnostic remarks in addition to warning and error messages 0 program dxe Selects a name for the compiled linked output source c Specifies the C language source file to be compiled VisualDSP 3 5 C Compiler and Library Manual 1 7 for ADSP 218x DSPs Compiler Command Line Reference The normal function of the cc218x switch is to invoke the compiler assembler and linker as required to produce an executable file The pre cise operation is determined by the extensions of the input filenames and or by various switches The compiler uses the following files to perform the specified action Extension Action lt C C source file is compiled assembled and linked asm dsp or s Assembly language source file is assembled and linked doj Object file from previous assembly is linked If multiple files are specified each is first processed to produce an object file then all object files are presented to the linker You can stop this sequence at various points by using appropriate com piler switches or by selecting options within the VisualDSP IDDE These switches are E P M H S and c Many of the compiler s switches take a file name as
50. Library Manual for ADSP 218x DSPs C Run Time Library isxdigit detect hexadecimal digit Synopsis dFinclude lt ctype h gt int isxdigit int c Description The isxdigit function determines if the argument character is a hexadec imal digit character A F a f or 0 9 If the argument is not a hexadecimal digit isxdigit returns a zero If the argument is a hexadeci mal digit isxdigit returns a non zero value Error Conditions The isxdigit function does not return any error conditions Example include lt ctype h gt int ch for ch 0 ch lt Ox7f ch printf 04x ch printf 2s isxdigit ch hexadecimal putchar n See Also isalnum isdigit VisualDSP 3 5 C Compiler and Library Manual 3 93 for ADSP 218x DSPs C Run Time Library Reference labs long integer absolute value Synopsis include lt stdlib h gt long int labs long int Description The labs function returns the absolute value of its long integer input Error Conditions The labs function does not return an error condition Example d Finclude lt stdlib h gt long int j j labs 285128 j 285128 See Also abs fabs 3 94 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Idexp multiply by power of 2 Synopsis dFinclude lt math h gt double ldexp double x int n float Idexpf float x int n Description C Run Time Library The 1dexp function retu
51. P switch Cc Compiles and or assembles only does not link on page 1 20 const read write Specifies that data accessed via a pointer to const data may be on page 1 20 modified elsewhere VisualDSP 3 5 C Compiler and Library Manual 1 11 for ADSP 218x DSPs Compiler Command Line Reference Table 1 2 Compiler Command Line Switches Contd Switch Name Description Dmacro definition on page 1 20 Defines a macro debug types on page 1 21 Supports building a h file directly and writing a complete set of debugging information for the header file default linkage asm C on page 1 21 Sets the default linkage type asm C Displays but does not perform main driver actions on page 1 22 E on page 1 22 dry on page 1 22 verbose dry run dryrun Displays but does not perform top level driver actions terse dry run Preprocesses but does not compile the source file ED on page 1 22 Produce preprocessed file and compile source EE on page 1 22 Preprocesses and compiles the source file extra keywords on page 1 22 Recognizes the Analog Devices extensions to ANSI ISO standards for C Default mode flags asm compiler lib link mem argument on page 1 23 Passes command line switches through the compiler to other build tools fp associative on page 1 23 Treats floating point multiplication
52. Software abort signal STGILL Software illegal signal SIGINT Software segmentation signal STGTERM Software termination signal SIGFPE Software floating point exception signal VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 3 117 C Run Time Library Reference The signal function causes the receipt of the signal number sig to be handled in one of the following ways e SIG_DFL The default action is taken e SIG_IGN The signal is ignored e Function address The function pointed to by func is executed The function pointed to by func is executed once when the signal is received Handling is then returned to the default state Interrupts are not nested by the default start up file Error Conditions The signal function returns SIG_ERR and sets errno to SIG_ERR if it does not recognize the requested signal Example includ e lt signal h gt void handler int sig main sig sig sig sig enable power d disable power al SIG_PWRDW al SIG_PWRDWN enable power d alf SIG_PWRDWN own in hand down interr STG own in disable power down interr alf SIG_PWRDWN handler Lerrup er GN cerrup SIG_IGN Interrupt Service Routine ISR t and register ISR pt t and register ISR pt 3 118 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs
53. This switch automatically enables optimization Tip Inline small frequently executed functions You can use the compiler s inline keyword to indicate that functions should have code generated inline at the point of call Doing this avoids various costs such as program flow latencies function entry and exit instructions and parameter passing overheads Using an inline function also has the advantage that the compiler can optimize through the inline VisualDSP 3 5 C Compiler and Library Manual 2 13 for ADSP 218x DSPs General Guidelines code and does not have to assume that scratch registers and condition states are modified by the call Prime candidates for inlining are small fre quently used functions because they will cause the least code size increase while giving most performance benefit As an example of the usage of the inline keyword the function below sums two input parameters and returns the result inline int add int a int b return a b Good use of the inline keyword Inlining has a code size to performance trade off that should be consid ered when it is used With 0a the compiler will automatically inline small functions where possible If the application has a tight upper code size limit the resulting code size expansion may be too great It is worth considering using automatic inlining in conjunction with the 0v n switch on page 1 33 to restrict inlining and other optimizations with a code
54. a C library function call the function by name and give the appro priate arguments The names and arguments for each function appear on the function s reference page The reference pages appear in C Run Time Library Reference on page 3 18 Like other functions you use library functions should be declared Decla rations are supplied in header files as described in the section Working with Library Header Files on page 3 5 Function names are C function names If you call C run time library func tions from an assembly language program you must use the assembly version of the function name prefix an underscore on the name For more information on naming conventions see the section C and Assembly Language Interface on page 1 148 You can use the archiver described in the VisualDSP 3 5 Linker and Utilities Manual for 16 Bit Processors to build library archive files of your own functions Using the Compiler s Built In Functions The C compiler s built in functions are a set of functions that the com piler immediately recognizes and replaces with inline assembly code instead of a function call Typically in line assembly code is faster than a library routine and it does not incur the calling overhead For example the absolute value function abs is recognized by the compiler which subsequently replaces a call to the C run time library version with an in line version 3 2 VisualDSP 3 5 C Compiler an
55. an optional parameter If you do not use the optional output name switch cc218x names the out put for you Table 1 1 lists the type of files names and extensions the compiler appends to output files File extensions vary by command line switch and file type These exten sions are influenced by the program that is processing the file any search directories that you select and any path information that you include in the file name Table 1 1 indicates the searches that the preprocessor compiler assem bler and linker support The compiler supports relative and absolute directory names to define file search paths Using the verbose output switches for the preprocessor compiler assembler and linker causes each of these tools to echo the name of each file as it is processed 1 8 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Table 1 1 Input and Output Files Input File Extension Input File Description Cc C source file wh Header file referenced by a Finclude statement i Preprocessed C source created when preprocess only E compiler switch is specified idl Interface definition language files for VCSE ipa opa Interprocedural analysis files used internally by the compiler when performing interprocedural analysis pch Precompiled header file S dSp asm Assembly language source file Lis Preprocessed assembly language source retained when save temps
56. and debugging This section contains e Using the Run Time Header on page 1 133 e Interrupt Table and Interface on page 1 133 e Autobuffering Support on page 1 134 e Stack Frame on page 1 136 e File I O Support on page 1 141 e Miscellaneous Information on page 1 143 e Register Classification on page 1 144 e Complete List of Registers on page 1 145 1 132 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Using the Run Time Header The run time header is an assembly language procedure that initializes the processor and sets up processor features to support the C run time envi ronment The default run time header source code for the ADSP 218x is in the 218x_hdr asm file This run time header performs the following operations e Initializes the C run time environment e Calls your main routine e Calls exit routine defined in the C run time library Jibc d1b if main returns e Defines system halt instruction called from exit routine Interrupt Table and Interface The interrupt table is an assembly language set of functions defined in named sections These get placed appropriately in the Linker Description File LDF to be executed at interrupt vector addresses The default code for the ADSP 218x DSP interrupt table is defined in 218x_int_tab asm The default interrupt table uses the following external symbols _lib_int_table Static table holding int
57. assertions See the A switch on page 1 18 for the list of standard assertions no std def The no std def disable standard macro definitions prevents the com piler from defining any default preprocessor macro definitions no std inc The no std inc disable standard include search switch directs the C preprocessor to search for header files in only the current directory and directories specified with 1 switch on page 1 25 You can invoke this switch by selecting the Ignore standard include paths check box in the VisualDSP Project Options dialog box Compile tab Preprocessor category VisualDSP 3 5 C Compiler and Library Manual 1 31 for ADSP 218x DSPs Compiler Command Line Reference no std lib The no std 1ib disable standard library search switch directs the linker to limit its search for libraries to directories specified with the L switch on page 1 27 The compiler also defines __NO_STD_LIB during the link ing stage and passes it to the linker so that the SEARCH_DIR directives in the LDF file can de disabled no widen muls The no widen muls disable widening multiplications switch disables the compiler optimization which it performs on multiplication operations By default the compiler attempts to optimize integer multiplication operations which are stored in a long result to utilize the double word MAC result registers of ADSP 218x DSPs The code produced this way is better suited to the
58. be specified with the debug types switch because it is implied For example cc218x debug types anyHeader h The implicit g option writes debugging information for only those typedefs that are referenced in the program The debug types option provides complete debugging information for all typedefs and structs default linkage asm C The default linkage asm assembler linkage and default linkage C C linkage switches direct the compiler to set the default linkage type C is the default linkage type Compatibility linkage 01dAsmCal11 to previous generation calling conventions cannot be set as a default linkage This switch can be specified in the Additional Options box located in the VisualDSP Project Options dialog box Compile tab General category VisualDSP 3 5 C Compiler and Library Manual 1 21 for ADSP 218x DSPs Compiler Command Line Reference dry The dry verbose dry run switch directs the compiler to display main driver actions but not to perform them dryrun The dryrun terse dry run switch directs the compiler to display top level driver actions but not to perform them The E stop after preprocessing switch directs the compiler to stop after the C preprocessor runs without compiling The output preprocessed source code prints the standard output stream lt stdout gt unless the out put file is specified with the o switch Note that the switch can be used in combination
59. being compiled These pragmas must be used at global scope immediately prior to a function definition These pragmas are VisualDSP 3 5 C Compiler and Library Manual 1 105 for ADSP 218x DSPs C Compiler Language Extensions pragma optimize_off This pragma turns off the optimizer if it was enabled This pragma has no effect if Interprocedural Optimization Analysis is enabled pragma optimize_for_space This pragma turns the optimizer back on if it was disabled or sets focus to give reduced code size a higher priority than high perfor mance where these conflict pragma optimize_for_speed This pragma turns the optimizer back on if it was disabled or sets focus to give high performance a higher priority than reduced code size where these conflict pragma optimize_as_cmd_line This pragma resets the optimization settings to be those specified on the cc218x command line when the compiler was invoked The following shows example uses of these pragmas pragma optimize_off void non_op non optimized code pragma optimize_for_space void op_for_si code optimized for size pragma optimize_for_speed void op_for_sp code optimized for speed subsequent functions declarations optimized for speed Linking Control Pragmas Linking pragmas change how a given global function or variable is viewed during the linking stage 1 1
60. char rem unsigned long int i i strtoul 2345 5 amp rem base 7 2345 rem 5 See Also atoi atol strtoul VisualDSP 3 5 C Compiler and Library Manual 3 151 for ADSP 218x DSPs C Run Time Library Reference strxfrm transform string using LC_COLLATE Synopsis include lt string h gt size_t strxfrm char sl1 const char s2 size_t n Description The strxfrm function transforms the string pointed to by s2 using the locale specific category LC_COLLATE It places the result in the array pointed to by s1 The function returns the length of the transformed string not including the terminating null character If n is zero and s1 is set to the null pointer then strxfrm will return the number of characters required for the transformed string Overlapping strings are not supported The transformation is such that strcmp will return the same result for two transformed strings as strco11 would for the same original strings However because only the C locale is defined in the ADSP 218x DSP environment the strxfrm function is similar to the strncpy function except that the null character is always appended at the end of the output string Error Conditions The strxfrm function does not return an error condition Example d Finclude lt string h gt char string1 50 strxfrm stringl SOMEFUN 49 SOMEFUN is copied into stringl 3 152 VisualDSP 3 5 C Compiler and Library Manual
61. copy with two calls say copy x y and later copy y z the interprocedural analysis will not be able to tell that a never aliases b Therefore the optimizer cannot be sure that one iteration of the loop is not dependent on the data calculated by the previous iteration of the loop If it is known that each iteration of the loop is not dependent on the pre vious iteration then the vector_for pragma can be used to explicitly notify the compiler that this is the case pragma loop_count min max modulo The pragma loop_count min max modulo appears just before the loop it describes It asserts that the loop will iterate at least min times no more than max times and a multiple of modulo times This information enables the optimizer to omit loop guards to decide whether the loop is worth completely unrolling and whether code need be generated for odd itera tions The last two arguments can be omitted if they are unknown For example int aig pragma loop_count 24 48 8 for i 0 i lt n i pragma vector_for The pragma vector_for notifies the optimizer that it is safe to execute two iterations of the loop in parallel The vector_for pragma does not force the compiler to vectorize the loop the optimizer checks various properties of the loop and does not vectorize it if it believes it is unsafe or if it cannot deduce that the various properties necessary for the vectoriza tion transformation are valid Strictly
62. correct bit in the Interrupt Force and Clear IFC Register Setting this bit forces a full interrupt and causes the program execution to change to the interrupt vec tor address for sig All other interrupts and signals are raised by calling the handler if set for sig directly from raise The sig argument must be one of the signals listed in priority order in Table 3 32 Table 3 32 Raise Function Signals Values and Meanings Sig Value Definition STGPWRDWN Power down interrupt STGIRQ2 Interrupt 2 SIGIRQL1 Interrupt 1 level sensitive SIGIRQLO Interrupt 0 level sensitive SIGSPORTOXMIT Signal Sport 0 transmit STGSPORTORECY Signal Sport 0 receive SIGIRQE Level sensitive VisualDSP 3 5 C Compiler and Library Manual 3 111 for ADSP 218x DSPs C Run Time Library Reference Table 3 32 Raise Function Signals Values and Meanings Contd Sig Value Definition SIGBDMA Byte DMA interrupt STGSPORTIXMIT Signal Sport 1 transmit SIGIRQ1 Interrupt 1 STGSPORTIRECV Signal Sport 1 receive SIGIRQO Interrupt 0 SIGTIMER Timer interrupt SIGABRT Software abort signal SIGILL Software illegal signal SIG Software segmentation signal SIGTERM Software termination signal SIGFPE Software floating point exception signal Interrupts are not nested by the default start up file Error Conditions The raise function retur
63. for ADSP 218x DSPs 3 127 C Run Time Library Reference strcoll compare strings Synopsis include lt string h gt int strcoll const char sl const char s2 Description The strcol1 function compares the string pointed to by s1 with the string pointed to by s2 The comparison is based on the locale macro LC_COLLATE Because only the C locale is defined in the ADSP 218x DSP environment the strcol1 function is identical to the strcmp function The function returns a positive value if the s1 string is greater than the s2 string a negative value if the s2 string is greater than the s1 string and a zero if the strings are the same Error Conditions The strcol1 function does not return an error condition Example include lt string h gt char stringl 50 string2 50 if strcoll stringl string2 printf s is different than 4s n stringl string2 See Also strcmp strncmp 3 128 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library strcpy copy from one string to another Synopsis d Finclude lt string h gt void strcpy char const char Description The strcpy function copies the null terminated string pointed to by s2 into the space pointed to by s1 Memory allocated for s1 must be large enough to hold s2 plus one space for the null character 0 The behav ior of strcpy is undefined if the two objects overlap or if s1 is not large enough Th
64. fractl6 fractl6 This function returns the 16 bit result of the fractional integer division of f1 by f2 f1 and f2 must both be positive fractional values with f2 greater than f1 Long division fractl6 div_l fract32 fractl6 VisualDSP 3 5 C Compiler and Library Manual 1 91 for ADSP 218x DSPs C Compiler Language Extensions This function produces a result which is the fractional integer division of the first parameter by the second Both inputs must be positive and the least significant word of the second parameter must be greater or equal to the first the result is positive leading bit equal to 0 and truncated to 16 bits Extract high most significant 16 bits fractl6 extract_h fract32 This function returns the 16 most significant bits if the 32 bit fract parameter provided Extract low least significant 16 bits fractl6 fract32 This function returns the 16 least significant bits of the 32 bit fract parameter provided Multiply and accumulate with rounding fractl6 mac_r fract32 fractl6 fractl6 This function performs an L_mac operation using the three parameters P P 8 P provided The result is the rounded 16 most significant bits of the 32 bit results from the L_mac operation Multiply and subtract with rounding fractl6o msu_r fract32 fractl6 fractl6 This function performs an L_msu operation using the three parameters P P g P provided The result is the rounded 16 most significant bits of
65. hyperbolic sine function 3 122 si revision silicon revision compiler switch 1 39 sizeof operator 1 122 SPORT 1 134 sport h header file 3 11 sqrt square root function 3 125 srand random number seed function 3 124 stack frame 1 136 free space 1 138 incoming arguments 1 137 linkage information 1 137 local variables temporaries 1 138 outgoing arguments 1 138 system wide specifications 1 138 stack pointer 1 136 stack usage pragma 1 108 standard conformances 1 3 Standard library functions memcmp 3 103 1 20 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs standard library functions abort 3 19 atexit 3 25 atof 3 26 atol 3 30 bsearch 3 34 div 3 49 exit 3 51 free 3 61 Idiv long division 3 96 malloc 3 101 rand 3 113 srand 3 124 strtol 3 148 strtoul 3 150 statement expression 1 117 statistical profiling 2 4 2 5 stdarg h header file 3 11 stdio functions 1 141 stdio h header file 1 141 3 11 stdlib h header file 3 12 stop see atexit exit functions strcat concatenate strings function 3 125 strchr find first occurrence of character in string function 3 126 strcmp compare strings function 3 127 3 130 strcoll compare strings function 3 128 strcpy copy from one string to another function 3 129 INDEX strcspn length of character segment in one string function 3 130 strerror get string containing error message function 3 131 string conversion see atof atoi atol strtok strt
66. in the string h Header File memchr memcmp memcpy memmove memset strcat strchr strcmp strcoll strcpy strcspn strerror strlen strncat strncmp strncpy strpbrk strrchr strspn strstr strtok strxfrm 3 16 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Table 3 29 Library Functions in the sysreg C Run Time Library h Header File disable_interrupts enable_interrupts io_space_read i0_space_write sysreg_read sysreg_write VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 3 17 C Run Time Library Reference C Run Time Library Reference The C run time library is a collection of functions that you can call from your C programs The information that follows applies to all of the functions in the library Notation Conventions An interval of numbers is indicated by the minimum and maximum sepa rated by a comma and enclosed in two square brackets two parentheses or one of each A square bracket indicates that the endpoint is included in the set of numbers a parenthesis indicates that the endpoint is not included Reference Format Each function in the library has a reference page These pages have the fol lowing format Name and Purpose of the function Synopsis Required header file and functional prototype Description Function specification Error Conditions How the function indicates an e
67. interests MyAnalog com provides access to books application notes data sheets code examples and more Registration Visit www myanalog com to sign up Click Register to use MyAnalog com Registration takes about five minutes and allows you to select the informa tion you want to receive If you are already a registered user just log on Your user name is your email address DSP Product Information For information on digital signal processors visit our website at www analog com which provides access to technical publications datasheets application notes product overviews and product announcements xxviii VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Preface You may also obtain additional information about Analog Devices and its products in any of the following ways e Email questions or requests for information to dsp support analog com e Fax questions or requests for information to 1 781 461 3010 North America 089 76 903 557 Europe e Access the Digital Signal Processing Division s FTP website at ftp ftp analog comor ftp 137 71 23 21 ftp ftp analog com Related Documents For information on product related development software see the follow ing publications VisualDSP 3 5 Getting Started Guide for 16 Bit Processors VisualDSP 3 5 User s Guide for 16 Bit Processors VisualDSP 3 5 Assembler and Preprocessor Manual for ADSP 218x and ADSP 219x DSPs VisualDSP 3 5 Linker
68. ipa switch causes additional files to be generated along with the object file produced by the compiler These files have ipa and opa filename extensions and should not be deleted manually unless the associ ated object file is also deleted All of the ipa optimizations are invoked after the initial link when a spe cial program has called the prelinker reinvokes the compiler to perform the new optimizations Because a file may be recompiled by the prelinker you cannot use the S option to see the final optimized assembler file when ipa is enabled Instead you must use the save temps switch so that the full com pile link cycle can be performed first Because IPA operates only during the final link the ipa switch has no benefit when compiling the source files to object format for inclusion in a library Although IPA will generate usage information for potential addi tional optimizations at the final link stage neither the usage information nor the module s source file are available when the linker includes a mod ule from a library Therefore each library module is compiled to the normal 0 optimization level The prelinker inspects object modules included from libraries and other object files which were not compiled with the ipa switch to see whether there are hidden references to the functions and variables defined in those objects which were compiled with the ipa switch and optimizes those variables and functions accordingly
69. isalpha isxdigit Dor 3 82 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs isgraph C Run Time Library detect printable character not including white space Synopsis dFinclude lt ctype h gt int isgraph int c Description The isgraph function determines if the argument is a printable character not including white space 0x21 0x7e If the argument is not a printable character isgraph returns a zero If the argument is a printable character isgraph returns a non zero value Error Conditions The isgraph function does not return any error conditions Example include lt ctype h gt int ch for ch 0 ch lt Ox7f ch printf 04x ch printf 2s isgraph ch graph putchar n See Also isalnum iscntrl isprint waa VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 3 83 C Run Time Library Reference isinf test for infinity Synopsis d Finclude lt math h gt int isinff float x int isinf double x Description The isinf function returns a zero if the argument is not set to the IEEE constant for Infnity or Infinity otherwise the function will return a non zero value Error Conditions The isinf function does not return or set any error conditions Example dFinclude lt stdio h gt d Finclude lt math h gt static int fail 0 main test int isinf double union double d float f unsigned
70. long by same short 1 96 multiply short by a long 1 98 multiply two longs 1 98 multiply with rounding 1 93 round 1 93 saturate 1 94 shift right with rounding 1 94 short absolute 1 91 short add 1 91 short division 1 91 short multiply 1 92 short negate 1 93 short normalize 1 93 short shift left 1 94 short shift right 1 94 short subtract 1 94 ETSI_fract_arith h header file 1 91 exit normal program termination function 3 51 INDEX exit macro 1 153 exp exponential function 3 52 extensions using compiler language 1 3 extra keywords not quite analog compiler switch 1 22 EZ KIT Lite 1 141 EZ kits 3 11 F fabs float absolute value function 3 53 false see Boolean type support keywords bool true false far jump return see longjmp setjmp functions Fast Fourier Transform functions 3 7 fflush NULL function reference 3 12 fN N point complex input FFT function 3 54 fftN functions 3 7 ffts h Fast Fourier Transforms 3 7 file extension 1 7 1 9 I O support 1 141 searches 1 8 searching lt filename gt 1 131 filenames on command line 1 18 filter functions biquad 3 31 filters h DSP filters 3 8 VisualDSP 3 5 C Compiler and Library Manual 1 9 for ADSP 218x DSPs INDEX fir finite impulse response filter function 3 57 flags command line input compiler switch 1 23 float representation 3 143 float h floating point header file 3 8 floating point hexadecimal constant
71. long int strtoul const char nptr char endptr int base Description The strtoul function returns as an unsigned long int the value repre sented by the string nptr If endptr is not a null pointer strtoul stores a pointer to the unconverted remainder in endptr The strtoul function breaks down the input into three sections e white space as determined by isspace e initial characters e unrecognized characters including a terminating null character The initial characters may be composed of an optional sign character 0x or 0X if base is 16 and those letters and digits which represent an integer with a radix of base The letters a z or A Z are assigned the values 10 to 35 and their use is permitted only when those values are less than the value of base If base is zero then the base is taken from the initial characters A leading 0x indicates base 16 a leading 0 indicates base 8 For any other leading characters base 10 is used If base is between 2 and 36 it is used as a base for conversion 3 150 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library Error Conditions The strtoul function returns a zero if no conversion can be made and a pointer to the invalid string is stored in the object pointed to by endptr If the correct value results in an overflow ULONG_MAX is returned ERANGE is stored in errno in the case of overflow Example include lt stdlib h gt define base 10
72. lt string h gt char stringl 50 ptr stringllL0 0 ptr strncat stringl MOREFUN 4 stringl equals MORE See Also strcat VisualDSP 3 5 C Compiler and Library Manual 3 133 for ADSP 218x DSPs C Run Time Library Reference strncmp compare characters in strings Synopsis include lt string h gt int strncemp const char s1 const char s2 size_t n Description The strncmp function lexicographically compares up to n characters of the null terminated strings pointed to by s1 and s2 It returns a positive value if the s1 string is greater than the s2 string a negative value if the s2 string is greater than the s1 string and a zero if the strings are the same Error Conditions The strncmp function does not return an error condition Example include lt string h gt char ptrl ptrl TESTI if strncmp ptri TEST 4 0 printf s starts with TEST n ptr1 See Also memecmp strcmp 3 134 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library strncpy copy characters from one string to another Synopsis d Finclude lt string h gt char strncpy char sl const char s2 size_t n Description The strncpy function copies up to n characters of the null terminated string pointed to by s2 into the space pointed to by s1 If the last character copied from s2 is not a null the result does not end with a null The behavior of s
73. ment will be caught by the assembler and not the compiler Examples of efficient use of built in functions are given in System Sup port Built in Functions on page 2 25 Memory Usage The compiler in conjunction with the use of the linker description file LDF allows the programmer control over where data is placed in mem ory This section describes how to best lay out data for maximum performance Tip Try to put arrays into different memory sections The DSP hardware can support two memory operations on a single instruction line combined with a compute instruction However two memory operations will only complete in one cycle if the two addresses are situated in different memory blocks if both access the same block then a stall will be incurred VisualDSP 3 5 C Compiler and Library Manual 2 15 for ADSP 218x DSPs General Guidelines Take as an example the dot product loop below Because data is loaded from both array a and array b in every iteration of the loop it may be use ful to ensure that these arrays are located in different blocks for i 0 1 lt 100 i sum a i bli Bad compiler assumes that two memory accesses together may give a stall This is done by using the Dual Memory Support Language Keywords compiler extension Placing a pm qualifier before the type definition tells the compiler that the array is located in Program Memory PM The memory may be accessed in parallel
74. not cover all the built in functions available for more information refer to Compiler Built in Functions on page 1 83 it presents some code examples where implementation choices are available to the programmer Fractional Data Fractional data represented as an integral type can be manipulated in two ways one way is the use of long promoted shifts and multiply constructs and the other is the use of compiler built in functions The built in func tions are recommended as they give you the most control over your data Let s consider the fractional dot product algorithm This may be written as long dot_product short a short b int i long sum 0 for i 0 i lt 100 i this line is performance critical sum long aLil bLi lt lt 1 return sum Bad uses shifts to implement fractional multiplication This presents some problems to the optimizer Normally the code gener ated here would be a multiply followed by a shift followed by an accumulation However the DSP hardware has a fractional multiply accu mulate instruction that performs all these tasks in one cycle 2 24 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Achieving Optimal Performance from C Source Code In the example code the compiler recognizes this idiom and replaces the multiply followed by shift with a fractional multiply In more complicated cases where perhaps the multiply is further sepa
75. not need to specify retain_name for main For more information see Interprocedural Analysis on page 1 50 pragma weak_entry The pragma weak_entry may be used before a static variable declaration or definition It applies to the function or variable declaration or defini tion that immediately follows the pragma Use of this pragma causes the compiler to generate the function or variable definition with weak linkage The following are example uses of the pragma weak_entry directive pragma weak_entry int w_var 0 pragma weak_entry void w_func Stack Usage Pragma The C compiler for ADSP 218x DSPs supports the stack usage pragma make_auto_static pragma make_auto_static The make_auto_static pragma may be used before a function definition The make_auto_static pragma directs the compiler to place all automatic variables used in the function in static store This may be beneficial in code that requires many accesses of automatic variables This is because an access to static store for the ADSP 218x DSPs is done in one instruction whereas an access to local automatic stack are may require three instruc tions The make autostatic switch on page 1 29 can be used to notify the compiler to process all function definition in the current source being compiled as if pragma make_auto_static had been used 1 108 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Make sure that the make_a
76. operators should therefore be avoided where possible especially in loops 2 8 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Achieving Optimal Performance from C Source Code Getting the Most from IPA Interprocedural analysis IPA is designed to try to propagate information about the program to parts of the optimizer that can use it This section looks at what information is useful and how to structure your code to make this information easily accessible to the analysis Initializing Constants Statically IPA will identify variables that have only one value and replace them with constants resulting in a host of benefits for the optimizer s analysis For this to happen a variable must have a single value throughout the pro gram If the variable is statically initialized to zero as all global variables are by default and is subsequently assigned some other value at another point in the program then the analysis sees two values and will not con sider the variable to have a constant value For example include lt stdio h gt int val initialized to zero void init val 3 re assigned void func printf val d val int main jnit func Bad IPA cannot see that val is a constant VisualDSP 3 5 C Compiler and Library Manual 2 9 for ADSP 218x DSPs General Guidelines is better written as include lt stdio h gt const int val 3 initialized once
77. or that have direct influence on the optimization levels performed e Debug The compiler produces debug information to ensure that the object code matches the appropriate source code line See g on page 1 23 for more information e Default The compiler does not perform any optimizations by default when none of the compiler optimization switches are used or enabled in VisualDSP project options Default optimization level can be enabled using the optimize_off pragma on page 1 105 e Procedural Optimizations The compiler performs advanced aggressive optimization on each procedure in the file being compiled The optimizations can be directed to favor optimizations for speed 0 or space 0s ora factor between speed and space 0v If debugging is also VisualDSP 3 5 C Compiler and Library Manual 1 49 for ADSP 218x DSPs Compiler Command Line Reference requested the optimization is given priority so the debugging functionality may be limited See O on page 1 32 Os on page 1 33 and Ov num on page 1 33 Procedural optimizations for speed and space using 0 and 0s can be enabled in C source using the pragma optimize_ for_speed for_space see on page 1 105 for more information on optimization pragmas e Automatic Inlining The compiler automatically inlines C functions which are not nec essarily declared as inline in the source code It does this when it has determined that doing so will r
78. output flushing 3 12 generated by printf 3 12 Ov optimize for speed vs size compiler switch 1 33 1 16 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs P P omit line compiler switch 1 34 P omit line numbers compiler switch 1 34 path install installation location compiler switch 1 34 path output non temporary files location compiler switch 1 35 path temp temporary files location compiler switch 1 35 path tool tool location compiler switch 1 34 pch precompiled header compiler switch 1 35 pchdir locate PCHRepository compiler switch 1 35 PCHRepository directory 1 35 pedantic ANSI standard warnings compiler switch 1 35 pedantic errors ANSI C errors compiler switch 1 36 placement support keyword section 1 76 support keyword segment 1 53 pm see dual memory support keywords pm dm PM support standard C library 1 76 pointer arithmetic action on 1 122 incrementing 2 12 input parameter types 1 76 INDEX pointer class support keyword restrict 1 53 1 77 pow raise to a power function 3 108 pplist preprocessor listing compiler switch 1 36 pragmas 1 99 align num 1 101 alloc 1 109 altregisters 1 103 const 1 110 function side effect 1 109 hdrstop 1 115 header file control 1 115 interrupt 1 102 1 103 interrupt handler 1 102 linkage_name 1 107 linking 1 106 linking control 1 106 loop optimization 1 103 2 33 loop_count min max modulo 1 104 make_auto_ st
79. sin 3 22 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library atan arc tangent Synopsis include lt math h gt double atan double x float atanf float x fractl6 atan_frl6 fractl6 x Description The atan function returns the arc tangent of the argument The output in radians is in the range 7 2 to 7 2 The atan_fr16 function covers the output range from 7 4 input value 0x8000 output value 0x9878 to 1 4 input value 0x7FFF output value 0x6488 The input argument is in radians Error Conditions The atan function does not return an error condition Example d Finclude lt math h gt double y y atan 0 0 y 0 0 See Also atan2 tan VisualDSP 3 5 C Compiler and Library Manual 3 23 for ADSP 218x DSPs C Run Time Library Reference atan2 arc tangent of quotient Synopsis include lt math h gt double atan2 double x double y float atan2f float x float y fractl6 atan2 fractl6 x fractl6 y Description The atan2 function computes the arc tangent of the input value x divided by input value y The output in radians is in the range 7 T The atan2_fr16 function uses the full range from 7 4 to 1 4 0x8000 to 0x7FFF for both input and output arguments This corresponds to a scal ing by n compared to the floating point function The input argument is in radians Error Conditions The atan2 function returns a zero if x
80. size cost to parts of the application that are performance critical This will be considered in more detail later in this chapter Using Inline asm Statements The compiler allows use of inline asm statements to insert small sections of assembly into C code Tip Avoid use of inline asm statements where built in functions may be used instead The compiler does not intensively optimize code that contains inline asm statements because it has little understanding about what the code in the statement does In particular use of an asm statement in a loop may inhibit useful transformations 2 14 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Achieving Optimal Performance from C Source Code The compiler has been enhanced with a large number of built in func tions These generate specific hardware instructions and are designed to allow the programmer to more finely tune the code produced by the com piler or to allow access to system support functions A complete list of compiler s built in functions is given in Compiler Built in Functions on page 1 83 Use of these builtins is much preferred to using inline asm statements Since the compiler knows what each builtin does it can easily optimize around them Conversely since the compiler does not parse asm state ments it does not know what they do and so is hindered in optimizing code that uses them Note also that errors in the text string of an asm state
81. speaking the pragma simply disables checking for loop carried dependencies void copy short a short b int i 1 104 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler pragma vector_for for i 0 i lt 100 i ali bli In cases where vectorization is impossible for example if array a were aligned on a word boundary but array b was not the information given in the assertion made by vector_for may still be put to good use in aiding other optimizations pragma no_alias Use the pragma no_alias to tell the compiler the following has no loads or stores that conflict due to references to the same location through dif ferent pointers known as aliases In this example void vadd int a int b int out int n int i fpragma no_alias for i 0 i lt n i out i ali b i the use of pragma no_alias just before the loop informs the compiler that the pointers a b and out point to different arrays so no load from b or a will be using the same address as any store to out Therefore a i or bli is never an alias for out i The use of the no_alias pragma can lead to better code because it allows the loads and stores to be reordered and any number of iterations to be performed concurrently thus providing better software pipelining by the optimizer General Optimization Pragmas There are three pragmas which can change the optimization level while a given module is
82. the ADSP 218x DSPs Additionally Analog Devices includes within the com piler a number of C language extensions designed to assist in DSP development The cc218x compiler runs from the VisualDSP environ ment or from an operating system command line The C compiler cc218x processes your C language source files and pro duces ADSP 218x DSP s assembler source files The assembler source files are assembled by the ADSP 218x assembler easm218x The assembler creates Executable and Linkable Format ELF object files that can either be linked using the linker to create an ADSP 218x executable file or included in an archive library using el far The way in which the com piler controls the assemble link and archive phases of the process depends on the source input files and the compiler options used Source files contain C programs to be processed by the compiler The compiler takes these source files for preprocessing first Preprocessed source files are assembled by the ADSP 218x DSP assembler easm218x 1 2 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler The assembler creates Executable and Linkable Format object files that can either be linked using the linker to create an ADSP 218x executable file The cc218x compiler supports the ANSI ISO standard definitions of the C language For information on these standards see any of the many ref erence texts on the C language In addition to ANSI st
83. these features are available in the C99 ANSI Standard A brief description of the extensions is included in this section For more information refer to the following web address http gcc gnu org onlinedocs gcc 3 2 1 gcc C Extensions html C 20Extensions Statement Expressions A statement expression is a compound statement enclosed in parentheses A compound statement itself is enclosed in braces so this construct is enclosed in parentheses brace pairs The value computed by a statement expression is the value of the last statement which should be an expression statement The statement expres sion may be used where expressions of its result type may be used But they are not allowed in constant expressions Statement expressions are useful in the definition of macros as they allow the declaration of variables local to the macro In the following example define min a b d short __x a __y b __res if X gt y _ res _ y else _ res _ x res int use_min return min foo thing 2 VisualDSP 3 5 C Compiler and Library Manual 1 117 for ADSP 218x DSPs C Compiler Language Extensions The foo and thing statement get called once each because they are assigned to the variables __x and __y which are local to the statement expression that min expands to and min can be used freely within a larger expression because it expands to an expression Labels local to a sta
84. to emit an instruc tion to enable hardware interrupts This function is implemented as a compiler built in the emitted instruc tion will be inline at the point of enable_interrupts use The inclusion of the sysreg h include file is mandatory when using enable_interrupts The enable_interrupts function does not return a value Error Conditions The enable_interrupts function does not return raise or set any error conditions Example include lt sysreg h gt main enable_interrupts emits ENA INTS instruction inline See Also disable_interrupts io_space_read io_space_write sysreg_read sysreg_write 3 50 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library exit normal program termination Synopsis d include lt stdlib h gt void exit int status Description The exit function causes normal program termination The functions registered by the atexit function are called in reverse order of their regis tration and the microprocessor is put into the IDLE state The status argument is stored in register AX1 and control is passed to the label ___1ib_prog_term which is defined in the run time start up Error Conditions The exit function does not return an error condition Example d Finclude lt stdlib h gt exit EXIT_SUCCESS See Also abort atexit VisualDSP 3 5 C Compiler and Library Manual 3 51 for ADSP 218x DSPs C Run Time Library Referenc
85. used and you wish to use the preserved registers you must save their contents and then restore those contents before returning 1 148 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler In general you should perform the following steps when writing C call able assembly subroutines e Familiarize yourself with the general features of the C run time model This should include the general notion of a stack how arguments are handled and also the various data types and their sizes e Create an interface definition or prototype so that the C pro gram knows the name of your function and the types of its arguments The prototype also determines how the arguments are passed In C mode the compiler allows you to use a function without a prototype In this case the compiler assumes that all the argu ments as they appear in the call are of the proper type even though this may not be desired The compiler also assumes that the return type is integer e The compiler normally prefaces the name of external entry points with an underscore You can simply declare the function with an underscore as the compiler does When using the function from assembly programs you might want your function s name to be just as you write it Then you will also need to tell the C compiler that it is an asm function by placing extern asm around the prototype e The C run time determines that all function para
86. will contain b 3 66 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library Both the a_coeffs and b_coeffs arrays must be located in program mem ory PM so that the single cycle dual memory fetch of the processor can be used When importing coefficients from a filter design tool that employs a transposed direct form II the a and a coefficients have to be negated For example if a filter design tool returns A 1 0 0 2 0 9 then the a coefficients will first have to be inverted to A 1 0 0 2 0 9 The state array contains a pointer to the delay line as its last element pre ceded by the delay line values The length of the state array is therefore one 1 greater than the number of taps Each filter has its own state array which should not be modified by the calling program only by the iir func tion The state array should be initialized to zeros 0 before the iir function is called for the first time The state array needs to be declared on a circular boundary The parameters sample a_coeffs b_coeffs and state are all con sidered to be fractional numbers The iir function executes fractional multiplications that preserve the format of the fractional input The following flow graph corresponds to the iir routine as part of the C Run Time Library adapted from the Oppenheim and Schafer text Digital Signal Processing from Prentice Hall 1975 e The b_coeffs and s
87. with a Linker Description File word dD dM and dN Output the results of prepro Removed cessing and or list of defines deps Generate dependencies list Removed fcond mismatch Allow conditional expression Removed mismatch finline functions Force function inlining Removed fkeep inline functions Force keeping of inlined func Removed tions fno asm Don t recognize asm as a key Replaced with no extra keywords fno builtin fsigned bitfields funsigned bitfields Don t recognize builtin func tions Control whether bit field is signed or unsigned Replaced with no builtin Removed Bitfield is signed or unsigned based on the sign of the type definition declaring the bitfield fno signed bitfields fno unsigned bitields Negative form of the fsigned bitfield and funsigned bitfield Replaced with signed bitfield and unsigned bitfield fsigned char funsigned char Specify whether to default to signed or unsigned char type Replaced with signed char and unsigned char VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Tools Differences Table A 1 Obsolete and Replaced Switches Contd Switch Name Operation under Release 6 1 Change for VisualDSP 3 5 fsyntax_only Check syntax only no output Replaced with syntax only fwritable strings Store string co
88. with the E switch ED The ED run after preprocessing to file switch directs the compiler to write the output of the C preprocessor to a file named original_filename i After preprocessing compilation proceeds normally The EE run after preprocessing switch directs the compiler to write the output of the C preprocessor to standard output After preprocessing compilation proceeds normally extra keywords The extra keywords enable short form keywords switch directs the compiler to recognize the Analog Devices keyword extensions to ISO ANSI standard C language including keywords such as pm and dm 1 22 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler without leading underscores which could affect conforming to ISO ANSI C programs This is the default mode The no extra keywords switch see on page 1 30 can be used to disallow support for the additional key words Table 1 5 on page 1 53 provides a list and a brief description of keyword extensions flags asm compiler lib link mem switch switch2 The flags command line input switch directs the compiler to pass each of the comma separated arguments to the other build tools such as Table 1 3 Build Tools Options Option Tool flags asm easm218x Assembler flags compiler Compiler executable flags lib elfar Library Builder flags link Linker flags mem Memory Initializer
89. 0 andy lt gt 0 Example d Finclude lt math h gt double a float b ll atan2 0 0 0 5 the error condition a 0 0 atan2 1 0 0 0 b 1 2 o ll See Also atan tan 3 24 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library atexit register a function to call at program termination Synopsis include lt stdlib h gt int atexit void func void Description The atexit function registers a function to be called at program termina tion Functions are called once for each time they are registered in the reverse order of registration Up to 32 functions can be registered using atexit Error Conditions The atexit function returns a non zero value if the function cannot be registered Example include lt stdlib h gt extern void goodbye void if atexit goodbye exit 1 See Also abort exit VisualDSP 3 5 C Compiler and Library Manual 3 25 for ADSP 218x DSPs C Run Time Library Reference atof convert string to a double Synopsis include lt stdlib h gt double atof const char nptr Description The atof function converts a character string into a floating point value of type double and returns its value The character string is pointed to by the argument nptr and may contain any number of leading whitespace characters as determined by the function isspace followed by a floating point number The floating poi
90. 06 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler pragma linkage_name identifier The pragma 1inkage_name associates the identifier with the next exter nal function declaration It ensures that identifier is used as the external reference instead of following the compiler s usual conventions If identifier is not a valid function name as could be used in normal func tion definitions the compiler will generate an error The following shows an example use of this pragma pragma linkage_name realfuncname void funcname void func funcname compiler will generate a call to realfuncname pragma retain_name The pragma retain_name indicates that the external function or variable declaration that follows the pragma is not removed even though Interpro cedural Analysis IPA sees that it is not used Use this pragma for C functions that are only called from assembler routines such as the startup code sequence invoked before main The following example shows how to use this pragma int delete_me int x return x 2 pragma retain_name int keep_me int y return yt2 int main void return 0 VisualDSP 3 5 C Compiler and Library Manual 1 107 for ADSP 218x DSPs C Compiler Language Extensions Since the program has no uses of either delete_me or keep_me the compiler will remove delete_me but will keep keep_me because of the pragma You do
91. 10 function accepts no arguments Instead it examines the I O control block at label _prim10C8 Without external intervention by a host environment the _primI0 routine simply returns which indicates failure of the request At program termination the host environment will close down any physi cal connection between the application and an opened file However the T O library will not implicitly close any opened streams to avoid an unnec essary overheads particularly with respect to memory occupancy Therefore unless explicit action is taken by an application any unflushed output may be lost Any output generated by printf is always flushed but output generated by other library functions such as putchar fwrite fprintf will not be automatically flushed Applications should therefore arrange to close down any streams that they open Note that the function reference fflush NULL will flush the buffers of all opened streams stdlib h The stdlib h header file contains general utilities specified by the C stan dard These include some integer math functions such as abs div and rand general string to numeric conversions memory allocation functions such as malloc and free and termination functions such as exit This header file also contains prototypes for miscellaneous functions such as bsearch and qsort string h The string h header file contains string handling functions including strcpy and memcpy 3 12 VisualDSP
92. 101 longjmp second return from setjmp function 3 99 loop exit test 2 21 iteration count 2 33 optimization 1 103 2 33 parallel processing 1 104 rotatiing by hand 2 18 short 2 17 unrolling 2 17 vectorizing 1 103 loop control automatic variables 2 21 variables 2 21 loop kernels short 2 34 loop carried dependency 2 18 lower case see islower tolower functions lvalue GCC generalized 1 119 M M generate make rules only compiler switch 1 27 macros __NO_LONG_LONG 1 127 __ VERSION __ 1 128 _ADSP21_ 1 126 _ADSP21XX_and_ADSP218X_ 1 126 _ANALOG_EXTENSIONS_ 1 126 _DATE_ 1 126 _DOUBLES_ARE_FLOATS_ 1 126 _ECC_ 1 126 _EDG_ 1 126 _EDG_VERSION_ 1 127 _FILE_ 1 127 _LINE_ 1 127 _NO_BUILTIN 1 127 _SIGNED_CHARS_ 1 127 _STDC_ 1 128 _STDC_VERSION_ 1 128 _TIME_ 1 128 compound statements 1 129 EDOM 3 9 ERANGE 3 9 for C Assembly interface support 1 152 HUGE_VAL 3 9 variable argument 1 121 macros and asm C program constructs 1 70 make autostatic make automatic variables static compiler switch 1 29 1 108 malloc allocate memory function 1 109 3 101 map generate a memory map compiler switch 1 29 map file with xml extension 1 29 math h header file 3 9 mathematical functions 1 14 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs floating point 3 9 floating point 3 9 maximum performance 2 27 MD make and compile compiler switch 1 28 mem invoke memory initializer compiler switch
93. 18x DSPs is always 32 bits This should be acceptable for most DSP programming It is not however fully standard conforming The standard include files automatically redefine the math library inter faces such that functions like sin can be directly called with the proper size operands therefore float sinf float 32 bit double sin double L 32 bit 7 For full descriptions of these functions and their implementation see Chapter 3 C Run Time Library 1 48 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Optimization Control The general aim of compiler optimization is to generate correct code that executes fast and is small in size Not all optimizations are suitable for every application or possible all the time so the compiler optimizer has a number of configurations or optimization levels which can be applied when suitable Each of these levels are enabled by one or more compiler switches and VisualDSP project options or pragmas Refer to Chapter 2 Achieving Optimal Performance from C Source Code for information on how to obtain maximal code per formance from the compiler The following list identifies several optimization levels The levels are notionally ordered with least optimization listed first and most optimiza tion listed last The descriptions for each level outline the optimizations performed by the compiler and identifies any switches or pragmas required
94. 20 dry verbose dry run 1 22 dryrun terse dry run 1 22 E stop after preprocessing 1 22 ED run after preprocessing to Ale 122 EE run after preprocessing 1 22 extra keywords 1 22 flags command line input 1 23 fp associative 1 23 full version display version 1 23 g generate debug information 1 23 H list headers 1 24 h elp command line help 1 24 HH list headers and compile 1 4 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 1 24 I start include directory 1 25 I directory include search directory 1 25 include filename include file 1 25 ipa interprocedural analysis 1 26 jump dm pm same select jump table memory type 1 26 L library search directory 1 27 l link library 1 27 M generate make rules only 1 27 make autostatic make automatic variables static 1 29 map generate a memory map 1 29 MD generate make rules and compile 1 28 mem invoke memory initializer 1 29 MM generate make rules and compile 1 28 Mo processor output file 1 28 MQ 1 28 Mt output make rules 1 28 no alttok disable tokens 1 29 no bss 1 30 no builtin no built in functions 1 30 no defs disable defaults 1 30 no extra keywords disable short form keywords 1 30 INDEX no fp associative 1 31 no mem not invoking memory initializer 1 31 no std ass disable standard assertions 1 31 no std def disable st
95. 22 Using the Conse eerie enrcoenen eee enienton 2 23 Using Built in Functions in Code Optimization 0 0 eee 2 24 POW D ai ecurine 2 24 System Support Built in Functions os cccsssepocesencancrseesneeucneds 2 25 Smaller Applications Optimizing for Code Size eseese 2 27 aa E T E E E E E E 2 29 Funeton Pramas satescsnasiciesadisnen taeeecsanseeenuaees LEAI Fpa CONSE aradienrene nr r 229 Fpragma PUTE sa vsrarscrnisatvcansiarsertsasiesersrabvenveonsearncsbcbesveondien 2 30 i CLL AoE ar REET ee nOn DEN Dereon ne nrnn EN ere ont oer seve 2 30 Fpragma reps clobbered dices ockacsnnsrnaniorsecenenyiememenecuies 2 31 pragma optimize_ off for_speed for_space as_cmd_line 2 33 Loop Uprimmzation Pramas cscccicisiceccrsarsciversrsancenunercisteaoeiexe 2 33 Fpropma loop COWIE arnar a 2 33 PEN mO E annas 2 34 Useful Optimization Switchog sssnusisiiteneniirarinen ienen 2 35 C RUN TIME LIBRARY C Ron Time Library GONE dsr iek a a 3 2 Calling Library FUNG sacsieenidasia 3 2 xvi VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs CONTENTS Using the Compilers Built In Functions ssccscciessarcceertencenescsnves Linking Libiary Punco socio anmelden Working With Library Source Code cs cccstsendcnisaceuenaieoasteoseenionns Working with Library Header Files smisesecscimeneeriieui T E SAEPE D AIE OE E ER E E AE E ery def2181 h Memory Map Definitions sssssisrisirernsisis def218 lxh Memory Map Definitions scvoscsscccsarsercscsyavensaes E
96. 3 8 stdio h 1 141 help command line help compiler switch 1 24 hexadecimal digit test see isxdigit function hexadecimal floating point constants 1 120 HH list h and compile compiler switch 1 24 hyperbolic sine 3 122 tangent 3 159 I I include search directory compiler switch 1 25 1 31 I start include directory compiler switch 1 25 INDEX functions 3 11 new device support 1 141 primitives 3 11 I O file support 1 141 space address 1 84 I O functions primitive 3 11 IFC Interrupt Force and Clear register 3 38 ifftN inverse complex FFT function 3 63 iir infinite impulse response filter function 3 66 IIR filter coefficients 3 66 include include file compiler switch 1 25 include directives 1 131 indexed array 2 12 initializer 1 80 A 4 induction variables 2 19 infinite impulse response IIR filter 3 66 initializers ageregate 1 80 array 1 80 indexed 1 80 A 4 inline asm keyword construct template 1 57 asm statements 2 14 assembler 1 57 I O files 1 9 assembly code 1 132 VisualDSP 3 5 C Compiler and Library Manual I 11 for ADSP 218x DSPs INDEX assembly support keyword asm 1 56 keyword 2 13 2 28 inline assembly language support keyword asm construct I O operands 1 68 construct template 1 57 construct template operands 1 61 constructs optimization 1 68 constructs with multiple instructions 1 67 macros containing asm 1 70 inline code avoiding 2 28 inline function sup
97. 3 89 ispunct detect punctuation character function 3 90 isspace detect whitespace character function 3 91 isupper detect uppercase character function 3 92 isxdigit detect hexadecimal digit function 3 93 J jump dm pm same select jump table memory type compiler switch 1 26 K keywords boolean 1 77 illegal 1 75 illegal dual memory support 1 75 memory macros 1 75 keywords compiler see compiler C extensions L L library search directory compiler switch 1 27 INDEX link library compiler switch 1 27 labs long integer absolute value function 3 94 language extensions compiler see compiler C extensions Idexp multiple by power of 2 function 3 95 Idiv division long function 3 96 Idiv long division function 3 96 leaf procedure 1 136 leaf_entry macro 1 153 leaf_exit macro 1 153 library header files working with 3 5 linking functions 3 3 source code working with 3 4 line breaks in string literals 1 121 linking library functions 3 3 pragmas for 1 106 locale h header file 3 9 localtime return address of encoded calendar time function 3 97 log natural logarithm function 3 97 log logf log base e function 3 101 log10 base 10 logarithm function 3 98 log10 log10f log base 10 function 3 101 long division 3 96 long jump see longjmp setjmp functions VisualDSP 3 5 C Compiler and Library Manual I 13 for ADSP 218x DSPs INDEX longjmp far jump return function 3
98. 5 C Compiler and Library Manual for ADSP 218x DSPs 3 C RUN TIME LIBRARY The C run time library is a collection of functions that you can call from your C programs Many of these functions are implemented in ADSP 218x DSP s assembly language C programs depend on library functions to perform operations that are basic to the C language These operations include memory allocation character and string conversions and math calculations This chapter describes the current release of the run time library Future releases may include more functions You may use the object files of the library functions in systems based on ADSP 218x processors This chapter contains e C Run Time Library Guide on page 3 2 e Documented Library Functions on page 3 14 e C Run Time Library Reference on page 3 18 For more information on the C standard library see The Standard C Library by P J Plauger Prentice Hall 1992 For more informa tion on the algorithms on which many of the library s math functions are based see Cody W J and W Waite Software Manual For The Elementary Functions Englewood Cliffs New Jer sey Prentice Hall 1980 VisualDSP 3 5 C Compiler and Library Manual 3 1 for ADSP 218x DSPs C Run Time Library Guide C Run Time Library Guide The C run time library contains functions that you can call from your C program This section describes how to use the library Calling Library Functions To use
99. 83 84 85 86 87 88 89 _ cc218x defines __ADSP21 81 83 84 85 86 87 88 89 __ as 1 when you compile with the corresponding proc ADSP 21 81 83 84 85 86 87 88 89 command line switch ANALOG _EXTENSIONS__ cc218x defines __ANALOG_EXTENSIONS__ as 1 unless you compile with pedantic or pedantic errors DATE__ The preprocessor expands this macro into the current date as a string con stant The date string constant takes the form mm dd yyyy ANSI standard DOUBLES _ARE_ FLOATS __ cc218x always defines __DOUBLES_ARE_FLOATS__as 1 ECC cc218x always defines __ECC__as 1 _EDG __ cc218x always defines __EDG__as 1 This signifies that an Edison Design Group front end is being used 1 126 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler __EDG_VERSION__ cc218x always defines __EDG_VERSION__ as an integral value representing the version of the compiler s front end __FILE__ The preprocessor expands this macro into the current input file name as a string constant The string matches the name of the file specified on the cc218x command line or in a preprocessor include command ANSI standard _LANGUAGE_C cc218x always defines _LANGUAGE_C as 1 when compiling C source __LINE__ The preprocessor expands this macro into the current input line number as a decimal integer constant ANSI standard __NO_ BUILTIN cc218x defines __NO_BUILTIN as 1 when you compile with the no built
100. AC MX1 MXO SR1 SRO MRI MRO AR B input yregs to MAC MY1 MYO c results from ALU AR C result from int multiplies MRO cc Used in the clobber list to tell the ASTAT compiler that condition codes have been clobbered d input xregs to SHIFTER SI SR1 SRO MR1 MRO AR D result from shift SR1 e data registers size 16 SI AX1 AXO MX1 MXO MYO MY1 AY1 AYO MRI MRO SRI SRO AR f shift amount SE g ALU X registers AX1 AXO AR SR1 SRO MR1 MRO G ALU Y registers AY1 AYO memory Used in the clobber list to tell the compiler that the asm statement writes to memory r all registers SR1 SRO SI MY1 MX1 AY1 AX1 MYO MXO AYO AXO MR1 MRO AR IO I7 O M7 LO L7 u DAGI L registers LO L3 v DAG2 L registers L4 L7 w DAGI I registers 0 13 x DAGI M registers MO M3 y DAG2 I registers 4 17 VisualDSP 3 5 C Compiler and Library Manual 1 65 for ADSP 218x DSPs C Compiler Language Extensions Table 1 7 ASM Operand Constraints Cont d Constraint Description Registers Z DAG2 M registers M4 M7 amp constraint Indicates that the constraint is applied to an output operand that may not overlap an input operand constraint Indicates that the constraint is applied to an output operand amp constraint Indicates the constraint is applied to an input operand that may not be overlapped with an output operand amp constraint Indicates the constraint is applied to an output operand that may not overl
101. AEAN A 1 22 ETTU rsisi aah AA A 1 22 iv VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs CONTENTS SIE pave E E ben EA E A EE AAEN AE E aero 1 22 PEET eiui AS 1 22 i E N E EAE NTER EPE A E A A ETE E 1 22 et ha oa E E cane eee 1 22 flags asm compiler lib link mem switch switch2 1 23 APO E a 1 23 SL O ar Herein Ree tty tle eine Ber Reena eT erent See omar ee neon 1 23 E EE NE A O IE man 1 23 ge E RE 1 24 l E EE A E E EE A E E SN OEE AS N 1 24 E EE A A ET 1 24 ae E ene ner A E eer emer eter errant mer r ret crore E er nar 1 25 direc KAF dreto ctceacestisicieenetenaeacns 1 25 hie Kenane saoto E 1 25 E a A AE A A 1 26 J ump idmlpmleamet oa 1 26 L directory Hi directora cuscinenrnmetnenandiemsanen 1 27 e ETIT Pee etter ac cee Reece ESE Dee ner ary UiteT BE ORY ser oT E EEE RUEETE OP aerr 1 27 a1 davies E E 1 27 HILL A E O AA E EAT A A AE 1 28 NN rai E Galaaaec np aetna 1 28 Mo filename sessirnir nN raaa N a 1 28 Me Tenane oeaiei lie A wlan ihdeaa aca etas iene 1 28 aT Ree Eee Cae eee erat en ome eee 1 28 VisualDSP 3 5 C Compiler and Library Manual v for ADSP 218x DSPs CONTENTS sima NAO saae n 1 29 iG TENS ea 1 29 STEIN 52 isc stig R AON 1 29 WING E EE A E E E E E E 1 29 E dunn E T I A E E T E 1 30 ODAL ir A E 1 30 E E E E E E er S 1 30 socata I enS 1 30 OLPC TINE oaa a RAO 1 31 RE AEE NA 1 31 E E S A A T EA E E 1 31 OSALETE sae ceeds ees 1 31 r ai E 1 31 AOA Geek EA aeraseniaid
102. AYO AY1 AR M5 I6 CCset int add_mask int a int b return at b amp 255 Good function compiled to preserve most registers to ensure that any other registers aside from AX1 AYO AY1 AR M5 16 and the condition codes will not be modified by the function If any other registers are used in the compilation of the function they will be saved and restored during the function prologue and epilogue In general it is not very helpful to specify any of the condition codes as call preserved as they are difficult to save and restore and are usually clob bered by any function Moreover it is usually of limited benefit to be able to keep them live across a function call Therefore it is better to use CCset all condition codes rather than ASTAT in the clobbered set above For more information refer to pragma regs_clobbered string on page 1 111 2 32 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Achieving Optimal Performance from C Source Code pragma optimize_ off for_speed for_space as_cmd_line The optimize_ pragma may be used to change the optimization setting on a function by function basis In particular it may be useful to optimize functions that are rarely called for example error handling code for space using pragma optimize_for_space whereas functions critical to performance should be compiled for maximum speed pragma optimize_for_speed The pragma optimize_off is usefu
103. Built in Functions on page 1 83 and Using the Compiler s Built In Functions on page 3 2 no defs The no defs disable defaults switch directs the preprocessor not to define any default preprocessor macros include directories library direc tories libraries or run time headers no extra keywords The no extra keywords disable short form keywords switch directs the compiler not to recognize the Analog Devices keyword extensions that might affect conformance to ISO ANSI standards for the C language These extensions include keywords such as asm which may be used as identifiers in conforming programs Alternate keywords that are prefixed with two leading underscores such as __pm and __dm continue to work The extra keywords switch on page 1 22 can be used to explicitly request support for the additional keywords 1 30 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler no fp associative The no fp associative switch directs the compiler not to treat floating point multiplication and addition as associative no mem The no mem switch causes the compiler to not invoke the Memory Initial izer tool after linking the executable This is the default setting See also mem on page 1 29 no std ass The no std ass disable standard assertions switch prevents the com piler from defining the system machine cpu and compiler assertions and from defining system specific
104. CALL instruction In the called function the address can then be popped from the hardware stack and saved as part of the stack frame This information is used by the debugger to generate call stack debug information for source level debugging Saving the return address on the stack frame is also useful in avoiding overflowing the finite hardware call stack for example when using recursion The value VisualDSP 3 5 C Compiler and Library Manual 1 137 for ADSP 218x DSPs C Run Time Model and Environment stored on the stack gets pushed back on the hardware call stack before the function returns The compiler detects recursive routines Local Variables and Temporaries Space for a register save area and local variables temporaries is allo cated on the stack by the function prologue Local variables and temporaries are typically placed first in this area so they can be addressed with the smallest offsets from FP The register save area is located at the farthest end of this area and can be accessed by SP relative addressing Outgoing Arguments Outgoing arguments are located at the top of the stack prior to the call Space may be pre allocated or claimed at the time of each call Free Space Space below SP is considered free and unprotected it is available for use in growing the stack at any time synchronously or asyn chronously the latter for interrupt handling This space should never be used on the ADSP 218x DSPs Gene
105. DSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 3 105 C Run Time Library Reference memset set range of memory to a character Synopsis include lt string h gt void memset void sl int c size_t n Description The memset function sets a range of memory to the input character c The first n characters of s1 are set to c The memset function returns a pointer to s1 Error Conditions The memset function does not return an error condition Example include lt string h gt char stringl1 50 memset stringl 0 50 set stringl to 0 See Also memcpy 3 106 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library modf separate integral and fractional parts Synopsis d Finclude lt math h gt double modf double f double fraction float modff float f float fraction Description The modf function separates the first argument into integral and fractional portions The fractional portion is returned and the integral portion is stored in the object pointed to by the second argument The integral and fractional portions have the same sign as the input Error Conditions The modf function does not return an error condition Example d Finclude lt math h gt double y n y modf 12 345 amp n fx y 0 345 ne a12 0 See Also frexp VisualDSP 3 5 C Compiler and Library Manual 3 107 for ADSP 218x DSPs C Run Time Lib
106. ONTENTS demean buler srssssnsrais oron 3 46 GEO ES raar E 3 48 e oa R A 3 49 enable tA sekan RAN 3 50 a E E EE E E E E E E SN 3 51 A E E E E E 3 52 le Ser E E E E E E E E E E 3 53 N ar EEEE EEE eE 3 54 De aa A E er en 3 57 PUI E E E EE E E E AE N O E E E ET 3 59 DOUG E E A E A A E T A A E E E 3 60 TES odena eee 3 61 TE a E O E ones 3 62 I s S 3 63 NEE E PEE E E EE TE AE E E A A E 3 66 MONUI rare RA A 3 71 lo space Pea isnot accssniesiniswinaabineisaansiberaacantarbiniaued ceaatineiannanenaas 3 7 5 MO SACOG ARE E E 3 77 O aae apeleneeane eee ae 3 79 PII E A A PAIE AA AA AE AET EA A E 3 80 E T E PEEN N ONE E TANIA AEA EE ITE EERTE AE 3 81 T A EE A NEEE EE E EE E EEE AE E E 3 82 PAOD ccobeninonrubia iaraa ke nake 3 83 DDT spa a A 3 84 xix VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs CONTENTS BIONET in ais N ee eee 3 86 MGA ai E S E A E E ei A E O 3 87 TEE S AO E 3 89 RPO aane r ECE eer 3 90 E T A E E E A 3 91 TOAD ET peseorarisrair en errero nir EErEE O REEERE 3 92 PG paaie e 3 93 E I o EEE EE ANEA E E E E A A A E 3 94 RI e E A 3 95 I E E E EEE E EEE E E War EE NE E E 3 96 e a E E E E E E E A E N 3 97 lop IO e ene icine aimee 3 98 long WRI N dia tandenediuneneis tases 3 99 Sa E E E A E ET NE EO 3 101 TE E i ATAN 3 102 A RA 3 103 HEMET acne cantiileaacisw sane oienatnraaestnieiatanniadtaienioiatinniaunies 3 104 TRIOS ara amin eum at 3 105 WONG ccs ieee eee eee 3 106 HOLP derese 3 107 PON E E AEE
107. P 3 5 C Compiler and Library Manual 1 83 for ADSP 218x DSPs C Compiler Language Extensions Built in functions have names which begin with __builtin_ Note that identifiers beginning with double underlines __ are reserved by the C standard so these names will not conflict with user program identifiers The header files also define more readable names for the built in functions without the __builtin_ prefix These additional names are disabled if the no builtin option is used The cc218x compiler provides built in versions of some of the C library functions as described in Using the Compiler s Built In Functions on page 3 2 The sysreg h header file defines a set of functions that provide efficient system access to registers modes and addresses not normally accessible from C source These functions are specific to individual architectures and this section lists the built in functions supported at this time on ADSP 218x DSPs The compiler supports e I O Space for Read Write on page 1 84 e Read Write of Non Memory Mapped Registers on page 1 85 e Interrupt Control on page 1 85 I O Space for Read Write The inclusion of sysreg h allows the use of built in functions that gener ate efficient inline instructions to implement read and write of values from and to I O space addresses The prototypes for these functions are as defined in sysreg h void io0_space_write const unsigned int addr const int value
108. RRO sanada RA N ener eee Meee nec eee ffts h Fast Fourier Transforms sciscsccscuccactasiasecesaneeusnactxenecees Hrs h DSP FEES eornianteai nne Hoath Flpaune Pont sccnchenicsuneceneereneiieinis fract h ADSP 218x DSP Macro Fract Definitions AE eee 3 10 spotth ADS 21 8x DSP Serial Ports siccvscssccescensesencescrzess 3 11 I EA E E E IEE E EE tomar 3 11 siai eina ASA 3 11 RM aipeanna 3 12 CHG E i a 3 12 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs xvii CONTENTS OEE D sti E E E 3 13 Documented Library FUNCHQRS scatinsrssnascininsorrsnscommniacanmnoieasss 3 14 C Run Time Library Reference seieren niiina 3 18 Notaren Cony nion oeaan A 3 18 Reference Format siicidncancitcan aminanuaadous 3 18 ADOTE sonein E E O 3 19 E E E E ae eee 3 20 NED E E A E A E E ANA A E EE 3 21 21 EEEE EO E E E A A A EAE E E A EEE E 3 22 1s E E OE E AE L S EA E A E E ora OR T TnVER ETS 3 23 EE E E EEE E E E A 3 24 E T E dee E eee 3 25 MOL pora 3 26 1 EE E E E ATN E E E erate 3 29 S E E AE E EE EE One E E E E EE E E RrIe 3 30 E EEE E A E EET O A E AE A A AE 3 31 a E E E E E A E A V oer arr en 3 34 calle ceccar ee ioe 3 36 e E E E N E E eee eee 3 37 plear mera orras EOE 3 38 A ETE E E EEA ernie 3 40 OE EEE RUPEE A E A A LOVED RT ene AS 3 41 COE ihc inci E ican brie ea cileahi N E A E T 3 44 E E cache ain pane ease nee aa oem 3 45 xviii VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C
109. SP 218x DSPs INDEX _primIO C function 3 12 A A assert compiler switch 1 18 abend see abort function abort abnormal program end function 3 19 abs absolute value function 3 20 acos arc cosine function 3 21 acos_frl6 function 3 21 activation record 1 136 ageregate initializers 1 80 aggregate assignment support compiler 1 82 aggregate constructor expression support 1 82 alias avoiding 2 10 align num pragma 1 101 alignment inquiry keyword 1 123 allocate memory see calloc free malloc realloc functions alphanumeric character test see isalnum function alter x macro 1 153 altregisters pragma 1 103 alttok alternative tokens compiler switch 1 19 ANSI C extensions A 4 ANSI standard compiler 1 22 arc tangent 3 23 array indexed 2 12 initializer 1 80 length 1 79 zero length 1 121 array search binary see bsearch function ASCII string see atof atoi atol functions asin arc sine function 3 22 asin_fr16 function 3 22 asm compiler keyword 1 53 keyword 1 56 1 123 statements 2 14 line breaks in 1 121 asm compiler keyword see inline assembly language support keyword asm asm constructs 1 57 flow control constructs 1 70 operand constraints 1 64 asm construct reordering 1 68 asm_sprt h mixed C assembly support 1 152 assembler 1 2 assembly constructs 1 57 language subroutines 1 148 assert h header file 3 6 assignments 1 73 atan arc tangent function 3 23 at
110. Standard C struct amp cc218x C Constructor struct Standard C struct truct foo int a char b 2 truct foo make_foo int x char s emp a X emp b 0 s 0 if s 0 0 temp b 1 s 1 else temp b 1 0 return temp S S struct foo temp t t i 1 82 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Equivalent cc218x C constructor struct struct foo make_foo int x char s return struct foo x s 0 s 0 s 1 O Preprocessor Generated Warnings The preprocessor directive warning causes the preprocessor to generate a warning and continue preprocessing The text on the remainder of the line that follows warning is used as the warning message C Style Comments The compiler accepts C style comments beginning with and ending at the end of the line in C programs This is essentially compatible with standard C except for the following case a b highly unusual c which a standard C compiler processes as a b c Compiler Built in Functions The compiler supports intrinsic functions that enable efficient use of hardware resources Knowledge of these functions is built into the cc218x compiler Your program uses them via normal function call syntax The compiler notices the invocation and generates one or more machine instructions just as it does for normal operators such as and VisualDS
111. Support You can reach DSP Tools Support in the following ways e Visit the DSP Development Tools website at www analog com technology dsp developmentTools index html e Email questions to dsptools support analog com e Phone questions to 1 800 ANALOGD e Contact your ADI local sales office or authorized distributor e Send questions by mail to Analog Devices Inc One Technology Way P O Box 9106 Norwood MA 02062 9106 USA Supported Processors The name ADSP 218x refers to a family of Analog Devices 16 bit fixed point processors VisualDSP currently supports the following ADSP 218x processors ADSP 2181 ADSP 2183 ADSP 2184 ADSP 2185 ADSP 2186 ADSP 2187 ADSP 2188 and ADSP 2189M VisualDSP 3 5 C Compiler and Library Manual xxvii for ADSP 218x DSPs Product Information Product Information You can obtain product information from the Analog Devices website from the product CD ROM or from the printed publications manuals Analog Devices is online at www analog com Our website provides infor mation about a broad range of products analog integrated circuits amplifiers converters and digital signal processors MyAnalog com MyAnalog com is a free feature of the Analog Devices website that allows customization of a webpage to display only the latest information on products you are interested in You can also choose to receive weekly email notification containing updates to the webpages that meet your
112. The cc218x compiler makes use of the DSP s double word long MAC instruction results to avoid having to explicitly promote inte ger operand multiplication to long If the integer multiplication result overflows the integer type then the result is not truncated as would be the case in strict ANSI terms This behavior is disabled using the no widen muls switch on page 1 32 Normal ANSI C external linkage does not specifically require stan dard include files to be used although it is recommended In many cases Analog C compilers do require standard include files to be used as build configurations Instead optimizations are used to select the correct and optimal implementation of C library func tions For example the include files may redefine standard C functions to use optimal compiler built in implementations The compilers also support a number of language extensions that are essentially aids to DSP programmers and would not be defined in strict ANSI conforming implementations These extensions are usually enabled by default and in some cases can be disabled using a command line switch if required These extensions include Inline function which directs the compiler to integrate the func tion code into the code of the callers Disabled if the 0 switches described on page 1 32 are not used Dual memory support keywords pm dm Disabled using the no extra keywords compiler switch on page 1 30 Placement suppor
113. The decimal digits can be followed by an exponent which consists of an introductory letter e or E and an optionally signed integer If neither an exponent part nor a decimal point appears a decimal point is assumed to follow the last digit in the string The form of a hexadecimal floating point number is sign 0x 0X hexdigs L hexdigs p P sign digits 3 140 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library A hexadecimal floating point number may start with an optional plus or minus followed by the hexadecimal prefix 0x or 0X This character sequence must be followed by one or more hexadecimal characters that optionally contain a decimal point The hexadecimal digits are followed by a binary exponent that consists of the letter p or P an optional sign and a non empty sequence of decimal digits The exponent is interpreted as a power of two that is used to scale the fraction represented by the tokens hexdigs hexdigs The first character that does not fit either form of number will stop the scan If endptr is not NULL a pointer to the character that stopped the scan is stored at the location pointed to by endptr If no conversion can be performed the value of nptr is stored at the location pointed to by endptr Error Conditions The strtod function returns a zero if no conversion can be made and a pointer to the invalid string is stored in the object po
114. The value in x is truncated to an integer prior to calculating the absolute value then reconverted to floating point for the assign ment to y misc h ADSP 218x DSP Timer Functions The misc h header file includes processor specific timer functions of the C library such as timer_set timer_on and timer_off setjmp h The setjmp h header file contains set jmp and longjmp for non local jumps signal h The signal h header file provides function prototypes for the standard ANSI signal h routines and also for several ADSP 218x DSP extensions such as interrupt and clear_interrupt The signal handling functions process conditions hardware signals that can occur during program execution They determine the way that your C program responds to these signals The functions are designed to process such signals as external interrupts and timer interrupts 3 10 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library sport h ADSP 218x DSP Serial Ports The sport h header file contains macros and subroutines to support the serial ports of the ADSP 218x DSPs stdarg h The stdarg h header file contains definitions needed for functions that accept a variable number of arguments Programs that call such functions must include a prototype for the functions referenced stdio h The stdio h header file defines a set of functions macros and data types for performing input and output Applic
115. _out int im_out int fft128 int rl_in int im_in int rl_outLl int out int fft64 int rl_in int imini int rl_outLl int _out int fft32 int rl_in int im_in int rl_outLl int _out int fftl6 int rl_in int im_in int rl_out int _out 3 54 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library int fft8 int rl_in int im_in int rl_outl int im_out Description These functions are Analog Devices extensions to the ANSI standard Each of these eight fftN functions computes the N point radix 2 Fast Fourier transform FFT of its integer input where N is 8 16 32 64 128 256 512 or 1024 There are eight distinct functions in this set They all perform the same function with the same type and number of arguments The only differ ence between them is the size of the arrays on which they operate To call a particular function substitute the number of points for N for example fft8 r_inp i_inp r_outp i_outp not fftN r_inp i_inp r_outp i_outp The input to fftN are two integer array of N points The array rl_in con tains the real components of the complex signal and the array im_in contains the imaginary components If there are fewer than N actual data points you must pad the array with zeros to make N samples Better results occur with less zero padding however The input data should be windowed if necessary before calling t
116. a pointer declaration as referring to data memory For more information see Dual Memory Support Keywords pm dm on page 1 71 VisualDSP 3 5 C Compiler and Library Manual 1 53 for ADSP 218x DSPs C Compiler Language Extensions Table 1 5 Keyword Extensions Cont d Keyword extensions Description pm Specifies the location of a static or global variable or qualifies a pointer declaration as referring to program memory For more information see Dual Memory Support Keywords pm dm on page 1 71 section string Specifies the section in which an object or function is placed For more information see Placement Support Keyword section on page 1 76 bool true false A Boolean type For more information see Boolean Type Support Keywords bool true false on page 1 77 restrict keyword Specifies restricted pointer features For more information see Pointer Class Support Keyword restrict on page 1 77 Table 1 6 Operational Extensions Operation extensions Description Variable length arrays Support for variable length arrays lets you use automatic arrays whose length is not known until runtime For more information see Variable Length Array Support on page 1 78 Non constant initializers Support for non constant initializers lets you use non constants as elements of aggregate initializers for au
117. a zero if no conversion can be made Example include lt stdlib h gt int i i atoi 5 i 5 See Also atof atol strtod strtol strtoul VisualDSP 3 5 C Compiler and Library Manual 3 29 for ADSP 218x DSPs C Run Time Library Reference atol convert string to long integer Synopsis include lt stdlib h gt long atol const char nptr Description The atol function converts a character string to a long integer value The character string to be converted is pointed to by the input pointer nptr The function clears any leading characters for which isspace would return true Conversion begins at the first digit with an optional preceding sign and terminates at the first non digit There is no way to determine if a zero is a valid result or an indica tor of an invalid string Error Conditions The atol function returns a zero if no conversion can be made Example d Finclude lt stdlib h gt long int i i atol 5 i 5 See Also atof atoi strtod strtol strtoul 3 30 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library biquad biquad filter section Synopsis d include lt filters h gt int biquad int sample int pm coeffs int dm state int sections Description This function is an Analog Devices extension to the ANSI standard The biquad function implements a biquad filter The function produces the filtered response of its
118. ader files that are enclosed in double quotes This switch removes the directory containing the current input file from the include directory list I directory directory The I directory include search directory switch directs the C prepro cessor to append the directory directories to the search path for include files This option may be specified more than once all specified directories are added to the search path include filename The include filename include file switch directs the preprocessor to process the specified file before processing the regular input file Any D and U options on the command line are always processed before an include file VisualDSP 3 5 C Compiler and Library Manual 1 25 for ADSP 218x DSPs Compiler Command Line Reference Include files whose names are not absolute path names and that are enclosed in when included will be searched for in the following directories in this order 1 The directory containing the current input file the primary source file or the file containing the finclude 2 Any directories specified with the I switch in the order they are listed on the command line 3 Any directories on the standard list lt VisualDSP install dir gt include If a file is included using the lt gt form this file will only be searched for by using directories defined in items 2 and 3 above ipa The ipa interprocedural analysis
119. age Extensions on page 1 52 Describes the cc218x compiler s extensions to the ISO ANSI stan dard for the C language Preprocessor Features on page 1 125 Contains information on the preprocessor and ways to modify source compilation C Run Time Model and Environment on page 1 132 Contains reference information about implementation of C pro grams data and function calls in ADSP 218x DSPs C and Assembly Language Interface on page 1 148 Describes how to call an assembly language subroutine from C pro gram and how to call a C function from within an assembly language program VisualDSP 3 5 C Compiler and Library Manual 1 1 for ADSP 218x DSPs C Compiler Overview C Compiler Overview The C compiler cc218x is designed to aid your DSP project develop ment efforts by e Processing C source files producing machine level versions of the source code and object files e Providing relocatable code and debugging information within the object files e Providing relocatable data and program memory segments for placement by the linker in the processors memory Using C developers can significantly decrease time to market since it gives them the ability to efficiently work with complex signal processing data types It also allows them to take advantage of specialized DSP opera tions without having to understand the underlying DSP architecture The C compiler cc218x compiles ISO ANSI standard C code for
120. agmas see Pragmas on page 1 99 1 124 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Preprocessor Features The cc218x compiler provides standard preprocessor functionality as described in any C text The following extensions to standard C are also supported end of line C style comments d warning directive For more information about these extensions refer to Preprocessor Gen erated Warnings on page 1 83 and C Style Comments on page 1 83 This section contains e Predefined Preprocessor Macros on page 1 125 e Header Files on page 1 128 e Writing Preprocessor Macros on page 1 129 e Preprocessing of IDL Files on page 1 131 Predefined Preprocessor Macros The cc218x compiler defines a number of macros to produce information about the compiler source file and options specified These macros can be tested using the ifdef and related directives to support your pro gram s needs Similar tailoring is done in the system header files Macros such as __DATE__ can be useful to incorporate in text strings The operator with a macro body is useful in converting such symbols into text constructs The predefined preprocessor macros are VisualDSP 3 5 C Compiler and Library Manual 1 125 for ADSP 218x DSPs Preprocessor Features ADSP21XX__ and _ ADSP218X__ cc218x always defines __ADSP21XX__ and __ADSP218X__as 1 ADSP21 81
121. an a 3 164 E TE T E E T A anaes 3 165 DAF E ENON AA O P TA S 3 168 E ENE PEN octal O N NT A A EN T 3 169 COMPILER LEGACY SUPPORT Tools ieee es A 1 C Compiler and C Run Time Library sccctssesctacrecerrstacornssiiiae A 3 Segment Placement Support Keyword Changed to Section A 3 Gol Cai er A 3 Support for G21 Based Options and Extensions 1 0 A 3 ieee Ta ciccereien cca nemenuacaneeenamenemaneemaniens A 4 Compiler Dapnostie crni sian A 4 xxii VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs ANSI G Extensions ccccpsccicovanntoucendetandinrabeadennerandennisweeenoereves A 4 Compiler Swich Wlodilcatioiis srrsncaroranraa A 5 Wes EET E E E E E E A 7 Rum Time Model sarunen A 8 INDEX VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs xxiii xxiv VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs PREFACE Thank you for purchasing Analog Devices development software for digi tal signal processors DSPs Purpose The VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs contains information about the C compiler and run time library for ADSP 218x DSPs It includes syntax for command lines switches and language extensions It leads you through the process of using library rou tines and writing mixed C assembly code Intended Audience The primary audience for this manual is programmers who are familiar with Analog Devices DSPs This manual assumes that the audience
122. an_buffer returns the mean of the current buffer as a result This value should be passed as a parameter to the function on the next call the first call to demean_buffer should have a 0 for the 01d_mean value Error Conditions The demean_buffer function does not return an error condition Example include lt filters h define BUFSIZE 1024 int data_buffer BUFSIZE int data_mean 0 The buffer is filled with data possibly from a converter Remove the mean from the buffer with this demean function data_demean demean_buffer data_buffer data_mean BUFSIZE or as in this example a 3 46 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library int i temp_mean temp_mean 0 for i 0 i lt BUFSIZE i temp_mean data_bufferli temp_mean BUFSIZE for i 0 i lt BUFSIZE i data_buffer i temp_mean See Also No references to this function VisualDSP 3 5 C Compiler and Library Manual 3 47 for ADSP 218x DSPs C Run Time Library Reference disable_interrupts disable interrupts Synopsis include lt sysreg h gt void disable_interrupts void Description The disable_interrupts function causes the compiler to emit an instruc tion to disable hardware interrupts This function is implemented as a compiler built in the emitted instruc tion will be inline at the point of disable_interrupts use The inclusion of the sys
123. an_fr16 function 3 23 1 2 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs atan2 arc tangent of quotient function 3 24 atan2_fr16 function 3 24 atexit select exit function function 3 25 atof convert string to double function 3 26 atoi convert string to integer function 3 29 atol convert string to long integer function 3 30 attributes functions variables and types 1 124 autobuffering 1 38 1 134 automatic inlining 1 33 1 50 2 13 loop control 2 21 variables 1 71 B base 10 logarithm 3 98 binary array search see bsearch function biquad biquad filter function 3 31 bitfields signed 1 40 unsigned 1 42 bit reversal sorting algorithm 1 101 bool see Boolean type support keywords bool true false boolean type support keywords 1 77 Boolean type support keywords bool true false 1 53 INDEX bsearch binary search in sorted array function 3 34 bss compiler switch 1 19 build lib build library compiler switch 1 20 built in functions 1 83 1 84 system 2 25 C C comments compiler switch 1 20 c compile only compiler switch 1 20 C function _primIO 3 12 C language extensions 1 53 aggregate assignments 1 82 asm keyword 1 56 bool keyword 1 77 C style comments 1 54 compound statements 1 79 false keyword 1 53 indexed initializers 1 81 inline keyword 1 55 non constant initializers 1 80 segment keyword 1 53 true keyword 1 53 C run time environment see also C Run time li
124. and Utilities Manual for 16 Bit Processors VisualDSP 3 5 Loader Manual for 16 Bit Processors VisualDSP 3 5 Product Bulletin 16 Bit Processors VisualDSP Kernel VDK User s Guide VisualDSP Component Software Engineering User s Guide Quick Installation Reference Card For hardware information refer to the processor s Hardware Reference Manual and Instruction Set Reference Manual VisualDSP 3 5 C Compiler and Library Manual Xxix for ADSP 218x DSPs Product Information Online Technical Documentation Online documentation comprises VisualDSP Help system and tools manuals and FlexLM network license manager software documentation You can easily search across the entire VisualDSP documentation set for any topic of interest For easy printing supplementary PDF files for the tools manuals are also provided If documentation is not installed on your system as part of the software installation you can add it from the VisualDSP CD ROM at any time Access the online documentation from the VisualDSP environment Windows Explorer or Analog Devices website A description of each documentation file type is as follows File Description CHM Help system files and VisualDSP tools manuals HTM or HTML FlexLM network license manager software documentation Viewing and printing the HTML files require a browser such as Internet Explorer 4 0 or higher PDF VisualDSP tools manuals in Portable Docum
125. and addition as associa tive full version on page 1 23 Displays version information for build tools g on page 1 23 Generates DWARF 2 debug information H on page 1 24 Outputs a list of header files but does not compile VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Table 1 2 Compiler Command Line Switches Contd Switch Name Description HH on page 1 24 Outputs a list of included header files and compiles h elp on page 1 24 Outputs a list of command line switches A I 7 on page 1 25 I directory on page 1 25 on page 1 25 Establishes the point in the include directory list at which the search for header files enclosed in angle brackets should begin Appends the specified search directory to the standard search path Only output header details or makefile dependencies for include files specified in double quotes include filename on page 1 25 Includes named file prior to processing each source file ipa on page 1 26 Specifies that interprocedural analysis should be performed for optimization between translation units jump dm pm same on page 1 26 Specifies that the compiler should place jump tables in data memory program memory or the same memory section as the function to which it applies L directory on page 1 27 T library on page 1 27 Append
126. andard macro definitions 1 31 no std inc disable standard include search 1 31 no std lib disable standard library search 1 32 no widen muls disable widening multiplications 1 32 O enable optimizations 1 32 o output file 1 33 Oa automatic function inlining 1 33 Os optimize for size 1 33 Ov optimize for speed vs size 1 33 P omit line numbers 1 34 path tool location 1 34 path install directory installation location 1 34 path output non temporary files location 1 35 path temp temporary files location 1 35 pch precompiled header 1 35 pchdir locate PCHRepository 1 35 pedantic ANSI standard warnings 1 35 pedantic errors ANSI C errors VisualDSP 3 5 C Compiler and Library Manual 1 5 for ADSP 218x DSPs INDEX 1 36 PP omit line numbers and run 1 34 pplist preprocessor listing 1 36 proc target processor 1 36 R add source directory 1 37 R disable source path 1 38 reserve reserve register 1 38 S stop after compilation 1 38 s strip debugging information 1 39 save temps save intermediate files 1 39 show display command line 1 39 signed bitfield make plain bitfields signed 1 40 signed char make char signed 1 40 si revision version silicon revision 1 39 syntax only just check syntax 1 40 sysdefs system definitions 1 41 T linker description file 1 41 time time the compiler 1 41 Umacro u
127. andards the compiler supports a set of C language extensions These extensions sup port hardware features of the ADSP 218x DSPs For information on these extensions see C Compiler Language Extensions on page 1 52 Compiler options are set in the VisualDSP Integrated Development and Debug Environment IDDE from the Compile page of the Project Options dialog box see Specifying Compiler Options in VisualDSP on page 1 10 The selections control how the compiler processes your source files letting you select features that include the language dialect error reporting and debugger output For more information on the VisualDSP environment see the VisualDSP 3 5 User s Guide for ADSP 21xx DSPs and online Help Standard Conformance Analog C compilers conform to the ISO IEC 998 1990 C standard with a small number of currently unsupported features or areas of divergence Unsupported features are e ANSI features that require operating system support are generally not supported This includes time h functionality in C e The cc218x compiler does not provide comprehensive support of NaN s overflow and underflow conditions in their compiler sup port floating point routines VisualDSP 3 5 C Compiler and Library Manual 1 3 for ADSP 218x DSPs C Compiler Overview Areas of divergence from Standard The double type is defined in terms of a single precision 32 bit floats not double precision 64 bit floats
128. ap an input operand constraint Indicates the constraint is temporary constraint Indicates the constraint is both an input and output operand 1 The use ofany letter not listed here results in unspecified behavior The compiler does not check the validity of the code by using the constraint letter Table 1 8 Register Names for asm Constructs Clobber String Meaning AX1 AXO AY1 AYO AR AF ALU registers MX1 MXO MY1 MYO MRI MRO MR2 MF MAC registers S SET SRE e SRO p NSBR SRZ SHIFTER registers SO I MAr a a POM ge ae DAG addressing registers MO M3 M5 Modifier registers TEO ALETA MEZ SM SEE Ya Eor SEZ Length register PX PMD DMD bus exchange regis ter astat ALU status registers MSTAT MMODE SSTAT Mode control registers TMASK LCNTL LEG Interrupt registers 1 66 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Table 1 8 Register Names for asm Constructs Cont d Clobber String Meaning CNTR TOPPCSTACK Program sequencer registers DMOVLAY PMOVLAY Overlay registers oc Condition code register memory Unspecified memory location s Assembly Constructs With Multiple Instructions There can be many assembly instructions in one template If the asm string is longer than one line you may continue it on the next line by placing a backs
129. ard architecture of the ADSP 218x processors There are two keywords used to designate memory space dm and pm They can be used to specify the location of a static or global variable or to qualify a pointer declaration These keywords allow you to control placement of data in primary dm or secondary pm data memory No data is placed in the memory unit that holds programs The following rules apply to dual memory support keywords A memory space keyword dm or pm refers to the expression to its right You can specify a memory space for each level of pointer This cor responds to one memory space for each in the declaration The compiler uses data memory as the default memory space for all variables All undeclared spaces for data are data memory spaces The compiler always uses program memory as the memory space for functions Function pointers always point to program memory You cannot assign memory spaces to automatic variables All auto matic variables reside on the stack which is always in data memory Literal character strings always reside in data memory Although program memory on the ADSP 218x DSPs consists of 24 bit words only 16 bits of each word are used when C data is stored in pm This is normally the case for assembly language pro gramming as well If you need special access to all 24 bits you should use an assembly language subroutine and work with the Px register VisualDSP 3 5 C Compiler and Li
130. are defined if the system returns information for them Macro Description HOSTNAME The name of the host machine __MACHINE__ The machine type of the host machine __SYSTEM__ The OS name of the host machine __USERNAME__ The current user s login name __GROUPNAME__ The current user s group name __REALNAME__ The current user s real name S __MACHINE__ __GROUPNAME__ and __ REALNAME__ are not available on Windows platforms T filename The T Linker Description File switch directs that the linker when invoked will use the specified Linker Description File LDF If T is not specified a default LDF file is selected based on the processor variant time The time time the compiler switch directs the compiler to display the elapsed time as part of the output information on each part of the compi lation process VisualDSP 3 5 C Compiler and Library Manual 1 41 for ADSP 218x DSPs Compiler Command Line Reference Umacro The U undefine macro switch lets you undefine macros If you specify a macro name it will be undefined The compiler processes all D define macro switches on the command line before any U undefine macro switches You can invoke this switch by selecting the Undefines field in the VisualDSP Project Options dialog box Compile tab Preprocessor category unsigned bitfield The unsigned bitfield make plain bitfields unsigned switch directs the compiler to make bitf
131. arks are enabled the compiler will produce a remark to indicate each function that is inlined Os The 0s optimize for size switch directs the compiler to produce code that is optimized for size This is achieved by performing all optimizations except those that increase code size The optimizations not performed include loop unrolling and jump avoidance It also uses a function to save and restore preserved registers for a function instead of generating the more cycle efficient inline default versions Ov num The Ov num optimize for speed versus size switch directs the compiler to produce code that is optimized for speed versus size The num should be an integer between 0 purely size and 100 purely speed o filename The o output file switch directs the compiler to use filename for the name of the final output file VisualDSP 3 5 C Compiler and Library Manual 1 33 for ADSP 218x DSPs Compiler Command Line Reference The P omit line numbers switch directs the compiler to stop after the C preprocessor runs without compiling and to omit the 1 ine preprocessor directives with line number information in the output from the prepro cessor The C switch can be used in conjunction with P to retain comments PP The PP omit line numbers and compile switch is similar to the P switch however it does not halt compilation after preprocessing path asm compiler def lib link mem filename T
132. as is that they allow code to remain por table since they will normally be ignored by a compiler that does not recognize them Function Pragmas Function pragmas include i fpragma const pragma pure pragma alloc pragma regs_clobbered and pragma optimize_ off for_speed for_space pragma const The pragma const pragma asserts to the compiler that a function does not have any side effects such as modifying global variables or data buffers and the result returned is only a function of the parameter values The pragma may be applied to a function prototype or definition It helps the compiler since two calls to the function with identical parameters will always yield the same result In this way calls to pragma const functions may be hoisted out of loops if their parameters are loop independent VisualDSP 3 5 C Compiler and Library Manual 2 29 for ADSP 218x DSPs Pragmas pragma pure Like pragma const this pragma asserts to the compiler that a function does not have any side effects such as modifying global variables or data buffers However the result returned may be a function of both the parameter values and any global variables The pragma may be applied to a function prototype or definition Two calls to the function with identical parameters will always yield the same result provided that no global vari ables have been modified between the calls Hence calls to pragma pure functions may be hoisted out of l
133. as part of the various compilation stages These intermediate files are placed in the path output specified output directory or the build directory if the path output switch on page 1 35 is not used See Table 1 1 on page 1 9 for a list of input output files file extensions show The show display command line switch directs the compiler to echo all command line arguments expanded option files switches and environ ment variables used by the compiler si revision version The si revision version silicon revision switch sets the version of the hardware which is the required target for the build It is used to enable inherent behavior relating to any errata in specific silicon revisions The revision can be specified as none or a number of the form described by regular expression 0 9 0 9 1 3 for example 1 123 The com piler defines a macro __SILICON_REVISION__ to a value specific to each silicon revision For unknown revisions the compiler will generate a warning and default to the latest known revision The parameter version represents a silicon revision of the processor specified by the proc switch on page 1 36 The none revision disables support for silicon errata VisualDSP 3 5 C Compiler and Library Manual 1 39 for ADSP 218x DSPs Compiler Command Line Reference For example cc218x proc ADSP 2189 si revision 0 1 In the absence of silicon revision the compiler selects the great
134. asting a value of one of the unions member s types Ranges in Case Labels A consecutive range of values can be specified in a single case by separat ing the first and last values of the range with For example case 200 300 Declarations mixed with Code In C mode the compiler will accept declarations in the middle of code as in C99 and C This allows the declaration of local variables to be placed at the point where they are required Therefore the declaration can be combined with initialization of the variable For example in the following function void func Key k Node p list while p amp amp p gt key k p p gt next if lp return Data d p gt data while d process d 1 122 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler the declaration of d is delayed until its initial value is available so that no variable is uninitialized at any point in the function Escape Character Constant The character escape e may be used in character and string literals and maps to the ASCII Escape code 27 Alignment Inquiry Keyword __alignof__ The __alignof__ type name construct evaluates to the alignment required for an object of a type The __alignof__ expression construct can also be used to give the alignment required for an object of the expression type If expression is an 1value may appear on the left hand side of an assign ment
135. ate file The filename is the name of the function with the appro priate extension for C or assembler source If you do not intend to modify any of the run time library functions and are not interested in using the source for reference you can delete this directory and its contents to con serve disk space The source code is provided so you can customize specific functions for your own needs To modify these files you need proficiency in ADSP 218x DSP assembly language and an understanding of the run time environment as explained in C Run Time Model and Environ 3 4 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library ment on page 1 132 Before you make any modifications to the source code copy the source code to a file with a different filename and rename the function itself Test the function before you use it in your system to verify that it is functionally correct Analog Devices only supports the run time library functions as provided Working with Library Header Files When you use a library function in your program you should also include the function s header with the include preprocessor command The header file for each function is identified in the Synopsis section of the function s reference page Header files contain function prototypes The compiler uses these prototypes to check that each function is called with the correct arguments A list of the header files that ar
136. atic 1 108 no_alias 1 105 no_pch 1 116 once 1 116 optimize_as_cmd_line 1 106 optimize_for_space 1 106 optimize_for_speed 1 106 optimize_off 1 106 pad alignopt 1 102 pure 1 110 regs_clobbered string 1 111 result_alignment 1 114 VisualDSP 3 5 C Compiler and Library Manual I 17 for ADSP 218x DSPs INDEX retain_name 1 107 system_header 1 116 vector_for 1 104 weak_entry 1 108 precompiled header 1 35 predefined macros 1 125 ___NO_LONG_LONG 1 127 __ADSP21 81 83 84 85 86 87 8 8 89 __ 1 126 __ADSP21XX__ __ADSP218X__ 1 126 __ANALOG_EXTENSIONS__ 1 126 DATE 1 126 __DOUBLES_ARE_FLOATS__ 1 126 __ECC__ 1 126 __EDG__ 1 126 __EDG_VERSION__ 1 127 __ FILE 1 127 __LINE_ 1 127 __NO_BUILTIN 1 127 __ SIGNED CHARS _ 1 127 _ STDC _ 1 128 __STDC_VERSION__ 1 128 __TIME _ 1 128 __ VERSION __ 1 128 _LANGUAGE C 1 127 prelinker 1 51 preprocessing IDL files 1 131 program 1 125 preprocessor features 1 125 macros 1 125 preprocessor macros 1 125 primitive I O functions 3 11 printable character test see isprint function printf function 3 165 flushing output 3 12 proc target processor compiler switch 1 36 procedural optimizations optimization procedural 1 49 procedure call 1 139 1 140 procedure call return 1 139 1 140 profile guided optimization 2 28 program control functions calloc 3 36 malloc 3 101 realloc 3 114 punctuation character test ispunct function 3 90 putsfirst macro 1 154 putsnext macro 1 155 PX r
137. ations that use the facilities of this header file should link with the I O library 1ibio d1b in the same way as linking with the C run time library 1ibc d1b The library is not inter rupt safe and should not therefore be called either directly or indirectly from an interrupt service routine The implementation of the stdio h routines is based on a simple interface with a device driver that provides a set of low level primitives for open close read write and seek operations By default these operations are provided by the VisualDSP simulator and EZ kits However alterna tive device drivers may be registered see Extending I O Support To New Devices on page 1 141 that can then be used through the stdio h functions The following restrictions apply to this software release e Functions tmpfile and tmpnam are not available e Functions rename and remove are only supported under the default device driver supplied by the VisualDSP simulator and EZ kits and they only operate on the host file system VisualDSP 3 5 C Compiler and Library Manual 3 11 for ADSP 218x DSPs C Run Time Library Guide e Positioning within a file that has been opened as a text stream is only supported if the lines within the file are terminated by the character sequence r n When using the default device driver all I O operations are channeled through the C function _prim10 The assembly label has two under scores __priml0 The _prim
138. be com pletely consecutive it may be moved across jump instructions or in other ways that are not significant to the compiler To force the compiler to keep the output consecutive use only one asm volatile construct or use the output of the asm construct in a C statement Assembly Constructs with Input and Output Operands The output operands must be write only cc218x assumes that the values in these operands do not need to be preserved When the assembler instruction has an operand that is both read from and written to you must logically split its function into two separate operands one input operand and one write only output operand The connection between them is expressed by constraints that say they need to be in the same loca tion when the instruction executes You can use the same C expression for both operands or different expres sions For example in the following statement the modi fy instruction uses sock as its read only source operand and shoe as its read write destination pseudo code modify shoe sock asm modify 0 2 w shoe 0 shoe x sock 1 68 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler The constraint 0 for operand 1 says that it must occupy the same loca tion as operand 0 A digit in an operand constraint is allowed only in an input operand and it must refer to an output operand Only a digit in the constraint can guarantee that one opera
139. brary C run time library 3 2 C assembly interface see mixed C assembly programming calling assembly language subroutine VisualDSP 3 5 C Compiler and Library Manual 1 3 for ADSP 218x DSPs INDEX 1 148 C library functions 3 2 calloc allocate and initialize memory function 3 36 ceil ceiling function 3 37 character string search see strchr function character string search recursive see strrchr function circular boundary array declaring 1 101 circular buffer length registers 1 144 clear_interrupt clear a pending signal function 3 38 clobber 1 59 clobber string specifiers 1 64 clobbered register set 1 112 1 113 clobbered registers 1 59 1 111 1 112 close operation 3 11 command line interface 1 6 compatibility call 1 157 compiler C extensions 1 53 code optimization 1 49 2 3 command line syntax 1 7 diagnostics output A 4 file extensions 1 9 input output files 1 9 intrinsic functions 1 83 legacy support A 1 A 9 obsolete modified switches A 5 optimization disabling 1 32 optimization enabling 1 32 optimizer 2 4 overview 1 2 reference 1 132 running 1 7 selecting options 1 3 1 10 compiler command line switches filename command file 1 18 A assert 1 18 alttok alternative tokens 1 19 bss 1 19 build lib build library 1 20 C comments 1 20 c compile only 1 20 const read write 1 20 debug types 1 21 default linkage assembler linkage 1 21 Dmacro define macro 1
140. brary Manual for ADSP 218x DSPs C Run Time Library isnan test for not a number NAN Synopsis d Finclude lt math h gt int isnanf float x int isnan double x Description The isnan function returns a zero if the argument is not set to an IEEE NaN Not a Number otherwise the function will return a non zero value Error Conditions The isnan function does not return or set any error conditions Example d Finclude lt stdio h gt d Finclude lt math h gt static int fail 0 main test int isnan double union double d float f unsigned long 1 u ifdef _ DOUBLES _ARE_FLOATS u l OxFF800000L if isnan u d 0 failt u l OxFF800001L if isnan u d 0 failt u l Ox7F800000L if isnan u d 0 failt u 1 0x7F800001L if isnan u d 0 failt dFendif VisualDSP 3 5 C Compiler and Library Manual 3 87 for ADSP 218x DSPs C Run Time Library Reference test int isnanf float u 1 OxFF800000L if isnanf u f 0 fail u 1 OxFF800001L if isnanf u f 0 failt u 1 0x7F800000L if isnanf u f 0 failt u 1 Ox7F800001L if isnanf u f 0 fail print pass fail message if fail printf Test passed n else printf Test failed 4d n fail See Also isinf 3 88 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library isprint detect printable character Synopsis inc
141. brary Manual 1 71 for ADSP 218x DSPs C Compiler Language Extensions The following listing shows examples of dual memory keyword syntax int pm abc 100 declares an array abc with 100 elements in program memory int dm def 100 declares an array def with 100 elements in data memory Kf int ghi 100 declares an array ghi with 100 elements in data memory int pm pm pp declares pp to be a pointer which resides in program memory and points to a program memory integer a int dm dm dd dec Memory int dd dec and poi ares dd to be a pointer which resides in primary Data and points to a data memory integer Ap ares dd to be a pointer which resides in data memory nts to a data memory integer Af int pm dm dp dec and poi ares dp to be a pointer which resides in data memory nts to a program memory integer xy int pm dp dec and poi ares dp to be a pointer which resides in data memory nts to a program memory integer my int dm pm pd dec ares pd to be a pointer which resides in pm secondary data memory and points to a data memory integer Xy int pm pd declares pd to be a pointer which resides in Program memory and points to a data memory integer Kj float pm dm pm fp the first pm means that fp is in program memory the following dm puts fp in data memory and fp itself is in program memory fs
142. called ay See Also disable_interrupts enable_interrupts io_space_read sysreg_read sysreg_write 3 78 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library isalnum detect alphanumeric character Synopsis include lt ctype h gt int isalnum int c Description The isalnum function determines if the argument is an alphanumeric character A Z a z or 0 9 If the argument is not alphanumeric isalnum returns a zero If the argument is alphanumeric isalnum returns a non zero value Error Conditions The isalnum function does not return any error conditions Example include lt ctype h gt int ch for ch 0 ch lt Ox7f ch printf 04x ch printf 3s isalnum ch alphanumeric putchar n See Also isalpha isdigit ae VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 3 79 C Run Time Library Reference isalpha detect alphabetic character Synopsis include lt ctype h gt int isalpha int c Description The isalpha function determines if the input is an alphabetic character A Z or a z If the input is not alphabetic isalpha returns a zero If the input is alphabetic isalpha returns a non zero value Error Conditions The isalpha function does not return any error conditions Example include lt ctype h gt int ch for ch 0 ch lt 0Ox7f ch printf O4x ch printf 2s isalpha
143. cases where the input is equal to 0x80000000 saturation occurs and 0x7fffffff is returned Long add fract32 L_add fract32 fract32 This function returns the 32 bit saturated result of the addition of the two input parameters Long add with carry fract32 L_add_c fract32 fract32 This function performs 32 bit addition of the two input parameters Uses the Carry flag as additional input when using the ETSI flag variables 16 bit variable gt most significant bits least significant bits zeroed fract32 L_deposit_h fract16 This function deposits the 16 bit parameter into the 16 most significant bits of the 32 bit result The least 16 bits are zeroed 16 bit variable gt least significant bits sign extended fract32 L_deposit_l fract16 This function deposits the 16 bit parameter into the 16 least significant bits of the 32 bit result The most significant bits are set to sign extension for the input Multiply and accumulate fract32 L_mac fract32 fractl6 fractl6 VisualDSP 3 5 C Compiler and Library Manual 1 95 for ADSP 218x DSPs C Compiler Language Extensions This function performs a fractional multiplication of the two 16 bit parameters and returns the saturated sum of the multiplication result with the 32 bit parameter Multiply and accumulate without saturation fract32 L_macNs fract32 fractl6 fractl6 This function performs a non saturating version of the L_mac operation Multiply both the most
144. ch alphabetic putchar n See Also isalnum isdigit 3 80 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library iscntrl detect control character Synopsis include lt ctype h gt int iscntri int c Description The iscntr1 function determines if the argument is a control character 0x00 Ox1F or 0x7F If the argument is not a control character iscntr1 returns a zero If the argument is a control character iscntr returns a non zero value Error Conditions The iscntr function does not return any error conditions Example include lt ctype h gt int ch for ch 0 ch lt Ox7f ch printf 04x ch printf 2s iscntrl ch control putchar n See Also isalnum isgraph VisualDSP 3 5 C Compiler and Library Manual 3 81 for ADSP 218x DSPs C Run Time Library Reference isdigit detect decimal digit Synopsis include lt ctype h gt int isdigit int c Description The isdigit function determines if the input character is a decimal digit 0 9 If the input is not a digit isdigit returns a zero If the input is a digit isdigit returns a non zero value Error Conditions The isdigit function does not return an error condition Example include lt ctype h gt int ch for ch 0 ch lt Ox7f cht printf 04x ch printf 2s isdigit ch digit putchar n See Also isalnum
145. char s va_list ap va_start ap sl s sl while s len strlen s S va_arg ap char va_end ap result malloc len 7 if result return result result va_start ap sl s sl while s strcat result s S va_arg ap char 3 166 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library va_end ap return result See Also va_end va_start VisualDSP 3 5 C Compiler and Library Manual 3 167 for ADSP 218x DSPs C Run Time Library Reference va_end finish variable length argument list processing Synopsis include lt stdarg h gt void va_end va_list ap Description The va_end macro can only be used after the va_start macro has been invoked A call to va_end concludes the processing of a variable length list of arguments that was begun by va_start Error Conditions The va_end macro does not return an error condition Example See va_arg on page 3 165 See Also va_arg va_start 3 168 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library va_start initialize the variable length argument list processing Synopsis d Finclude lt stdarg h gt void va_start va_list ap parmN Description The va_start macro is used in a function declared to take a variable num ber of arguments to start processing those variable arguments The first argument to va_start
146. claration this pragma acts as an assertion telling the compiler something it would not be able to discover for itself In the example fpragma regs_clobbered ar m5 void f void the compiler knows that only registers ar and m5 may be modified by the call to f so it may keep local variables in other registers across that call The regs_clobbered pragma may also be used with a function definition or a declaration preceding a definition when it acts as a command to the compiler to generate register saves and restores on entry and exit from the function to ensure it only modifies the registers in string For example fpragma regs_clobbered ar m5 int glint a return at3 The regs_clobbered pragma may not be used in conjunction with pragma interrupt If both are specified a warning is issued and the regs_clobbered pragma is ignored To obtain best results with the pragma it is best to restrict the clobbered set to be a subset of the default scratch registers The compiler is likely to produce more efficient code this way than if the scratch set is changed to use the same number of registers but which does not make a subset of the default volatile set usually scratch VisualDSP 3 5 C Compiler and Library Manual 1 111 for ADSP 218x DSPs C Compiler Language Extensions When considering when to apply the regs_clobbered pragma it may be useful to look at the output of the compiler to see how many scratch regis ters wer
147. clared with a non constant length This means that the space is allocated when the array is declared and deallocated when the brace level is exited The compiler does not allow jumping into the brace level of the array and produces a compile time error message if this is attempted The compiler does allow breaking or jumping out of the brace level and it deallocates the array when this occurs You can use variable length arrays as function arguments as shown in the following example struct entry var_array int array_len char dataLarray_len Larray_len 1 78 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler The compiler calculates the length of an array at the time of allocation It then remembers the array length until the brace level is exited and can return it as the result of the SIZEOF function performed on the array Because variable length arrays must be stored on the stack it is impossible to have variable length arrays in program memory pm The compiler issues an error if an attempt is made to use a variable length array in pm For example if you were to implement a routine for computation of a product of three matrices you need to allocate a temporary matrix of the same size as input matrices Declaring automatic variable size matrix is much easier then explicitly allocating it in a heap The expression declares an array with a size that is computed at run time The length of th
148. clude directive without compiling The o switch on page 1 33 may be used to specify the redi rection of the list to a file HH The HH list headers and compile switch directs the compiler to print to the standard output file stream a list of the files included by the preproces sor via the include directive After preprocessing compilation proceeds normally h elp The help command line help switch directs the compiler to output a list of command line switches with a brief syntax description 1 24 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler The 1 start include directory list switch establishes the point in the include directory list at which the search for header files enclosed in angle brackets should begin Normally for header files enclosed in double quotes the compiler searches in the directory containing the current input file then the compiler reverts back to looking in the directories specified with the 1 switch and then in the standard include directory For header files in angle brackets the compiler performs the latter two searches only It is possible to replace the initial search within the directory containing the current input file by placing the 1 switch at the point on the com mand line where the search for all types of header file should begin All include directories on the command line specified before the 1 switch will only be used in the search for he
149. copying the default 218x_int_tab asm file and LDF file into your project and modifying them as required An interrupt pragma defined function can be placed in the interrupt vec tor code directly or be jumped to from the vector if it does not fit in the interrupt vector space see Interrupt Handler Pragmas on page 1 102 The reset vector code which is placed at address zero 0 and does a jump to____system_start should not be replaced Autobuffering Support The cc218x compiler allows registers 12 13 15 17 and MO to be reserved from compiler use so that serial ports SPORTS can be configured to use autobuffering Registers are reserved using the reserve switch on page 1 38 This support makes it possible to to enable both SPORT for transmit and receive autobuffering 1 134 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler In addition to the compiler not using any reserved registers the run time libraries must do likewise The libraries normally avoid the use of registers 12 13 and MO by default Making the library code avoid registers 15 and 17 can add an extra complexity and in some cases introduces a performance penalty The aim is to avoid this penalty for applications that do not require autobuffering or these extra registers To this end autobuffering variants of the libraries are provided libcab d1b and libioab d1b which avoid 15 and 17 and will be used in place of the defaults T
150. ct now precedes the variable declaration and its argu ment is a string for example section my_sec int myvar For more information about the section construct see Placement Sup port Keyword section on page 1 76 G21 Compatibility Call The C compiler provides a special g21 compatibility call that enables use of existing libraries with the new compiler The extern 01dAsmCal1 decla ration can be added to the prototype s of the functions developed under Release 6 1 Your programs will be faster smaller and more reliable after the C code is upgraded to use the new compiler This convention is similar to the C linkage specification Support for G21 Based Options and Extensions The C compiler supports most of the switches and extensions of the previ ous GNU based compiler release For a list of absolute or modified options see Compiler Switch Modifications on page A 5 VisualDSP 3 5 C Compiler and Library Manual A 3 for ADSP 218x DSPs Tools Differences Indexed Initializers The syntax for indexed initializers may change in a future release This change may be incompatible with the existing syntax For more informa tion about indexed initializers see Indexed Initializer Support on page 1 80 Compiler Diagnostics Compiler diagnostics now go to stderr on the PC rather than to stdout ANSI C Extensions The following extensions are no longer supported e typeof This extension wa
151. ctype h The ctype h header file contains functions for character handling such as isalpha tolower and others 3 6 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library def2181 h Memory Map Definitions The def2181 h header file contains macros that define reserved memory addresses for a ADSP 2181 processor These memory addresses are used as system registers def2181x h Memory Map Definitions The def2181 h header file contains macros that define reserved memory addresses for a ADSP 218x processor apart from a ADSP 2181 processor These memory addresses are used as system registers errno h The errno h header file provides access to errno This facility is not in general supported by the rest of the library ffts h Fast Fourier Transforms This category includes the Fast Fourier Transform functions of the C library These functions are Analog Devices extensions to the ANSI standard fftN stands for the entire family of Fast Fourier Transform func tions fft1024 fft512 etc The fftN functions compute the Fast Fourier Transform FFT of their N point complex input signal The ifftN functions compute the Inverse Fast Fourier Transform of their N point complex input signal The input to each of these functions is two integer arrays real and imaginary of N elements The routines output two N element arrays and an associated block exponent for them If you only wish to inpu
152. d Library Manual for ADSP 218x DSPs C Run Time Library To use built in functions your source must include the required standard include file For the abs functions this would require stdlib h to be included There are built in functions used to define some ANSI C math h string h and stdlib h functions There are also built in func tions to support various ANALOG extensions to the ANSI standard defined in the include file math_builtins h Not all built in functions have a library alternate definition Therefore the failure to use the required include files can result in your program build failing to link If you want to use the C run time library functions of the same name compile with the no builtin no builtin functions compiler switch Linking Library Functions The C run time library is organized as several libraries which are cata logued in Table 3 15 on page 3 4 The libraries and start up files are installed within the subdirectory 218x lib of your VisualDSP installation When you call a run time library function the call creates a reference that the linker resolves One way to direct the linker to the library s location is to use the default Linker Description File ADSP 21 lt your_target gt df If you are not using the default LDF file then either add the appropriate library libraries to the LDF file used for your project or use the compiler s 1 switch to specify the library to be added to the link line For exam
153. d sections 1 76 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Applying section is only meaningful when the data item is something that the compiler can place in the named section Apply section only to top level named objects that have static duration meaning they are explicitly static or are given as external object definitions The example shows the declaration of a static variable that is placed in the section called bingo static section bingo int x Boolean Type Support Keywords bool true false The bool true and false keywords are extensions that support the C boolean type The bool keyword is a unique signed integral type There are two built in constants of this type true and false When convert ing a numeric or pointer value to bool a zero value becomes false a nonzero value becomes true A bool value may be converted to int by promotion taking true to one and false to zero A numeric or pointer value is automatically converted to bool when needed These keywords behave more or less as if the declaration that follows had appeared at the beginning of the file except that assigning a nonzero inte ger to a boo type always causes it to take on the value true typedef enum false true bool Pointer Class Support Keyword restrict The restrict operator keyword is an extension that supports restricted pointer features The use of restrict is limited to the declaratio
154. data stack The signalf function cannot be used in applications where nested interrupts are enabled This interrupt dispatcher will pass the interrupt ID to the handler as its parameter The signals interrupt dispatcher saves and restores only the smallest number of registers and modes required to determine if a handler has been registered and to call that handler The handler passed as input to signals 3 116 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs must be declared using the pragma interrupt directive see C Run Time Library on page 1 102 The altregisters directive see on page 1 103 may be used in conjunction with the interrupt pragma in the definition of the handler This dispatcher will not pass the interrupt ID to the handler The sig argument must be one of the signals listed in highest to lowest priority of interrupts in Table 3 33 Table 3 33 Signal Function Signals Values and Meanings Sig Value Definition SIGPWRDWN Power down interrupt STGIRQ2 Interrupt 2 SIGIRQL1 Interrupt 1 level sensitive SIGIRQLO Interrupt 0 level sensitive SIGSPORTOXMIT Signal Sport 0 transmit STGSPORTORECY Signal Sport 0 receive SIGIRQE Level sensitive SIGBDMA Byte DMA interrupt SIGSPORTIXMIT Signal Sport 1 transmit SIGIRQ1 Interrupt 1 STGSPORTIRECV Signal Sport 1 receive STGIRQO Interrupt 0 SIGTIMER Timer interrupt SIGABRT
155. define VCSE components verbose The verbose display command line switch directs the compiler to dis play command line information for all the compilation tools as they process each file version The version display compiler version switch directs the compiler to display its version information VisualDSP 3 5 C Compiler and Library Manual 1 43 for ADSP 218x DSPs Compiler Command Line Reference Wdriver limit number The Wdriver limit maximum process errors switch lets you set a maxi mum number of driver errors command line etc that the driver aborts at Werror limit number The Werror limit maximum compiler errors switch lets you set a max imum number of errors for the compiler W error remark suppress warn lt num gt num The Ww lt gt number override error message switch directs the compiler to override the severity of the specified diagnostic messages errors remarks or warnings The num argument specifies the message to override At compilation time the compiler produces a number for each specific compiler diagnostic message The D discretionary string after the diag nostic message number indicates that the diagnostic may have its severity overridden Each diagnostic message is identified by a number that is used across all compiler software releases Wremarks The Wremarks enable diagnostic warnings switch directs the compiler to issue remarks which are d
156. defined with the asm con struct it passes this code directly to the assembler The compiler does perform substitutions for operands of the formats 0 through 9 However it passes everything else through to the assembler without reading or analyzing it The asm constructs are executable statements and as such may not appear before declarations within C functions asm constructs may also be used at global scope outside function declarations Such asm constructs are used to pass declarations and directives directly to the assembler They are not executable con structs and may not have any inputs or outputs or affect any registers A simplified asm construct without operands takes the form of asm ENA INTS The complete assembly language instruction enclosed in double quotes is the argument to asm Using asm constructs with operands requires some additional syntax 1 56 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Note that the compiler generates a label before and after inline assembly instructions when generating debug code g switch These labels are used to generate the debug line information used by the debugger If the inline assembler inserts conditionally assembled code then likely at link time an undefined symbol error will occur If the inline assembler changes the section causing the compilers labels to be placed for example in a data section instead of t
157. e exp exponential Synopsis d Finclude lt math h gt double exp double float expf float Description The exp function computes the exponential value e to the power of its argument The argument must be in the range 87 9 88 6 Error Conditions The exp function returns the value HUGE_VAL and stores the value ERANGE in errno when there is an overflow error In the case of underflow the exp function returns a zero Example d Finclude lt math h gt double y y exp 1 0 y 2 71828 See Also log pow 3 52 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library fabs float absolute value Synopsis include lt math h gt double fabs double float fabsf float Description The fabs function returns the absolute value of the argument Error Conditions The fabs function does not return an error condition Example d Finclude lt math h gt double y y fabs 2 3 y 2 3 y fabs 2 3 y 2 3 See Also abs labs VisualDSP 3 5 C Compiler and Library Manual 3 53 for ADSP 218x DSPs C Run Time Library Reference fftN N point complex input fast Fourier transform FFT Synopsis Hinc ude lt ffts h gt int fft1024 int rl_in int im_in int rl_out int im_out int fft512 int rl_in int im_in int rl_out int im_out int fft256 int rl_in int im_in int rl
158. e will be called E VisualDSP 3 5 C Compiler and Library Manual 3 75 for ADSP 218x DSPs C Run Time Library Reference See Also disable_interrupts enable_interrupts io_space_write sysreg_read sysreg_write 3 76 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library io_space_write write I O space Synopsis include lt sysreg h gt void io_space_write const int address const unsigned int value Description The io_space_write function stores the value passed as the second param eter to I O memory space at the address passed as the first parameter This function is implemented as a compiler built in If the address param eter is a constant literal value the compiler will emit a Type 29 instruction that will be inlined at the point of io_space_write use For non literal addresses the compiler will call a library compiler support routine to per form the required write The inclusion of the sysreg h include file is mandatory when using io_space_write Error Conditions The io_space_write function does not return raise or set any error conditions Example include lt sysreg h gt int addr OxA int val OxA main int vl jo_space_write 0xA val inline instruction will be generated awe VisualDSP 3 5 C Compiler and Library Manual 3 77 for ADSP 218x DSPs C Run Time Library Reference int v2 jo_space_write addr OXFF support routine will be
159. e array is computed on entry to the block and saved in sizeof that is applied to the array For multidimensional arrays the boundaries are also saved for address computation After leaving the block all the space allocated for the array and size information are deallocated For example the following program prints 40 not 50 Finclude lt stdio h gt void foo int main foo 40 void foo int n char cin n 50 printf d sizeof c VisualDSP 3 5 C Compiler and Library Manual 1 79 for ADSP 218x DSPs C Compiler Language Extensions Non Constant Aggregate Initializer Support The compiler includes extended support for aggregate initializers The compiler does not require the elements of an aggregate initializer for an automatic variable to be constant expressions The following example shows an initializer with elements that vary at run time void initializer float a float b float the_array 2 a b a b All automatic structures can be initialized by arbitrary expressions involv ing literals previously declared variables and functions Indexed Initializer Support ISO ANSI Standard C requires the elements of an initializer to appear in a fixed order the same as the order of the elements in the array or structure being initialized The cc218x C compiler by comparison supports label ing elements for array initializers This feature lets you specify array or structure elements in a
160. e files effectively disabling this feature This option is position dependent on the command line it only affects files following it reserve register register The reserve reserve register switch directs the compiler mot to use the specified register s This guarantees that a known register or set of regis ters is available for autobuffering You can reserve the 12 13 15 17 and MO registers Separate register names with commas on the compiler command line Reserving registers seriously reduces the effectiveness of compiler optimizations and should only be done when autobuffering using circular buffers is essential For more information refer to Autobuffering Support on page 1 134 The S stop after compilation switch directs the compiler to stop compi lation before running the assembler The compiler outputs an assembler file with a s extension You can invoke this switch by selecting the Stop after Compiler check box in the VisualDSP Project Options dialog box Compile tab General category selection 1 38 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler The s strip debugging information switch directs the compiler to remove debugging information symbol table and other items from the output executable file during linking save temps The save temps save intermediate files switch directs the compiler to retain intermediate files generated and normally removed
161. e h gt int isspace int c Description The isspace function determines if the argument is a blank whitespace character 0x09 0x0D or 0x20 This includes space form feed f new line n carriage return r horizontal tab t and vertical tab v If the argument is not a blank space character isspace returns a zero If the argument is a blank space character isspace returns a non zero value Error Conditions The isspace function does not return any error conditions Example include lt ctype h gt int ch for ch 0 ch lt Ox7f ch printf 04x ch printf 2s isspace ch space putchar n See Also iscntrl isgraph VisualDSP 3 5 C Compiler and Library Manual 3 91 for ADSP 218x DSPs C Run Time Library Reference isupper detect uppercase character Synopsis include lt ctype h gt int isupper int c Description The isupper function determines if the argument is an uppercase charac ter A Z If the argument is not an uppercase character isupper returns a zero If the argument is an uppercase character isupper returns a non zero value Error Conditions The isupper function does not return any error conditions Example dFinclude lt ctype h gt int ch for ch 0 ch lt 0x7f ch printf 04x ch printf 2s isupper ch uppercase putchar n See Also isalpha islower 3 92 VisualDSP 3 5 C Compiler and
162. e of any leaf assembly routine leaf_exit is responsible for restoring the caller s stack and frame pointers and jumping to the return address alter x The alter macro expands into an instruction that adjusts the stack pointer by adding the immediate value x With a positive value for x alter pops x words from the top of the stack You could use alter to clear x number of parameters off the stack after a call VisualDSP 3 5 C Compiler and Library Manual 1 153 for ADSP 218x DSPs C and Assembly Language Interface save_reg The preprocessor expands the save_reg macro into a series of assembly language commands that push the following registers on the ADSP 218x architecture onto the C run time stack AYO AXO AX1 MYO MXO MX1 MR1 MRO SR1 SRO 10 I1 MO M3 15 restore_reg The restore_reg macro expands into a series of instructions that pop the stored registers off of the C run time stack readsfirst register The preprocessor expands the readsfirst macro into a series of assembly language commands that read the value off the top of the stack write the value to register and set up for a read of the next stack entry with the readsnext macro The readsfirst macro references the stack pointer 14 and might be used to read values that were placed on the stack using the putsfirst and putsnext macros register readsnext The preprocessor expands the readsnext macro into a series of assembly language commands T
163. e one or more decimal digits The sequence of digits may contain a decimal point The decimal digits can be followed by an exponent which consists of an introductory letter e or E and an optionally signed integer If neither an exponent part nor a decimal point appears a decimal point is assumed to follow the last digit in the string The form of a hexadecimal floating point number is sign 0x 0X hexdigs L hexdigs p P sign digits VisualDSP 3 5 C Compiler and Library Manual 3 143 for ADSP 218x DSPs C Run Time Library Reference A hexadecimal floating point number may start with an optional plus or minus followed by the hexadecimal prefix 0x or 0X This character sequence must be followed by one or more hexadecimal characters that optionally contain a decimal point The hexadecimal digits are followed by a binary exponent that consists of the letter p or P an optional sign and a non empty sequence of decimal digits The exponent is interpreted as a power of two that is used to scale the fraction represented by the tokens hexdigs hexdigs The first character that does not fit either form of number will stop the scan If endptr is not NULL a pointer to the character that stopped the scan is stored at the location pointed to by endptr If no conversion can be performed the value of nptr is stored at the location pointed to by endptr Error Conditions The strtodf function return
164. e strcpy function returns the new s1 Error Conditions The strcpy function does not return an error condition Example d Finclude lt string h gt char stringl1 50 strcpy stringl SOMEFUN SOMEFUN is copied into stringl See Also memcpy Memmove strncpy VisualDSP 3 5 C Compiler and Library Manual 3 129 for ADSP 218x DSPs C Run Time Library Reference strcspn length of character segment in one string but not the other Synopsis include lt string h gt size_t strcespn const char sl const char s2 Description The strcspn function returns the length of the initial segment of s1 which consists entirely of characters not in the string pointed to by s2 The string pointed to by s2 is treated as a set of characters The order of the characters in the string is not significant Error Conditions The strcspn function does not return an error condition Example S include lt string h gt char ptrl ptr2 size_t len ptrl Tried and Tested ptr2 aeiou len strcspn ptrl ptr2 Jen 2 See Also strlen strspn 3 130 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library strerror get string containing error message Synopsis d Finclude lt string h gt char strerror int errnum Description The strerror function returns a pointer to a string containing an error message by mapping the number in errnum to that str
165. e supplied with this release of the cc218x compiler appears in Table 3 16 You should use a C standard text to aug ment the information supplied in this chapter Table 3 16 C Run Time Library Header Files Header Purpose Standard assert h Diagnostics ANSI circ h Support for circular buffers C Extension ctype h Character handling ANSI def2181 h Memory map definitions C Extension def218x h Memory map definitions C Extension errno h Error handling ANSI ffts h FFT functions C Extension filters h DSP filters C Extension float h Floating point types ANSI VisualDSP 3 5 C Compiler and Library Manual 3 5 for ADSP 218x DSPs C Run Time Library Guide Table 3 16 C Run Time Library Header Files Contd Header Purpose Standard fract h Macros to use fract C Extension iso646 h Boolean operators ANSI limits h Limits ANSI locale h Localization ANSI math h Mathematics ANSI misc h Timer C Extension setjmp h Non local jumps ANSI signal h Signal handling ANSI sport h Serial port C Extension stdarg h Variable arguments ANSI stddef h Standard definitions ANSI stdio h Input Output ANSI stdlib h Standard library ANSI string h String handling ANSI sysreg h Efficient system access C Extension The following sections provides descriptions of all header files assert h The assert h header file contains the assert macro
166. e used Restricting the volatile set to these registers will produce no impact on the code produced for the function but may free up registers for the caller to allocate across the call site String Syntax A regs_clobbered string consists of a list of registers register ranges or register sets that are clobbered The list is separated by spaces commas or semicolons A register is a single register name which is the same as that which may be used in an assembly file A register range consists of start and end registers which both reside in the same register class separated by a hyphen All registers between the two inclusive are clobbered A register set is a name for a specific set of commonly clobbered registers that is predefined by the compiler The following register sets are defined Set Registers CCset ASTAT condition codes R MRO MR2 SR SRO SRI DAGlscratch Members of DAGI I L and M registers that are scratch by default DAG2scratch Members of DAG2 I L and M registers that are scratch by default DAGscratch DAGIscratch and DAG2scratch Dscratch Members of D registers that are scratch by default ALLscratch Entire default volatile set When the compiler detects an illegal string a warning is issued and the default volatile set as defined in this compiler manual is used instead 1 112 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Unclobberable and Mus
167. e zeroed after any call to that function The IMASK ICNTL SSTAT IFC and OWNCNTR registers are never used by the compiler and are never preserved VisualDSP 3 5 C Compiler and Library Manual 1 113 for ADSP 218x DSPs C Compiler Language Extensions User Reserved Registers User reserved registers will never be preserved in the function wrappers whether in the clobbered set or not Function Results The registers in which a function returns its result must always be clob bered by the callee and retain their new value in the caller They may appear in the clobbered set of the callee but it will make no difference to the generated code the return register will not be saved and restored Only the return register used by the particular function return type is spe cial Return registers used by different return types will be treated in the clobbered list in the convention way For example typedef struct int x int y Point typedef struct int x 10 Big int f Result in AX1 SR1 SRO and IO may be preserved across call Point g Result in SRI and SRO AX1 and IO may be preserved across call Big f Result pointer in I0 AX1 SR1 and SRO may be preserved across call pragma result_alignment n The pragma result_alignment n asserts that the pointer or integer returned by the function has a value that is a multiple of n It is often used in conjunction with the pragma alloc of custom allocat
168. ed The qsort function executes a binary search operation on a pre sorted array Note that e base points to the start of the array e nelem is the number of elements in the array e size is the size of each element of the array e compare is a pointer to a function that is called by qsort to com pare two elements of the array The function should return a value less than equal to or greater than zero according to whether the first argument is less than equal to or greater than the second VisualDSP 3 5 C Compiler and Library Manual 3 109 for ADSP 218x DSPs C Run Time Library Reference Error Conditions The qsort function does not return an error condition Example d Finclude lt stdlib h gt float a 10 int compare_float const void a const void b oat aval float a oat bval float b f aval lt bval return 1 else if aval bval return 0 else return 1 gt qsort a sizeof a sizeof a 0 sizeof a 0 compare_float See Also bsearch 3 110 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library raise force a signal Synopsis d Finclude lt signal h gt int raise int sig Description The raise function sends the signal sig to the executing program The raise function forces interrupts wherever possible and simulates an inter rupt otherwise Edge sensitive hardware interrupts are raised by setting the
169. ed based on the depth of loop nesting Tip Avoid the use of inline code Avoid using the inline keyword to inline code for functions that are used a number of times especially if they not very small functions The 0s switch does not have any effect on the use of the inline keyword It does however prevent automatic inlining using the 0a switch described on page 1 33 from increasing the code size Macro functions can also cause code expansion and should be used with care 2 28 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Achieving Optimal Performance from C Source Code Pragmas Pragmas can assist optimization by allowing the programmer to make assertions or suggestions to the compiler This section looks at how they can be used to finely tune source code Refer Pragmas on page 1 99 for full details of how each pragma works the emphasis here will be in consid ering under what circumstances they are useful during the optimization process In most cases the pragmas serve to give the compiler information which it is unable to deduce for itself It must be emphasized that the programmer is responsible for making sure that the information given by the pragma is valid in the context in which it is used Use of a pragma to assert that a function or loop has a quality that it does not in fact have is likely to result in incorrect code and hence a malfunctioning application An advantage of the use of pragm
170. ed to the source file name By default all precompiled headers are stored in a directory called PCHRepository Precompiled header files can significantly speed compilation pre compiled headers tend to occupy more disk space pch directory The pch directory locate PCHRepository switch specifies the location of an alternative PCHRepository for storing and invocation of precompiled header files If the directory does not exist the compiler creates it Note that o output does not influence the pchdir option pedantic The pedantic ANSI standard warnings switch causes the compiler to issue warnings for any constructs found in your program that do not strictly conform to the ISO ANSI standard for C The compiler may not detect all such constructs In particular the pedantic switch does not cause the compiler to issue errors when Analog Devices keyword extensions are used VisualDSP 3 5 C Compiler and Library Manual 1 35 for ADSP 218x DSPs Compiler Command Line Reference pedantic errors The pedantic errors ANSI C errors switch causes the compiler to issue errors instead of warnings for cases described in the pedantic switch pplist filename The pplist preprocessor listing switch directs the preprocessor to out put a listing to the named file When more than one source file has been preprocessed the listing file contains information about the last file pro cessed The generated file contains raw so
171. educe execution time How aggressively the compiler performs automatic inlining is controlled using the 0v switch Automatic inlining is enabled using the 0a switch and additionally enables Procedural Optimizations 0 See O on page 1 32 Os on page 1 33 and Ov num on page 1 33 for more information e Interprocedural optimizations IPA The compiler performs advanced aggressive optimization over the whole program in addition to the per file optimizations in proce dural optimization IPA is enabled using the ipa switch and additionally enables Procedural Optimizations 0 See ipa on page 1 26 and O on page 1 32 for more information Interprocedural Analysis The compiler has an optimization capability called Interprocedural Analysis IPA that allows the compiler to optimize across translation units instead of within individual translation units This capability allows the compiler to see all of the source files used in a final link at compilation time and to use that information while optimizing 1 50 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Interprocedural analysis is enabled by selecting the Interprocedural analy sis option on the Compiler tab accessed via the VisualDSP Project Options dialog box or by specifying the ipa command line switch see on page 1 26 The ipa switch automatically enables the 0 switch to turn on optimization Use of the
172. eemnbanacase 1 32 SO T E E 1 32 E EEE E A E N AE E A E EE ee A oe ert 1 32 E E a E E E E E E E EA ET 1 33 E E E E AE E A E E 1 33 AT DUE sanaaa A 1 33 NE AEE EO 1 33 BE E AEA E RO 1 34 aD iia E AI reel eer 1 34 path asm compiler def lib link mem filename 4 1 34 et RAN REO NOR sirara n uaee 1 34 vi VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs CONTENTS anne ESOT sneon ane 1 35 as Tiny Techy aierern ien a 1 35 E aAA AOO 1 35 apo d ESTOT Ste oie a nade eine eee 1 35 E E E E A AE 1 35 E I E T E E E A EE A 1 36 HCE TIN ie ene eee eee 1 36 EC Re EE E A E E E 1 36 R directory Hih ldirectory a accaccsecticsesensmieiteomseeronreadsn 1 37 a E E E E E EE E E E I A T 1 38 Aeee rep sei LTE e soroaren 1 38 1S A A 1 38 E E E E E T 1 39 Se IDS E E anmepsetiierases 1 39 e E A TEE EN E E E E A T 1 39 STERIO FETIO rr ARER EA 1 39 Sige OHIO scieisisnastansctinaiosmaibiasiiaetielriatntiaiiaunncsinuans 1 40 Sa Ga ee eee Ber er Erne ber ern ety nerve eer ie eter pect ener ee eter 1 40 ec hie 22 C1 aan ens is een nee eee ney erie ee See crmer reer ae eee rer or 1 40 AERTS aoa 1 41 E EAE TE A EE E 1 41 E aa AA 1 41 MOG soioinonegpiobuainaaa baiona 1 42 ARERR DIRE corsini earan a 1 42 VisualDSP 3 5 C Compiler and Library Manual vii for ADSP 218x DSPs CONTENTS maned NET sceneries 1 43 Se ree O 1 43 ayilelobal lt nameliii gt osisscSniidieonsiindenndstosiiudidandipnbenbiemsen 1 43 e SE T animacio
173. effs array must be initialized and in PM memory XJ pragma align 16 int state 11 int 7 for i 0 71 lt 11 i stateLi 0 initialize state array y fir 0x1234 coeffs state 10 y holds the filtered output See Also biquad iir 3 58 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library floor floor Synopsis include lt math h gt double floor double float floorf float Description The floor function returns the largest integral value that is not greater than its input Error Conditions The floor function does not return an error condition Example d Finclude lt math h gt double y y floor 1 25 yy 1 0 y floor 1 25 y 2 0 See Also ceil VisualDSP 3 5 C Compiler and Library Manual 3 59 for ADSP 218x DSPs C Run Time Library Reference fmod floating point modulus Synopsis d Finclude lt math h gt double fmod double numer double denom float fmodf float numer float denom Description The fmod function computes the floating point remainder that results from dividing the first argument into the second argument This value is less than the second argument and has the same sign as the first argument If the second argument is equal to zero fmod returns a zero Error Conditions The fmod function does not return an error condition Example include lt math h gt double y y
174. egister 1 71 Q qsort quicksort function 3 109 R R disable source path compiler switch 1 38 R search for source files compiler switch 1 37 raise raise a signal function 3 111 1 18 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs rand random number generator function 3 113 random number see rand srand functions 3 113 read operation 3 11 reading non memory mapped register 3 154 readsfirst macro 1 154 readsnext macro 1 154 realloc change memory allocation function 3 114 real time signals see clear_interrupt interruptf interrupts poll_flag_in raise signal functions register MSTAT mode status 1 145 register classification 1 144 register usage see mixed C assembly programming registers asm constructs 1 61 callee preserved 1 144 circular buffer length 1 144 clobbered 1 111 DAGI1 1 146 DAG 1 147 data register 1 145 dedicated 1 144 reserving 1 38 save scratch 1 144 regs_clobbered string 1 112 remove function 3 11 INDEX rename function 3 11 reserve compiler switch 1 38 restore_reg macro 1 154 restrict see pointer class support keyword restrict restrict keyword 2 23 restrict operator keyword 1 77 restrict qualifier 2 22 restricted pointer 2 22 retain_name pragma 1 107 return from interrupt RTI instruction 1 134 return registers 1 114 return value 1 139 RTT instruction 1 102 run time legacy model A 8 model 1 132 run time environment see mixed C ass
175. embly Language Interface on page 1 148 Before you make any modifications to the source code copy the source code to a file with a different file name and rename the function itself Test the function before you use it in your system to verify that it is func tionally correct Analog Devices only supports the run time library functions as provided ETSI Support for Data Types ETSI functions support fract16 and fract32 data types as follows e fract16 is a 16 bit fractional data type 1 15 format having a range of 1 0 1 0 This is defined in the C language as typedef short fractl6 1 90 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler e fract32 is a 32 bit fractional data type 1 31 format having a range of 1 0 1 0 This is defined in the C language as typedef long fract32 ETSI Header File The following are summary descriptions of the functions provided by the ETSI library as defined in the header file ETSI_fract_arith h Short absolute fractl6 abs_s fractl6 This function returns the 16 bit value that is the absolute value of the input parameter Where the input is 0x8000 saturation occurs and 0x7 fff is returned Short add fractl6 add fractl6 fractl6 This function returns the 16 bit result of addition of the two fract16 input parameters Saturation occurs with the result being set to 0x7 fff for overflow and 0x8000 for underflow Short division fractl6 div_s
176. embly programming run time environment programming see mixed C assembly programming run time header 1 133 218x_hdr asm 1 133 S S stop after compilation compiler switch 1 38 s strip debugging information compiler switch 1 39 saturation 1 87 save scratch registers 1 144 save_reg macro 1 154 VisualDSP 3 5 C Compiler and Library Manual I 19 for ADSP 218x DSPs INDEX save temps save intermediate files compiler switch 1 39 scalar data types 2 7 search character string see strchr strrchr functions search memory character see memchar function search path for include files 1 25 for library files 1 27 searching for included files 1 131 section elimination 2 27 keyword 1 76 seek operation 3 11 segment see placement support keyword segment segment placement A 3 set jump see longjmp setjmp functions setjmp define run time label function 3 115 setjmp h header file 3 10 setting compiler options 1 132 show display command line compiler switch 1 39 shr operation 1 94 signal define signal handling function 3 116 signal h header file 3 10 signalf function 3 116 signals see clear_interrupt interruptf interrupts poll_flag_in raise signal functions signed bitfield make plain bitfields signed compiler switch 1 40 signed char make char signed compiler switch 1 40 silicon revision setting 1 39 sin sine function 3 120 sin_fr16 function 3 120 single case range 1 122 sinh
177. ent Example d e symbol The operand is both an input and an output It must appear as part of the second argument to the asm construct The allocated register is loaded with the C expression value the asm template is executed and then the allocated register s new value is stored back into the C expression Therefore as with pure outputs the C expression must be one that is valid on the left hand side of an assignment Example d e symbol The operand is temporary It must appear as part of the third argument to the asm construct A register is allo cated as working space for the duration of the asm template execution The register s initial value is undefined and the register s final value is discarded The corresponding C expression is not loaded into the register but must be present This expression is normally specified using a literal zero Example d e amp symbol This operand constraint may be applied to inputs and out puts It indicates that the register allocated to the input or output may not be one of the registers that are allocated to VisualDSP 3 5 C Compiler and Library Manual 1 63 for ADSP 218x DSPs C Compiler Language Extensions the outputs or inputs This operand constraint is used when one or more output registers are set while one or more inputs are still to be referenced This situation sometimes occurs if the asm template contains more than one instruction Exam
178. entation Format one PDF file for each manual Viewing and printing the PDF files require a PDF reader such as Adobe Acrobat Reader 4 0 or higher From VisualDSP Access VisualDSP online Help from the Help menu s Contents Search and Index commands Open online Help from context sensitive user interface items toolbar buttons menu commands and windows XXX VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Preface From Windows In addition to any shortcuts you may have constructed there are many ways to open VisualDSP online Help or the supplementary documenta tion from Windows Help system files CHM files are located in the Help folder and PDF files are located in the Docs folder of your VisualDSP installation The Docs folder also contains the FlexLM network license manager software documentation Using Windows Explorer e Double click any file that is part of the VisualDSP documenta tion set e Double click the vdsp help chm file which is the master Help sys tem to access all the other CHM files Using the Windows Start Button e Access the VisualDSP online Help by clicking the Start button and choosing Programs Analog Devices VisualDSP and VisualDSP Documentation e Access the PDF files by clicking the Start button and choosing Programs Analog Devices VisualDSP Documentation for Printing and the name of the book From the Web To download t
179. er and Library Manual for ADSP 218x DSPs Compiler ISR code pragma altregisters The altregisters pragma may be used in conjunction to the interrupt pragma to indicate that the compiler can optimize the saving and restoring of registers through use of the secondary register sets Note the use of the altregisters pragma is not safe when nested interrupts are enabled tpragma interrupt pragma altregisters void field_SIG ISR code Loop Optimization Pragmas Loop optimization pragmas give the compiler additional information about usage within a particular loop which allows the compiler to per form more aggressive optimization The pragmas are placed before the loop statement and apply to the statement that immediately follows which must be a for while or do statement to have effect In general it is most effective to apply loop pragmas to inner most loops since the com piler can achieve the most savings there The optimizer always attempts to vectorize loops when it is safe to do so The optimizer exploits the information generated by the interprocedural analysis see Interprocedural Analysis on page 1 50 to increase the cases where it knows it is safe to do so Consider the following code void copy short a short b Tint 1 for i 0 1 lt 100 i ali b i VisualDSP 3 5 C Compiler and Library Manual 1 103 for ADSP 218x DSPs C Compiler Language Extensions If you call
180. errupt information defined in the C run time library __lib_int_determiner An interrupt dispatcher defined in the C run time library ___esystem_start C run time initialization defined in the run time header The 218x_int_tab file contains a section of code for each hardware inter rupt The LOF file places these code sections in the correct interrupt vector slots for each interrupt VisualDSP 3 5 C Compiler and Library Manual 1 133 for ADSP 218x DSPs C Run Time Model and Environment If an interrupt occurs program execution begins at the interrupt vector addresses Program execution causes a jump to __1ib_int_determiner in the default vector code If __lib_int_determiner finds by inspecting __lib_int_table a handler set for the interrupt it will call the handler __lib_int_determiner saves and restores all scratch registers around the handler call The function __1ib_int_determiner terminates by executing a return from interrupt RTI instruction which restores program execu tion to the point at which the interrupt was raised A handler for an interrupt or signal is set using the interrupt or signal C run time library functions These functions pass the signal name and a handler function pointer as parameters The signal macro names are defined in signal h The default interrupt vector code may be replaced with custom code by modifying or creating a new piece of code to be placed at the vector addresses This is usually done by
181. es It is useful to bear in mind the following basic strategy when writing an application 1 Try to choose an algorithm that is suited to the architecture being targeted For example there may be a trade off between memory usage and algorithm complexity that may be influenced by the tar get architecture 2 Code the algorithm in a simple high level generic form Keep the target in mind especially with respect to choices of data types 3 You can then turn your attention towards code tuning For critical code sections think more carefully about the strengths of the target platform and make any non portable changes where necessary Tip Choose the language as appropriate This section contains e How the Compiler Can Help on page 2 4 e Data Types on page 2 7 e Getting the Most from IPA on page 2 9 e Indexed Arrays vs Pointers on page 2 12 e Function Inlining on page 2 13 e Using Inline asm Statements on page 2 14 e Memory Usage on page 2 15 VisualDSP 3 5 C Compiler and Library Manual 2 3 for ADSP 218x DSPs General Guidelines How the Compiler Can Help The compiler provides many facilities designed to help the programmer Using the Compiler Optimizer There is a vast difference in performance between code compiled opti mized and code compiled non optimized In some cases optimized code can run ten or twenty times faster Optimization should always be used when measurin
182. est silicon revision it knows about if any A compiler will pass along the appropriate si revision switch setting when invoking another VisualDSP tool for example when the com piler driver invokes assembler and linker signed bitfield The signed bitfield make plain bitfields signed switch directs the compiler to make bitfields which have not been declared with an explicit signed or unsigned keyword to be signed This switch does not effect plain one bit bitfields which are always unsigned This is the default mode See also the unsigned bitfield switch on page 1 42 signed char The signed char make char signed switch directs the compiler to make the default type for char signed The compiler also defines the SIGNED_CHARS__ macro This is the default mode when the unsigned char make char unsigned switch on page 1 43 is not used syntax only The syntax only just check syntax switch directs the compiler to check the source code for syntax errors and warnings No output files will be generated with this switch 1 40 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler sysdefs The sysdefs system definitions switch directs the compiler to define several preprocessor macros describing the current user and user s system The macros are defined as character string constants and are used in func tions with null terminated string arguments The following macros
183. esulting bits are shifted right by 16 VisualDSP 3 5 C Compiler and Library Manual 1 93 for ADSP 218x DSPs C Compiler Language Extensions Saturate fractl6 saturate fract32 This function returns the 16 most significant bits of the input parameter If the input parameter is greater than 0x7fff 0x7fff is returned If the input parameter is less than 0x8000 0x8000 is returned Short shift left fractl6 shl fractl6 fractl6 This function arithmetically shifts the first parameter left by second parameter bits The empty bits are zero filled If second parameter is nega tive the operation shifts right Short shift right fractl6 shr fractl6 fractl6 This function arithmetically shifts the first parameter right by second parameter bits with sign extension If second parameter is negative the operation shifts left Shift right with rounding fractl6o shr_r fractl6 fractl6 This function performs a shift to the right as per the shr operation with additional rounding and saturation of the result Short subtract fractl6 sub fractl6 fractl6 This function returns the 16 bit result of the subtraction of the two parameters Saturation occurs with the result being set to 0x7fff for over flow and 0x8000 for underflow 1 94 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Long absolute fract32 L_abs fract32 This function returns the 32 bit absolute value of the input parameter In
184. et up by the getsfirst macro by reading the next value off the top of the stack and writing it to register Using Mixed C Assembly Naming Conventions It is necessary to be able to use C symbols function or variable names in assembly routines and use assembly symbols in C routines This section describes how to name C and assembly symbols and how to use C and assembly symbols To name an assembly symbol that corresponds to a C symbol add an underscore prefix to the C symbol name when declaring the symbol in assembly For example the C symbol main becomes the assembly symbol _main VisualDSP 3 5 C Compiler and Library Manual 1 155 for ADSP 218x DSPs C and Assembly Language Interface To use a C function or variable in your assembly routine declare it as glo bal in the C program and import the symbol into the assembly routine by declaring the symbol with the EXTERN assembler directive To use an assembly function or variable in your C program declare the symbol with the GLOBAL assembler directive in the assembly routine and import the symbol by declaring the symbol as extern in the C program Alternatively the cc218x compiler provides an asm linkage speci fier used similarly to the C linkage specifier of C which when used removes the need to add an underscore prefix to the symbol that is defined in assembly Table 1 14 shows the C Assembly interface naming conventions Table 1 14 Naming Conventio
185. ew tools Of the new features and enhancements the following have the most impact on your existing projects e Some tools switches have changed If you use any of the modified or obsolete switches you must revise your command line scripts or batch files in order to rebuild your project e The code generation tools no longer support AEXE format DSP executables EXE They now generate ELF format DSP executa bles DXE and the debugger requires DSP executables to be in the ELF DWARF 2 format As a result AEXE formatted files must be VisualDSP 3 5 C Compiler and Library Manual A 1 for ADSP 218x DSPs Tools Differences recompiled or reassembled in order to be debugged under VisualDSP 3 5 An ELF DWARF to AEXE conversion utility is available in VisualDSP 3 5 to perform back conversion An AEXE to ELF conversion utility performs forward conversion e Some assembly instructions and directives have changed from the VisualDSP 6 1 syntax but a legacy assembler switch has been provided to assemble files in the old syntax You may need to review diagnostic messages and revise your source code in order to reassemble your source Legacy syntax and the new syntax under VisualDSP 3 5 cannot be used together in the same source file They can be mixed together within the same project as long as they are assembled in different source files e Some C compiler extensions to the ISO ANSI standard have changed If you use any of the m
186. extensions By default the compiler processes the input file through the listed stages to produce a DXE file When developing a DSP project you may find it useful to modify the compiler s default options settings The way you set the com piler s options depends on the environment used to run the DSP development software See Specifying Compiler Options in VisualDSP on page 1 10 for more information 1 6 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Running the Compiler Use the following general syntax for the cc218x command line ce218x switch L switch sourcefile sourcefile where e switch is the name of the switch to be processed The compiler has many switches These switches select the operations and modes for the compiler and other tools Command line switches are case sensitive For example 0 is not the same as o e The sourcefile is the name of the file to be preprocessed com piled assembled and or linked e A file name can include the drive directory file name and file extension The compiler supports both Win32 and POSIX style paths using either forward or back slashes as the directory delim iter It also supports UNC path names starting with two slashes and a network name e The cc218x compiler uses the file extension to determine what the file contains and what operations to perform upon it Table 1 1 on page 1 9 lists the allowed extensions
187. extensions to the ANSI standard Each of these eight ifftN functions computes the N point radix 2 Inverse Fast Fourier transform IFFT of its integer input where N is 8 16 32 64 128 256 512 or 1024 There are eight distinct functions in this set They all perform the same function with the same type and number of arguments The only differ ence between them is the size of the arrays on which they operate To call a particular function substitute the number of points for N for example ifft8 r_inp i_inp r_outp i_outp not ifftN r_inp i_inp r_outp i_outp The input to ifftN are two integer array of N points The array real_input contains the real components of the inverse FFT input and the array imag_input contains the imaginary components If there are fewer than N actual data points you must pad the array with zeros to make N samples Better results occur with less zero padding however The input data should be windowed if necessary before calling the function because no preprocessing is performed on the data The functions return a block exponent The input and output arrays must be different The out put arrays must be on circular boundaries Error Conditions The ifftN functions do not return error conditions 3 64 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library Example include lt ffts h gt dtdefine N 1024 int real_input N imag_input N fpragma align
188. fmod 5 0 2 0 y 1 0 See Also div Idiv modf 3 60 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library free deallocate memory Synopsis d Finclude lt stdlib h gt void free void ptr Description The free function deallocates a pointer previously allocated to a range of memory by calloc or malloc to the free memory heap If the pointer was not previously allocated by calloc malloc or realloc the behavior is undefined The free function returns the allocated memory to the heap from which it was allocated Error Conditions The free function does not return an error condition Example include lt stdlib h gt char ptr ptr malloc 10 Allocate 10 words from heap free ptr Return space to free heap y See Also calloc malloc realloc VisualDSP 3 5 C Compiler and Library Manual 3 61 for ADSP 218x DSPs C Run Time Library Reference frexp separate fraction and exponent Synopsis include lt math h gt double frexp double f int expptr float frexpf float f int expptr Description The frexp function separates a floating point input into a normalized fraction and a base 2 exponent The function returns the first argument as a fraction in the interval 2 1 and stores a power of 2 in the integer pointed to by the second argument If the input is zero then the fraction and exponent will both be set to zero Error Co
189. fract16 x if x lt 0x2000 lt 0 25 first quadrant 0 7 2 a sin_fr16 Ox0 0x7fff 0 0x7fff return sin_frl6 x 4 else if x lt 0x6000 lt 0 75 if x lt 0x4000 second quadrant 2 1 x sin_fr16 0x8000 0x0 0x7fff 0 x7 a if x lt 0x6000 ay third quadrant 3 21 xy sin_fr1i6 0x0 0x7fff 0 0x8000 EJ return sin_fr1i6 0xc000 x 4 else fourth quadrant 3 27 7 me sin_frl6 0x8000 0x0 0x8000 0 return sin_fr16 0x8000 x 4 See Also asin COS VisualDSP 3 5 C Compiler and Library Manual 3 121 for ADSP 218x DSPs C Run Time Library Reference sinh hyperbolic sine Synopsis d Finclude lt math h gt double sinh double float sinhf float Description The sinh function returns the hyperbolic sine of the input parameter Error Conditions The sinh function returns the IEEE constant Inf if the argument is out side the domain Example d Finclude lt math h gt double x y y sinh x See Also cosh 3 122 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library sqrt square root Synopsis dFinclude lt math h gt double sqrt double fractl6 sqrt_frl6 fractl6 Description The sqrt function returns the positive square root of the input parameter Error Conditions The sqrt function returns a zero for a negative inp
190. g VisualDSP 3 5 C Compiler and Library Manual 1 45 for ADSP 218x DSPs Compiler Command Line Reference xref lt file gt The xref cross reference list switch directs the compiler to write cross reference listing information to the specified fi7e When more than one source file has been compiled the listing contains information about the last file processed For each reference to a symbol in the source program a line of the form symbol id name ref code filename line number column number is written to the named file symbol id represents a unique decimal num ber for the symbol The ref code parameter is one of the following characters Character Meaning D d Definition Declaration Modification Address taken Used Changed used and modified Any other type of reference Error unknown type of reference 1 46 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Data Type Sizes Compiler The sizes of intrinsic C data types are selected by Analog Devices so that normal C programs execute with hardware native data types and therefore execute at high speed Table 1 4 Data Type Sizes for the ADSP 218x DSPs Type Bit Size sizeof returns int 16 bits signed unsigned int 16 bits unsigned char 16 bits signed unsigned char 16 bits unsigned short 16 bits signed unsigned short 16 bits unsigned pointer 16 bits fract16 16 bits f
191. g performance or shipping code as product The optimizer in the C compiler is designed to generate efficient code from source that has been written in a straightforward manner The basic strategy for tuning a program is to present the algorithm in a way that gives the optimizer excellent visibility of the operations and data and hence the greatest freedom to safely manipulate the code Future releases of the compiler will continue to enhance the optimizer and expressing algorithms simply will provide the best chance of benefiting from such enhancements Note that the default setting or debug mode within the VisualDSP IDDE is for non optimized compilation in order to assist programmers in diagnosing problems with their initial coding The optimizer is enabled in VisualDSP by checking the Enable optimization check box under the Project Options gt Compile tab This adds the 0 enable optimiza tion switch on page 1 32 to the compiler invocation A release build from within VisualDSP will automatically enable optimization Using the Statistical Profiler Tuning an application begins with an understanding of which areas of the application are most frequently executed and therefore where improve ments would provide the largest gains The statistical profiling feature provided in VisualDSP is an excellent means for finding these areas More details about how to use it may be found in the VisualDSP 3 5 User s Guide
192. g the Const Qualifier By default the compiler assumes that the data referenced by a pointer to const type will not change Therefore another way to tell the compiler that the two arrays a and b do not overlap is to use the const keyword void copy short a const short b int ji for i 0 i lt 100 i ali b i Good pointers disambiguated via const qualifier The above example will have a similar effect on the no_alias pragma see in pragma no_alias on page 2 34 In fact the const implementation is better since it also allows the optimizer to use the fact that accesses via a and b are independent in other parts of the code not just the inner loop In C it is legal though bad programming practice to use casts to allow the data pointed to by pointers to const type to change This should be avoided since by default the compiler will generate code that assumes const data does not change If you have a program that modifies const data through a pointer you can generate standard conforming code by using the compile time flag const read write VisualDSP 3 5 C Compiler and Library Manual 2 23 for ADSP 218x DSPs Using Built in Functions in Code Optimization Using Built in Functions in Code Optimization Built in functions also known as compiler intrinsics provide a method for the programmer to efficiently use low level features of the DSP hard ware while programming in C Although this section does
193. ge 1 23 See the ip switch description in the VisualDSP 3 5 Linker and Utilities Manual for 16 Bit Processors for more information VisualDSP 3 5 C Compiler and Library Manual 1 101 for ADSP 218x DSPs C Compiler Language Extensions pragma pad alignopt The pragma pad alignopt may be applied to struct definitions It applies to struct definitions that follow until the default alignment is restored by omitting a ignopt for example by pragma pad with empty parentheses This pragma is effectively a shorthand for placing pragma align before every field within the struct definition The following example shows how to use pragma pad pragma pad 4 struct intis int j S8 42233 fpragma pad Interrupt Handler Pragmas The interrupt pragma s include interrupt and altregisters pragmas pragma interrupt The interrupt pragma may be used before a function declaration or defi nition It applies to the function declaration or definition that immediately follows the pragma Use of this pragma causes the compiler to generate the function code so that it may be used as a self dispatching interrupt handler The compiler arranges for the function to save its context above and beyond the usual caller preserved set of registers and to restore the con text upon exit The function will return using a return from interrupt RTI instruction pragma interrupt void field_SIG 1 102 VisualDSP 3 5 C Compil
194. gnition of __builtin functions no defs on page 1 30 Disables preprocessor definitions macros include directo ries library directories run time headers or keyword exten sions no extra keywords on page 1 30 no fp associative on page 1 31 Does not define language extension keywords that could be valid C identifiers Does not treat floating point multiply and addition as an associative no mem on page 1 31 Causes the compiler to not invoke the Memory Initializer after linking Set by default no std ass on page 1 31 Disables any predefined assertions and system specific macro definitions no std def on page 1 31 Disables normal macro definitions also disables Analog Devices keyword extensions that do not have leading under scores __ VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Table 1 2 Compiler Command Line Switches Contd Switch Name Description no std inc on page 1 31 Searches for preprocessor include header files only in the cur rent directory and in directories specified with the 1 switch no std lib on page 1 32 Searches only for those linker libraries specified with the 1 switch when linking no widen muls on page 1 32 Disable widening multiplications optimization 0 on page 1 32 Enables optimizations 0a on page 1 33 0s on page 1 33 Enab
195. has a working knowledge of the ADSP 218x DSP architecture and instruction set and the C programming language Programmers who are unfamiliar with ADSP 218x DSPs can use this manual but they should supplement it with other texts such as the appropriate hardware reference and instruction set reference that provide information about your ADSP 218x DSP architecture and instructions VisualDSP 3 5 C Compiler and Library Manual XXV for ADSP 218x DSPs Manual Contents Description Manual Contents Description This manual contains Chapter 1 Compiler Provides information on compiler options language extensions and C assembly interfacing Chapter 2 Achieving Optimal Performance from C Source Code Shows how to optimize compiler operation Chapter 3 C Run Time Library Shows how to use library functions and provides a complete C library function reference Appendix A Compiler Legacy Support Describes support for legacy code that was developed with previous releases of the development tools What s New in this Manual This edition of the VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs documents support for all ADSP 218x processors Refer to VisualDSP 3 5 Product Bulletin for 16 Bit Processors for infor mation on all new and updated features and other release information XXVI VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Preface Technical or Customer
196. he path tool location switch directs the compiler to use the specified component in place of the default installed version of the compilation tool The component should comprise a relative or absolute path to its location Respectively the tools are the assembler compiler driver defini tions file librarian linker or memory initializer Use this switch when you wish to override the normal version of one or more of the tools The path switch also overrides the directory specified by the path instal1 switch on page 1 34 path install directory The path insta11 installation location switch directs the compiler to use the specified directory as the location for all compilation tools instead of the default path This is useful when working with multiple ver sions of the tool set You can selectively override this switch with the path switch on page 1 34 1 34 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler path output directory The path output non temporary files location switch directs the com piler to place output files in the specified directory path temp directory The path temp temporary files location switch directs the compiler to P y P place temporary files in the specified directory pch The pch precompiled header switch directs the compiler to automati cally generate and use precompiled header files A precompiled output header has a pch extension attach
197. he VisualDSP environment provides access to files on a host system using stdio functions File I O support is provided through a set of low level primitives that implement the open close read write and seek operations The stdio functions make use of these primitives to pro vide conventional C input and output facilities The source files for the I O primitives are available under the VisualDSP installation in the subdirectory 218x 1ib src libio_src Refer to stdio h on page 3 11 for more information Extending I O Support To New Devices The I O primitives are implemented using an extensible device driver mechanism The default start up code includes a device driver that can perform I O through the VisualDSP simulator and EZ KIT Lite Other device drivers may be registered and then used through the normal stdio functions A device driver is a set of primitive functions grouped together into a DevEntry structure This structure is defined in device h struct DevEntry int Device void data EJ t xinit struct DevEntry entry t open const char name int mode close int fd t xwrite int fd unsigned char buf int size t xread int fd unsigned char buf int size long seek long fd long offset int whence a a ies San a ct typedef struct DevEntry DevEntry typedef struct DevEntry DevEntry_t VisualDSP 3 5 C Compiler and Library Manual 1 141 for ADSP 218x DSPs
198. he default code section then the debug line informa tion will be incorrect for these lines Using asm constructs with operands requires some additional syntax The construct syntax is described in e Assembly Construct Template on page 1 57 e Assembly Construct Operand Description on page 1 61 e Assembly Constructs With Multiple Instructions on page 1 67 e Assembly Construct Reordering and Optimization on page 1 67 e Assembly Constructs with Input and Output Operands on page 1 68 e Assembly Constructs and Macros on page 1 70 e Assembly Constructs and Flow Control on page 1 70 Assembly Construct Template Using asm constructs you can specify the operands of the assembly instruction using C expressions You do not need to know which registers or memory locations contain C variables ASM Construct Syntax Use the following general syntax for your asm constructs VisualDSP 3 5 C Compiler and Library Manual 1 57 for ADSP 218x DSPs C Compiler Language Extensions asm template Lconstraint output operand constraint output operand Lconstraint input operand constraint input operand clobber The syntax elements are defined as template The template is a string containing the assembly instruction s with number indicating where the compiler should substitute the oper ands Operands are numbered in order of occurrence from left to right sta
199. he function because no preprocess ing is performed on the data The functions return a block exponent The input and output arrays must be different The output arrays must be on circular boundaries Error Conditions The fftN functions do not return error conditions VisualDSP 3 5 C Compiler and Library Manual 3 55 for ADSP 218x DSPs C Run Time Library Reference Example d Finclude lt ffts h gt define N 1024 int real_input N pragma align 1024 int real_outputIN fpragma align 1024 int imag_outputIN int block_exponent imag_input N block_exponent fft1024 real_input imag_input See Also ifftN real_output imag_output 3 56 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library fir finite impulse response FIR filter Synopsis d Finclude lt filters h gt int fir int sample int pm coeffs int dm state int taps Description This function is an Analog Devices extension to the ANSI standard The fir function implements a finite impulse response FIR filter defined by the coefficients and delay line that are supplied in the call of fir The function produces the filtered response of its input data This FIR filter is structured as a sum of products The characteristics of the fil ter passband stop band etc are dependent on the coefficient values and the number of taps supplied by the calling program The integer input to the f
200. he recipient Using Mixed C Assembly Support Macros This section describes the C Assembly interface support macros available via the asm_sprt h system header file Use these macros for interfacing assembly language modules with C functions Your software package includes a version of the asm_sprt h file Table 1 13 lists and the following section describes the macros Table 1 13 Interface Support Macros function_entry exit leaf_entry leaf_exit alter x save_reg restore_reg readsfirst x readsnext putsfirst putsnext getsfirst x getsnext 1 152 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler function_entry The function_entry macro expands into the function prologue for non leaf functions This macro should be the first line of any non leaf assembly routine exit The exit macro expands into the function epilogue for non leaf func tions This macro should be the last line of any non leaf assembly routine Exit is responsible for restoring the caller s stack and frame pointers and jumping to the return address leaf_entry The leaf_entry macro expands into the function prologue for leaf func tions This macro should be the first line of any leaf assembly routine This macro is currently null but should be used for future compatibility leaf_exit The leaf_exit macro expands into the function epilogue for non leaf functions This macro should be the last lin
201. he tools manuals point your browser at http www analog com technology dsp developmentTools gen_purpose html Select a DSP family and book title Download archive Z1P files one for each manual Use any archive management software such as WinZip to decompress downloaded files VisualDSP 3 5 C Compiler and Library Manual XXxxl for ADSP 218x DSPs Product Information Printed Manuals For general questions regarding literature ordering call the Literature Center at 1 800 ANALOGD 1 800 262 5643 and follow the prompts VisualDSP Documentation Set VisualDSP manuals may be purchased through Analog Devices Cus tomer Service at 1 781 329 4700 ask for a Customer Service representative The manuals can be purchased only as a kit For additional information call 1 603 883 2430 If you do not have an account with Analog Devices you will be referred to Analog Devices distributors To obtain information on our distributors log onto http www analog com salesdir continent asp Hardware Manuals Hardware reference and instruction set reference manuals can be ordered through the Literature Center or downloaded from the Analog Devices website The phone number is 1 800 ANALOGD 1 800 262 5643 The manuals can be ordered by a title or by product number located on the back cover of each manual Datasheets All data sheets can be downloaded from the Analog Devices website As a general rule any data sheet with a letter suffix
202. hese commands continue the read process set up by the readsfirst macro by reading the next value off the top of the stack and writing it to register putsfirst register The preprocessor expands the putsfirst macro into a series of assembly language commands These commands write the contents of register to the top of the stack and set up for a write of the next stack entry with the putsnext macro 1 154 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler putsnext register The preprocessor expands the putsnext macro into a series of assembly language commands These commands continue the write process set up by the putsfirst macro by writing the next register to the top of the stack getsfirst register The preprocessor expands the getsfirst macro into a series of assembly language commands that read the value off the top of the stack write the value to register and set up for a read of the next stack entry with the getsnext macro The preprocessor expands the getsfirst macro into a series of assembly language instructions that read a value from the top of a function frame write the value to register and set up a read of the next value with getsnext The getsfirst macro references the frame pointer M4 and would be used to read function parameters register getsnext The preprocessor expands the getsnext macro into a series of assembly language commands These commands continue the read process s
203. hese libraries will be added to the link line by the default LDF files when macro __RESERVE_AUTOBUFFER_REGS__ is defined The compiler driver will define this macro in compile assemble and link phases when the compilers reserve switch is used The compiler will also plant a common symbol ___reserved_bitmask into modules compiled with the reserve switch This symbol can be used to determine which registers are reserved accross an application This is sometimes required when saving and restoring registers in an interrupt service routine Bits set in ____reserved_bitmask correspond to the following reserved registers bit 0 set I2 reserved bit 1 set I3 reserved bit 2 set I5 reserved bit 3 set I7 reserved bit 4 set MO reserved VisualDSP 3 5 C Compiler and Library Manual 1 135 for ADSP 218x DSPs C Run Time Model and Environment Stack Frame The stack frame or activation record provides for the following activities e Space for local variables for the current procedure For the com piler this includes temporary storage as well as that required for explicitly declared user automatic variables e Place to save linkage information such as return addresses location information for the previous caller s stack frame and to allow this procedure to return to its caller e Space to save information that must be preserved and restored e Arguments passed to the current procedure In addition if this is not a leaf
204. iagnostic messages that are even milder than warnings You can invoke this switch by selecting the Enable remarks check box in the VisualDSP Project Options dialog box Compile tab Warning selection 1 44 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Wterse The Wterse enable terse warnings switch directs the compiler to issue the briefest form of warnings This also applies to errors and remarks W The w disable all warnings switch directs the compiler not to issue warnings You can invoke this switch by selecting the Disable all warnings and remarks check box in the VisualDSP Project Options dia log box Compile tab Warning selection warn protos The warn protos prototypes warning switch directs the compiler to produce a warning message when a function is called without a full proto type being supplied write files The write files enable driver I O redirection switch directs the com piler driver to redirect the file name portions of its command line through a temporary file This technique helps with handling long file names which can make the compiler driver s command line too long for some operating systems write opts The write opts switch directs the compiler to pass the user specified options but zor the input file names to the main driver via a temporary file This can be helpful if the resulting main driver command line would otherwise be too lon
205. ields which have not been declared with an explicit signed or unsigned keyword to be unsigned This switch does not effect plain one bit bitfields which are always unsigned For example given the declaration struct int azz int b 1 signed int c 2 unsigned int d 2 bX the bitfield values are Field unsigned bitfield signed bitfield Why xa 2 1 0 3 Plain field x b 0 1 0 1 One bit x C 2 1 Snl Explicit signed x d 0 3 0 3 Explicit unsigned See also the signed bitfields switch on page 1 40 1 42 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler unsigned char The unsigned char make char unsigned switch directs the compiler to make the default type for char unsigned The compiler also undefines the STGNED_CHARS__ preprocessor macro The v version and verbose switch directs the compiler to display both the version and command line information for all the compilation tools as they process each file val global lt name list gt The val global add global names switch directs the compiler that the names given by lt name ist gt are present in all globally defined variables The list is separated by double colons In C the names are prefixed and separated by underscores _ The compiler will issue an error on any glo bally defined variable in the current source module s not using lt name list gt This switch is used to
206. iiassteninasedlaininacteauudimanieassanlics xxviii DSP Product Informatio itasiscessiacdoidsionacdscndoicoeeaenaabeauniioneds xxviii Relace Den calcio ienaa N xxix Online Technical Documentation osesorressscnms isorine XXX Fiom Viod DOUP E nnn S XXX From Windows aia died cas caesar aini SANRA RSS xxxi Fron the Web ernesrina An RNR XXXi Protea Manuals cncnntoeedeirrokpii niie ai xxxii VisualDSP Documentation Set scccsnsssccaterrvecercnoeeass xxxii VisualDSP 3 5 C Compiler and Library Manual iii for ADSP 218x DSPs CONTENTS Hardware WARIS smnesrnrentnmo nrnna xxxii DS E XXxxil Cte DSP Publicadont sorces R xxxiii Notion Conven one soei shares pated aac eacnarelaadagboaseaeaemonseianeseneas xxxiii COMPILER C Compiler CO nescieira A RA RS 1 2 Stamdard COn NI serii a a 1 3 Compiler Command Line Reference sicicsisscsaciinisaiesisaiciviaaiennemebs 1 6 Running the LO el accuses 1 7 Specifying Compiler Options in VisualDSP oc 1 10 Compiler Command Line Series saci peas sscinssespceesecensecciannesss 1 11 A SWINE aa AEAEE 1 18 A ame to BENEI enncacinone S 1 18 E EAE A E E A E E EN 1 19 Sen eee Or BITES I A ERE SOE 207 EPP TOPO OCR oo OnE SEP REET 1 19 a e o E Aa 1 20 is E EAA E EOE TE ENE E 1 20 ES ca E E E E A A E EE A E E 1 20 CONSTE WIE fsctiodcccsacatrandeantaeatedecstaneanagemssacanenst 1 20 Dmaco AMET acteeicsbicalsiiinicat viens aiana 1 20 debar eper HINES ra 1 21 Aerle hnkage lasm CI srren 1 21 EB INR EE S E
207. ike functions For example the following code example shows macros that contain asm constructs This code defines a macro abs_macro which uses the inline asm instruction to perform an assembly language abs operation of variable x_var putting the result in result_var tdefine abs_macro result x asm Z0 abs 1 c result c x pseudo code result abs x main int result_var 0 int x_var 10 abs_macro result_var 10 Lrg KT abs_macro result_var X_var Assembly Constructs and Flow Control It is inadvisable to place flow control operations within an asm construct that leaves the asm construct such as calling a procedure or perform ing a jump to another piece of code that is not within the asm construct itself Such operations are invisible to the compiler and may violate assumptions made by the compiler For example the compiler is careful to adhere to the calling conventions for preserved registers when making a procedure call If an asm construct calls a procedure the asm construct must also ensure that all conven tions are obeyed or the called procedure may corrupt the state used by the function containing the asm construct 1 70 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Dual Memory Support Keywords pm dm This section covers cc218x keyword extensions to the C language These extensions support the dual memory space modified Harv
208. ile switch directs the compiler to use filename for the output of MD or ED switches Mt filename The Mt filename output make rule for the named source switch specifies the name of the source file for which the compiler generates the make rule when you use the M or MM switch If the named file is not in the current directory you must provide the path name in double quotation marks The new file name will override the default base doj The Mt option supports the IMPORT extension MQ The MQ switch directs the compiler not to compile the source file but to output a rule In addition the MQ switch does not produce any notifica tion when input files are missing 1 28 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler make autostatic The make autostatic make automatic variables static switch directs the compiler to place all automatic variables in static store This may be bene ficial in code that requires many accesses of automatic variables as an access to static store is done in one instruction whereas an access to local automatic stack area may require three instructions Alternatively this feature can be applied on a function by function basis using the make_auto_static pragma See Stack Usage Pragma on page 1 108 for more information Do not use the make autostatic switch if the source being com piled contains any functions that are directly or indirectly recursive
209. ilter is sample The integer taps indicates the length of the filter which is also the length of the array coeffs The coef fs array holds one FIR filter coefficient per element The coefficients are stored in reverse order for example coeffs 0 holds the taps 1 coefficient The coef fs array is located in program memory data space to use the single cycle dual memory fetch of the processor The state array contains a pointer to the delay line as its last element pre ceded by the delay line values The length of the state array is therefore one 1 greater than the number of taps Each filter has its own state array which should not be modified by the calling program only by the fir function The state array should be initialized to zeros before the fir function is called for the first time The delay state array parameter must be located on a circular boundary otherwise the function will not work VisualDSP 3 5 C Compiler and Library Manual 3 57 for ADSP 218x DSPs C Run Time Library Reference The parameters sample coeffs J and state are all considered to be fractional numbers The fir function executes fractional multiplications that preserve the format of the fractional input If your application requires a true integer fir you should divide the output of the filter by two Error Conditions The fir function does not return an error condition Example include lt filters h gt int y int pm coeffsl10 co
210. improved efficiency The default interrupt function dispatcher saves and restores all scratch registers and modes on the data stack around a call to the handler func when servicing an inter rupt This dispatcher will pass the interrupt ID for example S1G_PWRDWN to the handler as its parameter The interruptf interrupt dispatcher does the same as interrupt except it switches between primary and secondary register sets to save and restore registers instead of using the data stack The interruptf function cannot be used in applications where nested interrupts are enabled This interrupt dispatcher will pass the interrupt ID to the handler as its parameter The interrupts interrupt dispatcher saves and restores only the smallest number of registers and modes required to determine if a handler has been registered and to call that handler The handler passed as input to VisualDSP 3 5 C Compiler and Library Manual 3 71 for ADSP 218x DSPs C Run Time Library Reference interrupts must be declared using the pragma interrupt directive on page 1 102 The pragma altregisters directive on page 1 103 may be used in conjunction with the interrupt pragma in the definition of the handler This dispatcher will not pass the interrupt ID to the handler The sig argument must be one of the signals listed in priority order in Table 3 31 Table 3 31 Interrupt Function Signals Values and Meanings
211. in command line switch __NO_LONG_LONG cc218x defines __NO_LONG_LONG as 1 for C source This definition signifies no support is present for the long long int type __SIGNED_CHARS__ cc218x defines __SIGNED_CHARS__ as 1 unless you compile with the unsigned char command line switch VisualDSP 3 5 C Compiler and Library Manual 1 127 for ADSP 218x DSPs Preprocessor Features __ STDC __ cc218x defines _STDC__ asl __STDC_VERSION__ cc218x defines _STDC__ as 199409L __TIME__ The preprocessor expands this macro into the current time as a string con stant The time string constant takes the form hh mm ss ANSI standard __VERSION__ The preprocessor defines __VERSION__ as a string constant giving the ver sion number of the compiler used to compile this module Header Files A header file contains C declarations and macro definitions Use the i tinclude C preprocessor directive to access header files for your program Header file names have an h extension There are two main categories of header files e System header files declare the interfaces to the parts of the operat ing system Include these header files in your program for the definitions and declarations you need to access system calls and libraries Use angle brackets to indicate a system header file For example Hinclude lt file gt e User header files contain declarations for interfaces between the source files of your program Use double q
212. inating null character The initial characters may be composed of an optional sign character 0x or 0X if base is 16 and those letters and digits which represent an integer with a radix of base The letters a z or A Z are assigned the values 10 to 35 and their use is permitted only when those values are less than the value of base If base is zero then the base is taken from the initial characters A leading 0x indicates base 16 a leading 0 indicates base 8 For any other leading characters base 10 is used If base is between 2 and 36 it is used as a base for conversion Error Conditions The strtol function returns a zero if no conversion can be made and the invalid string is stored in the object pointed to by endptr If the correct value results in an overflow positive or negative as appropriate LONG_MAX is returned If the correct value results in an underflow LONG_MIN is returned ERANGE is stored in errno in the case of either overflow or underflow 3 148 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library Example include lt stdlib h gt i tdefine base 10 char rem long int i i strtol 2345 5 amp rem base 7 2345 rem 5 See Also atoi atol strtoul VisualDSP 3 5 C Compiler and Library Manual 3 149 for ADSP 218x DSPs C Run Time Library Reference strtoul convert string to unsigned long integer Synopsis include lt stdlib h gt unsigned
213. information can be held more compactly than in floating point It would take 24 bits in floating point format to match the precision of 16 bit fractional data Also control of normalization and precision is more complex with floating point Many DSPs do not include hardware support for floating point arithmetic and these operations are therefore very expensive in both code size and performance terms for such DSPs 1 86 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Fractional data has a representation similar to that of integers except that while an integer value is considered to have a decimal point to the right of the least significant bit a fractional value is considered to have a decimal point to the left of the most significant bit Fractional values are usually held in 16 bit or 32 bit containers In each case signed values are in the range 1 0 1 0 The bit operations on fractional data are identical to those on integer data but there are three aspects of the result that are normally treated differently 1 MSB extraction Multiplication is a widening operation thus mul tiplying a 16 bit value by another 16 bit value produces a 32 bit result If a 16 bit integer result is required then this is taken to be the least significant 16 bits of the result and the upper 16 bits are regarded as overflow For a fractional operation the upper 16 bits would represent a 16 bit result and the lower 16 b
214. ing Error Conditions The strerror function does not return an error condition Example include lt string h gt char ptrl ptrl strerror 1 See Also No references to this function VisualDSP 3 5 C Compiler and Library Manual 3 131 for ADSP 218x DSPs C Run Time Library Reference strlen string length Synopsis include lt string h gt size_t strlen const char s1 Description The strlen function returns the length of the null terminated string pointed to by s not including the terminating null character Error Conditions The strlen function does not return an error condition Example include lt string h gt size_t len len strlen SOMEFUN len 7 See Also No references to this function 3 132 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library strncat concatenate characters from one string to another Synopsis d Finclude lt string h gt char strncat char sl const char s2 size_t n Description The strncat function appends a copy of up to n characters in the null terminated string pointed to by s2 to the end of the null terminated string pointed to by s1 It returns a pointer to the new s1 string The behavior of strncat is undefined if the two strings overlap The new s1 string is terminated with a null 0 Error Conditions The strncat function does not return an error condition Example d Finclude
215. input data The parameter sections specifies the number of biquad sections The biquad filter implemented in this function is based on the Oppenheim and Schafer Nth order Direct Form II cascaded scheme The characteristics of the filter depend on the coeffi cient values supplied by the calling program The coeffs array must be five 5 times the number of sections in length and it also must be located in program memory pm The definition is int pm coeffs 5 sections The state array holds two delay elements per section It also has one extra location that holds an internal pointer The total length must be 2 sections 1 The definition is int dm state 2 sections 1 You cannot access the state array except that the array should be initial ized to all zeros before the first call to biquad The first location of state is an address Setting the address to zero tells the function that it is being called for the first time VisualDSP 3 5 C Compiler and Library Manual 3 31 for ADSP 218x DSPs C Run Time Library Reference Error Conditions The biquad function does not return an error condition Example include lt filters h gt i fdefine TAPS 9 float sample output statel2 TAPS 1 float pm coeffs 5 TAPS int i for i 0 i lt 2 TAPS 1 i stateli 0 initialize state array output biquad sample coeffs state TAPS First Section Second Section
216. inted to by endptr If the correct value results in an overflow a positive or negative as appropri ate HUGE_VAL is returned If the correct value results in an underflow 0 is returned The ERANGE value is stored in errno in the case of either an over flow or underflow Example d Finclude lt stdlib h gt char re double dd dd strtod 2345 5E4 abc amp rem dd 2 3455E 7 rem abc dd strtod 0x1 800p 9 123 amp rem dd 768 0 rem 123 ey VisualDSP 3 5 C Compiler and Library Manual 3 141 for ADSP 218x DSPs C Run Time Library Reference See Also atof strtol strtoul 3 142 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library strtodf convert string to float Synopsis include lt stdlib h gt float strtodf const char nptr char endptr Description The strtodf function extracts a value from the string pointed to by nptr and returns the value as a float The strtodf function expects nptr to point to a string that represents either a decimal floating point number or a hexadecimal floating point number Either form of number may be pre ceded by a sequence of whitespace characters as determined by the isspace function that the function ignores A decimal floating point number has the form sign digits digits te E sign digits The sign token is optional and is either plus or minus and dig its ar
217. ion functions that return pointers that are more strictly aligned than be deduced from their type 1 114 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Header File Control Pragmas The header file control pragmas help the compiler to handle header files pragma hdrstop The pragma hdrstop is used in conjunction with the pch precompiled header switch on page 1 35 The switch tells the compiler to look for a precompiled header pch file and if it cannot find one to generate a file for use on a later compilation The pch file contains a snapshot of all the code preceding the header stop point By default the header stop point is the first non preprocessing token in the primary source file The pragma hdrstop can be used to set the point earlier in the source file In the example include standard_defs h include common_data h include frequently_changing_data h int is the default header stop point is start of the declaration of i This might not be a good choice as in this example frequently_changing_data h might change frequently causing the pch file to be regenerated often and therefore losing the benefit of precompiled headers The hdrstop pragma can be used to move the header stop to a more appropriate place In this case include standard_defs h include common_data h pragma hdrstop include frequently_changing_data h int i VisualDSP
218. is specified doj Object file to be linked d1b Library of object files to be linked as needed xm DSP system memory map file output sym DSP system symbol map file output For information on additional search directories see the 1 directory switch on page 1 25 and L directory switch on page 1 27 When you provide an input or output file name as an optional parameter use the following guidelines e Use a file name include the file extension with either an unambig uous relative path or an absolute path A file name with an absolute path includes the drive directory file name and file extension Enclose long file names within straight quotes for example Jong file name c The cc218x compiler uses the file extension conven tion listed in Table 1 1 to determine the input file type VisualDSP 3 5 C Compiler and Library Manual 1 9 for ADSP 218x DSPs Compiler Command Line Reference e Verify that the compiler is using the correct file If you do not pro vide the complete path as part of the parameter or add additional search directories cc218x looks for input in the current directory Specifying Compiler Options in VisualDSP When using the VisualDSP IDDE use the Compile tab from the Project Options dialog box to set compiler functional options described on Figure 1 1 Assemble ale F General Preprocessor L Processor Warning BBUTMeauGty sze J opeen
219. ised to zero iir sample i 0x225 0xe10 0x545 0x16a0 to be declared on circular boundary state TAPS 1 index input coeffs TAPS 0x5678 APS 1 0x5432 0x1012 Ox2222 0x3333 0x4444 stateLi 0 a_coeffs b_coeffs state TAPS output with expected VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 3 69 C Run Time Library Reference for i 0 i lt TAPS i if outputli e_outputLli fail print out pass fail message if fail 0 printf Test passed n else printf Test failed n See Also biquad fir 3 70 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library interrupt define interrupt handling Synopsis d Finclude lt signal h gt void interrupt int sig void func int int void interruptf int sig void func int int void interrupts int sig void func Description These functions are Analog Devices extensions to the ANSI standard The interrupt function determines how a signal received during program execution is handled The interrupt function executes the function pointed to by func at every interrupt sig the signal function executes the function only once The different variants of the interrupt functions differentiate between handler dispatching functions The variants will be appropriate for some applications and provide
220. itch is equivalent to including assert name value in your source file and both may be tested in a preprocessor condition in the following manner if tname value do something else do something else endif For example the default assertions may be tested as if machine adsp218x do something endif The parentheses in the assertion should be quoted when using the A switch to prevent misinterpretation No quotes are needed for a assert directive in a source file alttok The alttok alternative tokens switch directs the compiler to allow digraph sequences in C source files bss The bss switch causes the compiler to place global zero initialized data into a BSS style section called bsz rather than into the normal global data section This is default mode See also the no bss switch on page 1 30 VisualDSP 3 5 C Compiler and Library Manual 1 19 for ADSP 218x DSPs Compiler Command Line Reference build lib The build 1ib build library switch directs the compiler to use the elfar librarian to produce a library file d1b as the output instead of using the linker to produce an executable file dxe The o option on page 1 33 must be used to specify the name of the resulting library C The c comments switch which is only active in combination with the E EE ED P or PP switches directs the preprocessor to retain com ments in its output C The c c
221. ites in Loops Other dependencies can be caused by writes to array elements In the fol lowing loop the optimizer cannot determine whether the load from a reads a value defined on a previous iteration or one that will be overwrit ten in a subsequent iteration for C100 i ons PE alij bli alclill Bad has array dependency The optimizer can resolve access patterns where the addresses are expres sions that vary by a fixed amount on each iteration These are known as induction variables for i 0 i lt n i alit4 bli a i Good uses induction variables Inner Loops vs Outer Loops Tip Inner loops should iterate more than outer loops The optimizer focuses on improving the performance of inner loops because this is where most programs spend the majority of their time It is considered a good trade off for an optimization to slow down the code before and after a loop if it is going to make the loop body run faster Therefore try to make sure that your algorithm also spends most of its VisualDSP 3 5 C Compiler and Library Manual 2 19 for ADSP 218x DSPs Loop Guidelines time in the inner loop otherwise it may actually be made to run slower by optimization If you have nested loops where the outer loop runs many times and the inner loop a small number of times it may be possible to rewrite the loops so that the outer loop has the fewer iterations Avoiding Conditional Code in Loops If a loo
222. ithm and understanding their impact is crucial to attaining optimal performance The focus of what follows is on how to obtain maximal code performance from the compiler Most of these guidelines also apply when optimizing for minimum code size although some techniques specific to that goal are also discussed The first section looks at some general principles and how the compiler can lend the most help to your optimization effort Optimal coding styles are then considered in detail Special features such as com piler switches built in functions and pragmas are also discussed The chapter ends with a short example to demonstrate how the optimizer works Small examples are included throughout this chapter to demonstrate points being made Some show recommended coding styles others iden tify styles to be avoided or code that it may be possible to improve These are marked as Good and Bad respectively This chapter contains e General Guidelines on page 2 3 e Loop Guidelines on page 2 17 e Using Built in Functions in Code Optimization on page 2 24 e Smaller Applications Optimizing for Code Size on page 2 27 VisualDSP 3 5 C Compiler and Library Manual 2 1 for ADSP 218x DSPs Pragmas on page 2 29 Useful Optimization Switches on page 2 35 2 2 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Achieving Optimal Performance from C Source Code General Guidelin
223. its would be regarded as an underflow 2 Duplicate sign bit elimination Following a multiplication of two 16 bit values the nature of the representation results in two sign bits in the result For normal integer arithmetic this causes no problem but for fractional arithmetic a shift left by one is required to normalize the result 3 Saturation If we perform an arithmetic operation that would cause us to overflow it can be useful to return the maximum appropri ately signed number that can be represented in the result register The alternatives which include firing an interrupt saying the result is undefined and is some other number usually look less attractive to DSP programmers These fractional operations can often be done at no extra cost to normal integer operations on DSPs using special instructions or modes of operation VisualDSP 3 5 C Compiler and Library Manual 1 87 for ADSP 218x DSPs C Compiler Language Extensions The C programming language does not include a basic type for fractional data and rather than introduce a non standard type Analog Devices defines fract16 and fract32 in terms of appropriately sized integer data types and provides sets of basic intrinsic functions which perform the required operations These look like library function calls but are spe cially recognized by the compilers which generate short sequences or single instructions exploiting any specialized features which may be avail
224. keywords command line switch is used see on page 1 30 the compiler defines shorter forms of the keyword extensions that omit the leading underscores This section describes only the shorter forms of the keyword extensions but in most cases you can use either form in your code For example all references to the inline keyword in this text appear without the leading double underscores but you can use inline or __inline interchangeably in your code You might need to use the longer forms such as __inline exclusively if you are porting a program that uses the extra Analog Devices keywords as identifiers For example a program might declare local variables such as pm or dm In this case you should use the no extra keywords switch and if you need to declare a function as inline or allocate variables to memory spaces you can use __inline or __pm __dm respectively Table 1 5 provides a list and a brief description of keyword extensions Table 1 6 provides a list and a brief description of operational extensions Both tables direct you to sections of this chapter that document each extension in more detail Table 1 5 Keyword Extensions Keyword extensions Description inline function Directs the compiler to integrate the function code into the code of the callers For more information see Inline Function Support Keyword inline on page 1 55 dm Specifies the location of a static or global variable or qualifies
225. l for debugging specific functions without increasing the size or decreasing the performance of the overall application unnecessarily For more information refer to General Optimization Pragmas on page 1 105 Loop Optimization Pragmas Many pragmas are targeted towards helping to produce optimal code for inner loops These are the 1oop_count and no_alias pragmas pragma loop_count The loop_count pragma enables the programmer to inform the compiler about a loop s iteration count The compiler is able to make more reliable decisions about the optimization strategy for a loop if it knows the itera tion count range If you know that the loop count is always a multiple of some constant this can also be useful as it allows a loop to be partially unrolled or vectorized without the need for conditionally executed itera tions Knowledge of the minimum trip count may allow the compiler to omit the guards that are usually required after software pipelining Any of the parameters of the pragma that are unknown may be left blank An example of the use of the 100p_count pragma might be pragma loop_count minimum 40 maximum 100 modulo 4 for i 0 i lt n i ali b i VisualDSP 3 5 C Compiler and Library Manual 2 33 for ADSP 218x DSPs Pragmas Good the loop_count pragma gives compiler helpful information to assist optimization For more information refer to pragma loop_count min max modulo on page
226. l parameter in a macro declaration may be followed by to indi cate the parameter stands for a variable number of arguments For example define trace msg args fprintf stderr msg HF args can be used with differing numbers of arguments trace got here n trace i 4d n i trace x f y 4f n x y The operator has a special meaning when used in a macro definition before the parameter that expands the variable number of arguments if the parameter expands to nothing then it removes the preceding comma The variable argument macro syntax comes from GCC It is not compatible with C99 variable argument macros Line Breaks in String Literals String literals may span many lines The line breaks do not need to be escaped in any way They are replaced by the character n in the generated string The extension is not compatible with many dialects of C including ANSI ISO C89 and C99 However it is useful in asm statements which are intrinsically non portable VisualDSP 3 5 C Compiler and Library Manual 1 121 for ADSP 218x DSPs C Compiler Language Extensions Arithmetic on Pointers to Void and Pointers to Functions Addition and subtraction is allowed on pointers to void and pointers to functions The result is as if the operands had been cast to pointers to char The sizeof operator returns one for void and function types Cast to Union A type cast can be used to create a value of a union type by c
227. lash at the end of the line or by quoting each line separately This is an example of multiple instructions in a template asm Sse exp 41 hi sr norm 1 hi Z0 sr0 e normalized output e Cinval input se srl srO clobbers Assembly Construct Reordering and Optimization For the purpose of optimization the compiler assumes that the side effects of an asm construct are limited to changes in the output operands or the items specified using the clobber specifiers This does not mean that you cannot use instructions with side effects but you must be careful to notify the compiler that you are using them by using the clobber specifiers see Table 1 8 on page 1 66 VisualDSP 3 5 C Compiler and Library Manual 1 67 for ADSP 218x DSPs C Compiler Language Extensions The compiler may eliminate supplied assembly instructions if the output operands are not used move them out of loops or replace two with one if they constitute a common subexpression Also if the instruction has a side effect on a variable that otherwise appears not to change the old value of the variable may be reused later if it happens to be found in a register Use the keyword volatile to prevent an asm instruction from being moved combined or deleted For example define I0write val addr asm volatile si val 1O0 addr si si A sequence of asm volatile constructs is not guaranteed to
228. le 3 17 Symbolic Names Defined in iso646 h Cont d Symbolic Name Equivalent bitand amp bitor comp not not_eq l or or_eq xor A xor_eq Ss locale h The locale h header file contains definitions for expressing numeric monetary time and other data math h This category includes the floating point mathematical functions of the C run time library The mathematical functions are ANSI standard The math h header file contains prototypes for functions used to calculate mathematical properties of single precision floating type variables On the ADSP 218x processors double and float are both single precision float ing point types Additionally some functions support a 16 bit fractional data type The math h file also defines the macro HUGE_VAL HUGE_VAL evaluates to the maximum positive value that the type double can support The macros EDOM and ERANGE defined in errno h are used by math h functions to indicate domain and range errors VisualDSP 3 5 C Compiler and Library Manual 3 9 for ADSP 218x DSPs C Run Time Library Guide Some of the functions in this header file exist as both integer and floating point The floating point functions typically have an f prefix Make sure you are using the correct one The C language provides for implicit type conversion so the fol lowing sequence produces surprising results with no warnings float x y y abs x
229. le as defined by those registers Preserved registers can be used their contents will not be changed by call ing a C function The function will always save and restore the contents of preserved registers if they are going to change VisualDSP 3 5 C Compiler and Library Manual 1 151 for ADSP 218x DSPs C and Assembly Language Interface If arguments are on the stack they are addressed via an offset from the stack pointer or frame pointer Explore how arguments are passed between an assembly language program and a function by writing a dummy func tion in C and compiling it with the save temporary files option the save temps switch on page 1 39 By examining the contents of volatile global variables in s file you can determine how the C function passes arguments and then duplicate that argument setup process in the assem bly language program The stack must be set up correctly before calling a C callable function If you call other functions maintaining the basic stack model also facilitates the use of the debugger The easiest way to do this is to define a C main program to initialize the run time system maintain the stack until it is needed by the C function being called from the assembly language pro gram and then continue to maintain that stack until it is needed to call back into C However make sure the dedicated registers are correct You do not need to set the FP prior to the call the caller s FP is never used by t
230. ler Command Line Reference Table 1 2 Compiler Command Line Switches Contd Switch Name Description Wterse Issues only the briefest form of compiler warnings errors on page 1 45 and remarks wW Does not display compiler warning messages on page 1 45 warn protos Produces a warning when a function is called without a pro on page 1 45 totype write files Enables compiler I O redirection on page 1 45 write opts Passes the user options but not input filenames via a tem on page 1 45 orary file pag porary xref filename Outputs cross reference information to the specified file on page 1 46 The following sections provide detailed comman line switch descriptions filename The filename command file switch directs the compiler to read command line input from filename The specified filename must contain driver options but may also contain source filenames and environment variables It can be used to store frequently used options as well as to read from a file list A name tokens The A assert switch directs the compiler to assert name as a predicate with the specified tokens This has the same effect as the fassert prepro cessor directive The following assertions are predefined system embedded machine adsp218x 1 18 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler cpu adsp218x compiler cc218x The A name value sw
231. les automatic function inlining Optimize for code size 0v num on page 1 33 Controls speed vs size optimizations o filename on page 1 33 Specifies the output file name P on page 1 34 Preprocesses but does not compile the source file Omits line numbers in the preprocessor output PP on page 1 34 Similar to P but does not halt compilation after preprocess ing path asm compiler def 1ib link mem filename on page 1 34 Use the specified component in place of the default installed version of a compilation tool path install directory on page 1 34 Uses the specified directory as the location of all compilation tools path output directory on page 1 35 Specifies the location of non temporary files path temp directory on page 1 35 Specifies the location of temporary files pch on page 1 35 Generates and uses precompiled header files pch VisualDSP 3 5 C Compiler and Library Manual 1 15 for ADSP 218x DSPs Compiler Command Line Reference Table 1 2 Compiler Command Line Switches Contd Switch Name Description pchdir directory on page 1 35 Specifies the location of PCHRepository pedantic on page 1 35 Issues compiler warnings for any constructs that are not strictly ISO ANSI standard C compliant pedantic errors on page 1 36 Issues compiler errors for any const
232. ll stop the scan Error Conditions The atof function returns a zero if no conversion could be made If the correct value results in an overflow a positive or negative as appropriate HUGE_VAL is returned If the correct value results in an underflow 0 0 is returned The ERANGE value is stored in errno in the case of either an over flow or underflow Notes The function reference atof pdata is functionally equivalent to strtod pdata char NULL and therefore if the function returns zero it is not possible to determine whether the character string contained a valid representation of 0 0 or some invalid numerical string Example d Finclude lt stdlib h gt double x xX atof 5 5 x 5 5 VisualDSP 3 5 C Compiler and Library Manual 3 27 for ADSP 218x DSPs C Run Time Library Reference See Also atoi atol strtod 3 28 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library atoi convert string to integer Synopsis include lt stdlib h gt int atoi const char nptr Description The atoi function converts a character string to an integer value The character string to be converted is pointed to by the input pointer nptr The function clears any leading characters for which isspace would return true Conversion begins at the first digit with an optional preceding sign and terminates at the first non digit Error Conditions The atoi function returns
233. long l je z ifdef _ DOUBLES_ARE_FLOATS u 1 0xFF800000L if isinf u d 0 fail u 1 0xFF800001L if isinf u d 0 fail u 1 0x7F800000L if isinf u d 0 fail u 1 0x7F800001L if isinf u d 0 fail endif 3 84 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library test int isinff float u 1 OxFF800000L if isinff u f 0 fail u 1 OxFF800001L if isinff u f 0 fail u 1 O0x7F800000L if isinff u f 0 fail u 1 Ox7F800001L if isinff u f 0 fail print pass fail message if fail printf Test passed n else printf Test failed 4d n fail See Also isnan VisualDSP 3 5 C Compiler and Library Manual 3 85 for ADSP 218x DSPs C Run Time Library Reference islower detect lowercase character Synopsis include lt ctype h gt int islower int c Description The islower function determines if the argument is a lowercase character a z If the argument is not lowercase is lower returns a zero If the argu ment is lowercase islower returns a non zero value Error Conditions The islower function does not return any error conditions Example include lt ctype h gt int ch for ch 0 ch lt Ox7f ch printf 04x ch printf 2s islower ch lowercase putchar n See Also isalpha isupper 3 86 VisualDSP 3 5 C Compiler and Li
234. longs fract32 Mpy_32 fractl6 fractl6 fractl6 fractl6 This function performs the multiplication of two fract32 type variables provided as high and low half parameters The result returned is calculated as Res L_mult hil hi2 Res L_mac Res mult hil lo2 1 Res L_mac Res mult lol hi2 1 Multiply short by a long fract32 Mpy_32_16 fractl6 fractl6 fractl6 Extract a long from two shorts void L_Extract fract32 src fractl6 hi fractl6 lo This function extracts low and high halves of fract32 type value into fractl6 variables pointed to by the parameters hi and 10 The values cal culated are Hi bitl6 to bit3l of src Lo sre hi lt lt 16 gt gt 1 1 98 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Fract integer division of two longs fract32 Div_32 fract32 L_num fractl6 denom_hi fractl6 denom_lo This is 32 bit fractional divide operation The result returned is the fract32 representation of L_num divided by L_denom represented by demon_hi and denom_lo L_num and L_denom must both be positive frac tional values and L_num must be less that L_denom to ensure that the result falls within the fractional range Pragmas The compiler supports a number of pragmas Pragmas are implementa tion specific directives that modify the compiler s behavior There are two types of pragma usage pragma directives and pragma operators Pragma directives have the following syntax
235. lude lt ctype h gt int isprint int c Description The isprint function determines if the argument is a printable character 0x20 0x7E If the argument is not a printable character isprint returns a zero If the argument is a printable character isprint returns a non zero value Error Conditions The isprint function does not return any error conditions Example include lt ctype h gt int ch for ch 0 ch lt Ox7f ch printf 04x ch printf 3s isprint ch printable putchar n See Also isgraph isspace VisualDSP 3 5 C Compiler and Library Manual 3 89 for ADSP 218x DSPs C Run Time Library Reference ispunct detect punctuation character Synopsis include lt ctype h gt int ispunct int c Description The ispunct function determines if the argument is a punctuation charac ter If the argument is not a punctuation character ispunct returns a zero If the argument is a punctuation character ispunct returns a non zero value Error Conditions The ispunct function does not return any error conditions Example dFinclude lt ctype h gt int ch for ch 0 ch lt 0x7f cht printf 04x ch printf 43s ispunct ch punctuation putchar n See Also isalnum 3 90 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library isspace detect whitespace character Synopsis include lt ctyp
236. lves when linking This tells the linker to be directed to link with the ETSI library libetsi d1b in the 218x lib directory which is a subdirectory of the VisualDSP installation directory This is done automatically when using the default Linker Description File LDF for ADSP 218x DSP tar gets as these specify that 1ibetsi d1b will be on each link line VisualDSP 3 5 C Compiler and Library Manual 1 89 for ADSP 218x DSPs C Compiler Language Extensions If not using default LDF files then either add libetsi d1b to the LDF file which is being used or alternatively use the compiler s letsi switch to specify that 1ibetsi dib is to be added to the link line Working with ETSI Library Source Code The source code for functions and macros in the ETSI library is provided with your VisualDSP software By default the installation program copies the source code to a subdirectory of the directory where the run time libraries are kept named 218x 1ib src libetsi_src Each func tion is kept in a separate file The file name is the name of the function with the extension asm If you do not intend to modify any of the func tions you can delete this directory and its contents to conserve disk space The source code is provided so you can customize specific functions for your own needs To modify these files you need proficiency in ADSP 218x assembly language and an understanding of the run time environment as explained in C and Ass
237. me extension may also help The compiler optimizer may have moved code around so that it does not appear in the same order as in your original source Using Interprocedural Optimization To obtain the best performance the optimizer often requires information that can only be determined by looking outside the function that it is working on For example it helps to know what data can be referenced by pointer parameters or whether a variable actually has a constant value The ipa compiler switch on page 1 26 enables interprocedural analysis VisualDSP 3 5 C Compiler and Library Manual 2 5 for ADSP 218x DSPs General Guidelines IPA which can make this available When this switch is used the com piler will be called again from the link phase to recompile the program using additional information obtained during previous compilations Because it only operates at link time the effects of IPA will not be seen if you compile with the S switch on page 1 38 To see the assembly file when IPA is enabled use the save temps switch on page 1 39 and look at the s file produced after your program has been built As an alternative to IPA you can achieve many of the same benefits by adding pragma directives and other declarations such as __builtin_aligned to provide information to the compiler about how each function interacts with the rest of the program These directives are further described Using Built in Functions in Code Op
238. me string When the string contains no further tokens NULL is returned Each new call to strtok may use a new delimiter string even if s1 is NULL in which case the remainder of the string is tokenized using the new delimiter characters Error Conditions The strtok function returns a null pointer if there are no tokens remain ing in the string Example d Finclude lt string h gt static char str a phrase to be tested today char t t strtok str t points to a KJ t strtok NULL t points to phrase 3 146 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library t strtok NULL t points to to be tested t strtok NULL t points to today af t strtok NULL t NULL Af See Also No references to this function VisualDSP 3 5 C Compiler and Library Manual 3 147 for ADSP 218x DSPs C Run Time Library Reference strtol convert string to long integer Synopsis Finclude lt stdlib h gt long int strtol const char nptr char endptr int base Description The strtol function returns as a long int the value that was represented by the string nptr If endptr is not a null pointer strtol stores a pointer to the unconverted remainder in endptr The strtol function breaks down the input into three sections white space as determined by isspace the initial characters and unrecognized characters including a term
239. meters are passed on the stack A good way to observe and understand how argu ments are passed is to write a dummy function in C and compile it using the save temps command line switch on page 1 39 The resulting compiler generated assembly file s can then be viewed VisualDSP 3 5 C Compiler and Library Manual 1 149 for ADSP 218x DSPs C and Assembly Language Interface The following example includes the global volatile variable assign ments to indicate where the arguments can be found upon entry to asmfunc Sample file for exploring compiler interface global variables assign arguments there just so we can track which registers were used type of each variable corresponds to one of arguments int global_a float global_b int global_p the function itself int asmfunc int a float b int p int d int e do some assignments so that s file will show where args are global_a a global_b b global_p p value gets loaded into the return register return 12345 When compiled with the save temps option set see on page 1 39 this produces the following PROCEDURE _asmfunc global _asmfunc _asmfunc SI DM I4 4 I0 SI AX1 DM I4 2 SI DM I4 1 AXO DM I4 3 DM _global_b AX1 DM _global_a SI DM _global_bt 1 AXO 1 150 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler RTS DB AX1
240. mpiler to see that an automatic scalar whose address is not taken may be held in a register during a loop But it is not as easy when the variable is a global or a function static Therefore code such as for i 0 i lt globvar i a i 10 Bad may need to reload globvar on every iteration may not create a hardware loop if the compiler cannot be sure that the write into the array a does not change the value of the global variable The globvar must be re loaded each time around the loop before performing the exit test In this circumstance the programmer can make the compiler s job easier by writing int upper_bound globvar for i 0 i lt upper_bound i ali 10 Good easily becomes hardware loop Using the Restrict Qualifier The restrict qualifier provides one way to help the compiler resolve pointer aliasing ambiguities Accesses from distinct restricted pointers do not interfere with each other The loads and stores in the following loop for i 0 i1 lt 100 i ali bli Bad possible alias of arrays a and b 2 22 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Achieving Optimal Performance from C Source Code may be disambiguated by writing int restrict p a int restrict g for i 0 1 lt 100 i Psp KAFR Good restrict qualifier tells compiler that memory accesses do not alias The restrict keyword is particularly useful on function parameters Usin
241. n int value sysreg_read sysreg_IMASK See Also disable_interrupts enable_interrupts io_space_read io_space_write sysreg_write VisualDSP 3 5 C Compiler and Library Manual 3 155 for ADSP 218x DSPs C Run Time Library Reference sysreg_write write to non memory mapped register Synopsis include lt sysreg h gt void sysreg_write const int const unsigned int Description The sysreg_write function causes the compiler to emit instructions to write the non memory mapped register which is passed as the first param eter with the value passed as the second parameter The first parameter for sysreg_write should be a member of the SysReg enumeration defined in sysreg h This enumeration is used to map the non memory mapped actual registers to a small constant which is defined as a user friendly name The enumerated variables defined are sysreg_ASTA arithmetic status sysreg_SSTA shifter status sysreg_MSTA multiplier status sysreg_ICNTL interrupt control sysreg_IMASK interrupts enabled mask sysreg_IFC interrupt force and clear The sysreg_write function is implemented as a compiler built in the emitted instructions will be inlined at the point of sysreg_write use The inclusion of the sysreg h include file is mandatory when using sysreg_write Error Conditions The sysreg_write function does not return raise or set any error conditions 3 156 VisualDSP 3 5 C Compiler and Librar
242. n Data Types on page 2 7 The hardware does not provide direct support for division so division and modulus operations are almost always multi cycle operations even on integral type inputs If the compiler has to issue a full division operation it will usually need to generate a call to a library function One notable sit uation in which a library call is avoided is for integer division when the divisor is a compile time constant and is a power of two In that case the compiler generates a shift instruction Even then a few fix up instructions are needed after the shift if the types are signed If you have a signed divi sion by a power of two consider whether you can change it to unsigned in order to obtain a single instruction operation When the compiler has to generate a call to a library function for one of these arithmetic operators that are not supported by the hardware perfor mance will suffer not only because the operation will take multiple cycles but also because the effectiveness of the compiler optimizer will be reduced For example such an operation in a loop can prevent the compiler from making use of efficient zero overhead hardware loop instructions Also calling the library to perform the required operation can change values held in scratch registers before the call so the compiler will have to gener ate more stores and loads from the data stack to keep values required after the call returns Emulated arithmetic
243. n array element and should return a value less than equal to or greater than zero according to whether the first parameter is less than equal to or greater than the second The bsearch function returns a pointer to the first occurrence of key in the array Error Conditions The bsearch function returns a null pointer if the key is not found in the array 3 34 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Example d Finclude lt stdlib h gt char answer char base 50 3 answer bsearch g base 50 3 See Also qsort C Run Time Library VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 3 35 C Run Time Library Reference calloc allocate and initialize memory Synopsis d Finclude lt stdlib h gt void calloc size_t nmemb size_t size Description The calloc function returns a pointer to a range of dynamically allocated memory that has been initialized to zero The number of elements the first argument multiplied by the size of each element the second argu ment is the total memory allocated The memory may be deallocated with the free function Error Conditions The calloc function returns a null pointer if unable to allocate the requested memory Example d Finclude lt stdlib h gt int ptr ptr int calloc 10 sizeof int ptr points to a zeroed array of length 10 See Also free malloc realloc 3 36 VisualDSP 3 5
244. n of a pointer and specifies that the pointer provides exclusive initial access to the object to which it points More simply restrict is a way that you can identify that a pointer does not create an alias Also two different restricted pointers can not designate the same object and therefore are not aliases The compiler is free to use the information about restricted pointers and aliasing in order to better optimize C code that uses pointers VisualDSP 3 5 C Compiler and Library Manual 1 77 for ADSP 218x DSPs C Compiler Language Extensions The restrict keyword is most useful when applied to function parameters about which the compiler would otherwise have little information For example void fir short in short c short restrict out int n The behavior of a program is undefined if it contains an assignment between two restricted pointers except for the following cases e A function with a restricted pointer parameter may be called with an argument that is a restricted pointer e A function may return the value of a restricted pointer that is local to the function and the return value may then be assigned to another restricted pointer If your program uses a restricted pointer in a way that it does not uniquely refer to storage then the behavior of the program is undefined Variable Length Array Support The compiler supports variable length automatic arrays Unlike other automatic arrays variable length ones are de
245. n re 1 43 E E E E E E EEN 1 43 Wd river imit nam Der cerasina anie 1 44 Weron COUDE rr a 1 44 W error remark suppress warn lt num gt num sessssssssse 1 44 a E E E een A 1 44 a AEE E AET E toes 1 45 SUE E E E EE ea eon E E 1 45 E E E E 1 45 a E E N E P E 1 45 SES n a abaemeol Anabaena 1 45 EE EA a AEA 1 46 Da TPE S ar a R R 1 47 Optimization Control cst cagsuiaaenoreecinetsesratecranganeaetinsacnians 1 49 Taterprocediral ANAS corcsonrrnrres innr 1 50 C Compiler Language Extensigns ieee 1 52 Inline Function Support Keyword inline ccsccccsssecsscsseecsvesces 1 55 Inline Assembly Language Support Keyword asm 44 1 56 Assembly Construct Template serisinin eisie 1 57 ASMO Construct Syota cssissiircaciaciionnmsiircnsinnciiens 1 57 Foi Construct Syara Rilet on ceteris 1 59 viii VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs CONTENTS ASMO Construct Template Example secicccssicsasesdencanereaes 1 60 Assembly Construct Operand Description sssssrississriisrsa 1 61 Assembly Constructs With Multiple Instructions 1 67 Assembly Construct Reordering and Optimization 1 67 Assembly Constructs with Input and Output Operands 1 68 Assembly Constructs and Macros ciicticsertenionneactnrieoned 1 70 Assembly Constructs and Flow Control sssccccsssseeneees 1 70 Dual Memory Support Keywords pm dm sesser 1 71 Memory Keywords and Assignments Type Conversions
246. nction returns a 1 if the parameter is not a valid signal and a zero in all other cases 3 38 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library Example d Finclude lt signal h gt clear_interrupt SIGTIMER clears the timer clear bit in IFC See Also interrupt raise signal VisualDSP 3 5 C Compiler and Library Manual 3 39 for ADSP 218x DSPs C Run Time Library Reference copysign copy the sign Synopsis dFinclude lt math h gt double copysign double parml double parm2 float copysignf float parml float parm2 fractl6 copysign_frl6 fractl6 parml fractl6 parm2 Description This function copies the sign of the second argument to the first argument Algorithm return parml copysignof parm2 Domain Full Range for type of parameters used 3 40 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library cos cosine Synopsis include lt math h gt double cos double float cosf float fractl6 cos_frl6 fractl6 Description The cos function returns the cosine of the argument The input is inter preted as radians the output is in the range 1 1 The cos_fri6 function inputs a fractional value in the range 1 0 1 0 corresponding to 7 2 1 2 The domain represents half a cycle which can be used to derive a full cycle if required see Notes below The result in radians is in the
247. nd is in the same place as another operand Just because a variable for example shoe in the code that follows is used for more than one operand does not guar antee that the operands are in the same place in the generated assembler code Do NOT try to control placement with operand names use the digit The following code might NOT work asm modify 0 42 w shoe w shoe x sock In some cases operands 0 and 1 could be stored in different registers due to reloading or optimizations Be aware that asm does not support input operands that are used as both read operands and write operands The following example shows a danger ous use of such an operand In this example my_variable is modified during the asm operation The compiler only knows that the output result_asm has changed Subsequent use of my_variable after the asm instruction may yield incorrect results since those values may have been modified during the asm instruction and may not have been restored int result_asm int my_variable NOT recommended pseudo code result_asm dm my_variable M3 asm operation changes value of my_variable Rif asm 40 DM 41 M3 e result_asm w my_variable VisualDSP 3 5 C Compiler and Library Manual 1 69 for ADSP 218x DSPs C Compiler Language Extensions Assembly Constructs and Macros A way to use asm constructs is to encapsulate them in macros that look l
248. ndefine macro 1 42 unsigned bitfield make plain bitfields unsigned 1 42 unsigned char make char unsigned 1 43 v version and verbose 1 43 val global add global names 1 43 verbose display command line 1 43 version display version 1 43 w display all warnings 1 45 W override error messages 1 44 warns protos prototypes warning 1 45 Wdriver limit maximum process errors 1 44 Werror limit maximum compiler errors 1 44 Wremarks enable diagnostic warnings 1 44 write files enable driver I O redirection 1 45 write opts 1 45 Wterse terse warnings 1 45 xref file cross reference list 1 46 compound statements with in expressions support compiler 1 79 conditional code in loops 2 20 conditional expressions with missing operands 1 120 const keyword 2 23 pointers 1 20 qualifier 2 23 const read write compiler switch 1 20 const read write flag 2 23 constructs flow control 1 70 1 6 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs control character test see iscntrl function controlling header files with pragmas 1 115 interrupts 1 85 optimization 1 49 convert characters see tolower toupper functions strings see atof atoi atol strtok strtol strtoul functions copying characters between overlapping objects 3 105 characters from one object to another 3 104 copysign 3 40 cos cosine function 3 41 cos_fr16 function 3 41 cosh hyperbolic cosine func
249. nditions The frexp function does not return an error condition Example d Finclude lt math h gt double y int exponent y frexp 2 0 amp exponent y 0 5 exponent 2 See Also modf 3 62 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs ifftN C Run Time Library N point inverse complex input fast Fourier transform IFFT Synopsis include lt fft int ifft1024 ESS 9S tact Q r int SS Shy t ct int So SS Sh c gt D a G int A a Sh ct aaah int Soto eh c ct h ct an P int me e Sy t ct h ct Qa WwW Do y ct m aD int DUD aaa Sh ct a a s h gt int dm real_inputl ag_inputL eal_outputl ag_outputL nt dm real_inputL ag_inputL eal_outputl ag_outputL int dm real_input imag_inputL eal_outputl ag_outputLl int dm real_input ag_inputL eal_outputLl ag_outputL int dm real_inputl ag_inputL eal_outputl imag_output int dm real_inputl ag_inputL eal_outputl imag_output int dm real_inputl ag_inputL eal_outputl imag_outputl VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 3 63 C Run Time Library Reference int ifft8 int dm real_inputl int dm imag_inputl int dm real_outputl int dm imag_outputl Description These functions are Analog Devices
250. ne Some programs may not have any declarations of external assembly lan guage functions This is not good programming practice and should be fixed The effect of the 01dAsmCal1 declaration is as follows e Pass the first two arguments in registers AR and AY1 The C run time stack for compatibility calls is normally used to pass the third and subsequent parameters to a called function This changes if either of the first two parameters is a multi word param eter in which case it and all subsequent parameters are passed on the stack Functions that take variable arguments varargs func tions will have the last named parameter and subsequent parameters passed on the stack e Postpend an underscore onto the external name e Look in the AR register instead of AX1 for a one word return value VisualDSP 3 5 C Compiler and Library Manual 1 157 for ADSP 218x DSPs C and Assembly Language Interface The 01dAsmCal1 extern declaration can encompass one or more prototypes that define external entry points as shown in the following example extern OldAsmCall int libfn int flag int a void resetmach int idle 1 158 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 2 ACHIEVING OPTIMAL PERFORMANCE FROM C SOURCE CODE This chapter provides guidance to help you to tune your application to achieve the best possible code from the compiler Some implementation choices are available when coding an algor
251. ng the macros SPACE1 and SPACE2 Dual Memory Support Keywords amp Macros itdefine SPACE1 pm itdefine SPACE2 dm char pm foo char dm char SPACE1 foo char SPACE2 char pm x char SPACE1 x char dm y char SPACE2 y x foo amp y x foo amp y PM and DM Compiler Support for Standard C Library Functions There are a number of functions defined in the standard C library that take pointer input parameter types These functions which include for example strlen are implemented differently when the pointer input is to program memory PM or data memory DM The different imple mentations are called automatically by the compiler because it has specific in built knowledge about the standard C functions that require pointer parameters The support requires that the normal standard header file for example string h is included prior to use of the function requiring PM and DM variants The default library function variants are DM should the include file not be used Placement Support Keyword section The section keyword directs the compiler to place an object or function in an assembly SECTION in the compiler s intermediate assembly output file You name the assembly SECTION with section s string literal parameter If you do not specify a section for an object or function declaration the compiler uses a default section The LDF file supplied to the linker must also be updated to support the additional name
252. ns a zero if successful a non zero value if it fails Example include lt signal h gt raise SIGABRT See Also interrupt signal 3 112 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs rand random number generator Synopsis d include lt stdlib h gt int rand void Description C Run Time Library The rand function returns a pseudo random integer value in the range 0 215 1 For this function the measure of randomness is its periodicity the num ber of values it is likely to generate before repeating a pattern The output of the pseudo random number generator has a period in the order of 919 2 1 Error Conditions The rand function does not return an error condition Example include lt stdlib h gt int i i rand See Also srand VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 3 113 C Run Time Library Reference realloc change memory allocation Synopsis include lt stdlib h gt void realloc void ptr size_t size Description The realloc function changes the memory allocation of the object pointed to by ptr to size Initial values for the new object are taken from those in the object pointed to by ptr If the size of the new object is greater than the size of the object pointed to by ptr then the values in the newly allocated section are undefined If ptr is a non null pointer that was not allocated with malloc or calloc
253. ns for Symbols In The C Program In The Assembly Subroutine int c_var extern _c_var declared global void c_func extern _c_func extern int asm_var global _asm_var extern void asm_func global _asm_func _asm_func extern asm void asm_func global asm_func asm_func Compatibility Call The cc218x compiler in VisualDSP 3 5 produces code that is not fully compatible with the Release 6 1 run time model However the new com piler is superior in many ways to the old one and your programs will be faster smaller and more reliable after the C code is converted to the new system 1 156 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler The cc218x compiler provides a compatibility call to enable usage of exist ing libraries and special purpose assembly language subroutines with the new compiler This feature is available with a small amount of source code modification by adding an extern OldAsmCall specification to the prototype in the source program similar to what is done when calling between C and C source programs There is no compiler option for compatibility calls This feature provides full compatibility with the following restrictions e You cannot mix old and new compiled modules e Old code is not allowed to call into a new compiled module e A procedure pointer from a new compiled module is not allowed as an argument to an old routi
254. ns may require implicit calls to library functions For more details see Data Types on page 2 7 Avoiding Non Unit Strides If you write a loop such as for i 0 i lt n i 3 some code Bad non unit stride means division may be required then in order for the compiler to turn this into a hardware loop it will need to work out the loop trip count To do so it must divide n by 3 The compiler will decide that this is worthwhile as it will speed up the loop but as discussed above division is an expensive operation Try to avoid creating loop control variables with strides of non unit magnitude Loop Control i Tip Use int types for loop control variables and array indices i Tip Use automatic variables for loop control and loop exit test For loop control variables and array indices it is always better to use signed ints rather than any other integral type The C standard requires various type promotions and standard conversions that complicate the code for the compiler optimizer Frequently the compiler is still able to VisualDSP 3 5 C Compiler and Library Manual 2 21 for ADSP 218x DSPs Loop Guidelines deal with such code and create hardware loops and pointer induction vari ables However it does make it more difficult for the compiler to optimize and may occasionally result in under optimized code The same advice goes for using automatic local variables for loop con trol It is easy for a co
255. nst char sl const char s2 Description The strstr function returns a pointer to the first occurrence in the string pointed to by s1 of the characters in the string pointed to by s2 This excludes the terminating null character in s1 Error Conditions If the string is not found strstr returns a null pointer If s2 points to a string of zero length s1 is returned Example d Finclude lt string h gt char ptrl ptr2 ptrl TESTING ptr2 strstr ptrl E ptr2 points to the E in TESTING See Also strchr VisualDSP 3 5 C Compiler and Library Manual 3 139 for ADSP 218x DSPs C Run Time Library Reference strtod convert string to double Synopsis include lt stdlib h gt double strtod const char nptr char endptr Description The strtod function extracts a value from the string pointed to by nptr and returns the value as a double The strtod function expects nptr to point to a string that represents either a decimal floating point number or a hexadecimal floating point number Either form of number may be pre ceded by a sequence of whitespace characters as determined by the isspace function that the function ignores A decimal floating point number has the form sign digits digits e E sign digits The sign token is optional and is either plus or minus and dig its are one or more decimal digits The sequence of digits may contain a decimal point
256. nstants in the writable data segment Removed String constants are placed in the seg_datal section Defini tion in the LDF file can place this section in RAM or ROM module imacros Process macro file Removed MD MM and MMD Output rules for the make util Removed ity used with E mboot page Specify boot page Removed The ADSP 218x DSP does not support paging mdmdata Specify architecture file seg Removed mpmdata ments You can control placement of mdcode object file segments using the SECTION directive in the LDF file mlistm Merge C code with assem Removed bler generated code mno doloops Don t generate loop structures Removed in assembled code mno inits Don t initialize variables in Removed assembled code mpjump Place the jump table in pm Replaced with memory jump dm pm mreserved Instructs the compiler not to Replaced with reserve use specified registers mrom Make the module a ROM Removed msmall code Optimize for size not for speed Replaced with 0s A 6 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Legacy Support Table A 1 Obsolete and Replaced Switches Contd Switch Name Operation under Change for Release 6 1 VisualDSP 3 5 mstatic spil Use dm memory when all regis Removed ter are used nostdinc Do not search standard system Replaced with no
257. nt number may either be of the form of a decimal floating point number or a hexadecimal floating point number A decimal floating point number has the form sign digits digits e E sign digits The sign token is optional and is either plus or minus and digits are one or more decimal digits The sequence of digits may contain a decimal point The decimal digits can be followed by an exponent which consists of an introductory letter e or E and an optionally signed integer If neither an exponent part nor a decimal point appears a decimal point is assumed to follow the last digit in the string The form of a hexadecimal floating point number is sign 0x 0X hexdigs hexdigs p P sign digits 3 26 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library A hexadecimal floating point number may start with an optional plus or minus followed by the hexadecimal prefix 0x or 0X This character sequence must be followed by one or more hexadecimal characters that optionally contain a decimal point The hexadecimal digits are followed by a binary exponent that consists of the letter p or P an optional sign and a non empty sequence of decimal digits The exponent is interpreted as a power of two that is used to scale the fraction represented by the tokens hexdigs hexdigs The first character that does not fit either form of number wi
258. ny order by specifying the array indices or structure field names to which they apply All index values must be constant expres sions even in automatic arrays For an array initializer the syntax INDEX appearing before an initializer element value specifies the index to be initialized by that value Subse quent initializer elements are then applied to sequentially following elements of the array unless another use of the INDEX syntax appears The index values must be constant expressions even if the array being ini tialized is automatic 1 80 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler The following example shows equivalent array initializers the first in standard C and the next using the extension Note that the index pre cedes the value being assigned to that element Example 1 Standard C amp cc218x C Array Initializer Standard C array initializer int abcl6 0 0 12 0 14 0 equivalent cc218x C array initializer int abcl6 3 12 5 14 You can combine this technique of naming elements with standard C ini tialization of successive elements The standard C and cc218x instructions below are equivalent Note that any unlabeled initial value is assigned to the next consecutive element of the structure or array Example 2 Standard C amp cc218x C Array Initializer Standard C array initializer int abc 6 0 5 6 0 12 0 e
259. od sets for a and b do not intersect a and b are not aliases fn globl glob2 N fn glob3 globl N Bad sets intersect both a and b may access glob1 a and b may be aliases The third case arises because IPA considers the union of all calls at once rather than considering each call individually when determining whether there is a risk of aliasing If each call were considered individually IPA would have to take flow control into account and the number of permuta tions would make compilation time impracticably long The lack of control flow analysis can also create problems when a single pointer is used in multiple contexts For example it is better to write int p a4 int tgp some use of p some use of q VisualDSP 3 5 C Compiler and Library Manual 2 11 for ADSP 218x DSPs General Guidelines Good p and q do not alias than int p a some use of p p b some use of p Bad uses of p in different contexts may alias because the latter may cause extra apparent aliases between the two uses Indexed Arrays vs Pointers C allows a program to access data from an array in two ways either by indexing from an invariant base pointer or by incrementing a pointer These two versions of vector addition illustrate the two styles Style 1 using indexed arrays void va_ind const short aL const short b short out int n int i for i 0 i lt n i outLi a i b i Style
260. ode for compiler syntax errors but does not write any output sysdefs on page 1 41 Defines the system definition macros T filename on page 1 41 Specifies the Linker Description File time on page 1 41 Displays the elapsed time as part of the output information on each part of the compilation process Umacro on page 1 42 unsigned bitfield on page 1 42 Undefines macro Treats bitfields which have not been declared with use of signed or unsigned keyword as unsigned unsigned char on page 1 43 Makes the char data type unsigned Vv on page 1 43 Displays both the version and command line information val global lt name list gt on page 1 43 Adds global names verbose on page 1 43 Displays command line information version on page 1 43 Wdriver limit number on page 1 44 Displays version information Halts the driver after reaching the specified number of errors Werror limit number on page 1 44 Stops compiling after reaching the specified number of errors error remark suppress warn lt num gt num on page 1 44 Overrides the severity of compilation diagnostic messages Wremarks on page 1 44 Indicates that the compiler may issue remarks which are diagnostic messages even milder than warnings VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 1 17 Compi
261. odified or removed extensions you must revise your code in order to rebuild your project e The run time model has changed If you call a Release 6 1 assem bly language subroutine from your C program you must revise the assembly code to comply with the new rules for the C run time environment e The Architecture File ACH is no longer supported If you re link using your Release 6 1 object files or object libraries you must cre ate a Linker Description File for each object or object library before using the new linker The remainder of this section describes these and other known differences between VisualDSP Releases 6 1 and VisualDSP 3 5 It also provides assistance when possible to make transformation to the new software easier A 2 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Legacy Support C Compiler and C Run Time Library The new cc218x compiler provided in VisualDSP 3 5 does not support some switches and extensions that were available in the g21 compiler As a result the compiler supports a set of new rules for the run time environ ment This section lists the extensions and switches that have been removed replaced or whose function works differently than in Release 6 1 For further details about the cc218x compiler see Chapter 1 Compiler Segment Placement Support Keyword Changed to Section The segment placement keyword has changed to section The section constru
262. oes not return an error condition Example include lt ctype h gt int ch for ch 0 ch lt Ox7f ch printf 04x ch if isupper ch printf tolower 04x tolower ch putchar n See Also islower isupper toupper VisualDSP 3 5 C Compiler and Library Manual 3 163 for ADSP 218x DSPs C Run Time Library Reference toupper convert from lowercase to uppercase Synopsis include lt ctype h gt int toupper int c Description The toupper function converts the input character to uppercase if it is in lowercase otherwise it returns the character Error Conditions The toupper function does not return an error condition Example dFinclude lt ctype h gt int ch for ch 0 ch lt 0x7f ch printf 04x ch if islower ch printf toupper 04x toupper ch putchar n See Also islower isupper tolower 3 164 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library va_arg get next argument in variable length list of arguments Synopsis Finclude lt stdarg h gt void va_arg va_list ap type Description The va_arg macro is used to walk through the variable length list of argu ments to a function After starting to process a variable length list of arguments with va_start call va_arg with the same va_list variable to extract arguments from the list Each call to va_arg returns a new argument from the list
263. ograms and how to call C functions from within assembly language programs Before attempting to do either of these be sure to familiarize yourself with the information about the C run time model including details about the stack data types and how arguments are han dled in C Run Time Model and Environment on page 1 132 This section contains e Calling Assembly Subroutines from C Programs e Calling C Routines from Assemby Programs on page 1 151 e Using Mixed C Assembly Naming Conventions on page 1 155 e Compatibility Call on page 1 156 Calling Assembly Subroutines from C Programs Before calling an assembly language subroutine from a C program create a prototype to define the arguments for the assembly language subroutine and the interface from the C program to the assembly language subrou tine Even though it is legal to use a function without a prototype in C prototypes are a strongly recommended practice for good software engi neering When the prototype is omitted the compiler cannot perform argument type checking and assumes that the return value is of type inte ger and uses K amp R promotion rules instead of ANSI promotion rules The run time model defines some registers as scratch registers and others as preserved or dedicated registers Scratch registers can be used within the assembly language program without worrying about their previous con tents If more room is needed or an existing code is
264. ol strxfrm functions string functions compare characters in 3 134 copy characters 3 135 memchar 3 102 memmove 3 105 strchr 3 126 strcoll 3 128 strcspn 3 130 strerror 3 131 string length 3 132 strpbrk 3 136 strrchr 3 137 3 138 strspn 3 138 strstr 3 139 strtok 3 146 strxfrm 3 152 string literals with line breaks 1 121 string h header file 3 12 strings converting to double 3 140 strlen string length function 3 132 strncat concatenate characters from one string to another function 3 133 strncmp compare characters in strings function 3 134 VisualDSP 3 5 C Compiler and Library Manual I 21 for ADSP 218x DSPs INDEX strncpy copy characters from one string to another function 3 135 strpbrk find character match in two strings function 3 136 strrchr find last occurrence of character in string function 3 137 strspn length of segment of characters in both strings function 3 138 strstr find string within string function 3 139 strtod convert string to double function 3 140 strtok convert string to tokens function 3 146 strtol convert string to long integer function 3 148 strxfrm transform string using LC_COLLATE function 3 152 syntax only just check syntax compiler switch 1 40 sysdef system definitions compiler switch 1 41 sysreg h header file 1 84 2 25 3 13 sysreg_read read from non memory mapped register function 3 154 sysreg_write write to non memory mapped registe
265. ompile only switch directs the compiler to compile and or assemble the source files but stop before linking The output is an object file doj for each source file const read write The const read write switch directs the compiler to specify that con stants may be accessed as read write data as in ANSI C The compiler s default behavior assumes that data referenced through const pointers will never change The const read write switch changes the compiler s behavior to match the ANSI C assumption which is that other non const pointers may be used to change the data at some point Dmacro definition The D define macro switch directs the compiler to define a macro If you do not include the optional definition string the compiler defines the macro as the string 1 If definition is required to be a character string 1 20 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler constant it must be surrounded by escaped double quotes Note that the compiler processes D switches on the command line before any U unde fine macro switches This switch can be invoked with the Definitions dialog field from the VisualDSP Project Options dialog box Compile tab Preprocessor category debug types lt file h gt The debug types switch provides for building an h file directly and writing a complete set of debugging information for the header file The g option on page 1 23 need not
266. ompiler may allocate an output operand in the same register as an unrelated input operand unless the output operand has the amp constraint modifier This situation can occur because the com piler assumes that the inputs are consumed before the outputs are produced This assumption may be false if the assembler code actually consists of more than one instruction In such a case use amp for each output operand that must not overlap an input or supply an amp for the input operand Table 1 7 lists operand constrains Operand constraints indicate what kind of operand they describe by means of preceding symbols The possible preceding symbols are no sym bol amp and no symbol The operand is an input It must appear as part of the third argument to the asm construct The allocated register will be loaded with the value of the C expression before the asm template is executed Its C expression will not be modified by the asm and its value may be a constant or literal Example d 1 62 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler e symbol The operand is an output It must appear as part of the sec ond argument to the asm construct Once the asm template has been executed the value in the allocated regis ter is stored into the location indicated by its C expression therefore the expression must be one that would be valid as the left hand side of an assignm
267. oops if their parameters are loop inde pendent and no global variables are modified in the loop pragma alloc The pragma alloc pragma asserts that the function behaves like the malloc library function In particular it returns a pointer to new memory that cannot alias any pre existing buffers In the following code pragma alloc int new_buf void int vmul int a int b int i int out new_buf for i 0 i lt 100 i outLi ali b i Good uses pragma alloc to disambiguate out from a and b the use of the pragma allows the compiler to be sure that the write into buffer out does not modify either of the two input buffers a or b and therefore the iterations of the loop may be re ordered 2 30 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Achieving Optimal Performance from C Source Code pragma regs_clobbered The regs_clobbered pragma is a useful way to improve the performance of code that makes function calls The best use of the pragma is to increase the number of call preserved registers available across a function call There are two complementary ways in which this may be done First of all suppose that you have a function written in assembly that you wish to call from C source code The regs_clobbered pragma may be applied to the function prototype to specify which registers are clob bered by the assembly function that is which registers may have different value
268. ous Information This section contains a number of miscellaneous aspects of the design that may be helpful in understanding stack functionality e Procedures without prototypes can be called successfully provided the argument types correspond properly Prototypes are always good programming practice Programs that call library subroutines should always include header files e There is no special interface for calling system library functions They use the standard calling convention VisualDSP 3 5 C Compiler and Library Manual 1 143 for ADSP 218x DSPs C Run Time Model and Environment Register Classification This section describes the ADSP 218x registers Registers are listed in order of preferred allocation by the compiler Callee Preserved Registers Preserved Registers 12 13 15 17 and MO are preserved A subroutine which uses any of these registers must save preserve and restore it Dedicated Registers Certain registers have dedicated purposes and are not used for other things Compiled code and libraries expect the dedicated registers to be correct Caller Save Registers Scratch All registers not preserved or dedicated are scratch registers A subroutine may use a scratch register without having to save it Circular Buffer Length Registers Registers LO through L7 are the circular buffer length registers The com piler assumes that these registers contain zero which disables circular buffe
269. ow the Compiler Can Help seis desde rceserseceuvoateaneteccereaions 2 4 Using the Compiler Optimizer csosessssssnimosesani 2 4 Using the Statistical Profiler siersiitiisiikekiasinikakiea 2 4 Using Intetprocedural Optimization srsnsrsircrrnonsureses 2 5 Dara 1908 ck ieee eee ee ee 2 7 Avoiding Emulated Arihmetit scascisaccciaxedsvarsinarcnncavanconesncrads 2 8 terme ihe Most irom ica iiacnernueennuentniaueets 2 9 Ipi alizing Constants Statically ssisiisiriiesinrsniiiennnenias 2 9 Avoiding Aliats onssoiorennninerannsneni naain 2 10 lndered Arrays vs Pointe once ees 2 12 Trying Pointer and Indexed SO lee ccciceectcsserseancereriemenens 2 13 Pancian TODE een A 2 13 Using Inline asm Statements sororis nian 2 14 WS Uar seein N E ens 2 15 Lo p Guidelines dais cscaincdi aa cercaasanianspacd kiiin 2 17 Keemine Loops ShO icceticqntsnerieiesienem 2 17 Avoiding Unrtolling Lone sesasscbiee 2 17 Avoiding Loop Rotation by Hand scssancisascarcrnsinaserinccanataantevens 2 18 Avoiding Array Writes in Loops cececsisusnisnseisiasniseisi 2 19 Roney Loops vs Outer Loops nincsen 2 19 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs XV CONTENTS Avoiding Conditional Cod in Lane o secccarcesesstecareterrcnce 2 20 Avoiding Placing Function Calls in Loops scsarsisisusnsnisi 2 21 Avoiding Non Unit Strides sander diiccatecndsacssonaediuodscndncetonniasten 2 21 Loop Control sunari 2 21 Using the Resttiet Qualihef cspissnoniitnbniiininiibniaat 2
270. p contains conditional code control flow latencies may incur large penalties if the compiler has to generate conditional jumps within the loop In some cases the compiler will be able to convert IF THEN ELSE and constructs into conditional instructions In other cases it will be able to relocate the expression evaluation outside of the loop entirely How ever for important loops linear code should be written where possible The compiler will not perform the loop transformation that interchanges conditional code and loop structures Instead of writing for i 0 i1 lt 100 i if mult_by_b suml ali bli else sumi ali cli Bad loop contains conditional code it is better to write if mult_by_b for i 0 i lt 100 i suml ali b i else for i 0 i lt 100 i suml a i c i Good two simple loops can be optimized well if this is an important loop 2 20 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Achieving Optimal Performance from C Source Code Avoiding Placing Function Calls in Loops The compiler will not usually be able to generate a hardware loop if the loop contains a function call due to the expense of saving and restoring the context of a hardware loop In addition to obvious function calls such as printf hardware loop generation can also be prevented by operations such as division modulus and some type coercions These operatio
271. pis sonsgomicibiianinn anka ail 1 99 Daa Alignment Peis acicncisuimiameianenae 1 101 Piao is alien DUM srncie 1 101 PN ped TANITA socaire 1 102 Interropt Handler Prapmas cic sacunsicasmncniievenansenancnineanneties 1 102 OT IEE anii S 1 102 Fpragma altregisters oiutosoniakoiiirueinini kinei 1 103 Loop Optitmizanon Praginas sosesororsruisnrrneuiraii 1 103 pragma loop_count min max modulo e 1 104 Pe PORE OT siaersscrarantcesianncapnumiuncnsiauntavaeata 1 104 FG HO Ie sarena 1 105 General Oprimization Pagans scscsdecccicovscesnseaenivndanonsts 1 105 Linking Control Pragmas sobsnsnossisainierisinnissersi 1 106 pragma linkage namie identifier siccssnsssrnerrai 1 107 x VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs CONTENTS Se PA AI arrr rT n 1 107 Fpiagma weak FY arranimninpar ninna SS 1 108 Stack Usage POA uiian RER 1 108 pragma make auto static csciccinnnounnennanions 1 108 Function Side Etfect Pragmas ssnssiniiuscoiibianinikknt 1 109 VINA olote 1 109 Tpm DUTE eri 1 110 F pragma CONSE sorerirorrardsr na rror ENERE 1 110 pragma regs clobbered string nesoresarsnsmsoroisisnsss 1 111 pragma result alignment 0 ceccisiccssswneainrsrsevscneisensundes 1 114 Header File Control Pragmas accusiorsissorassrnananiss 1 115 f pragma kirap ers S 1 115 Teed BE PON oaa 1 116 APEE CORE a 1 116 Fpragma system header occu siecenarrseuareancerssndoiandedaeedaensinees 1 116 GCC Compatibility Extensions seisasnesirecs
272. ple amp d e symbol The operand is an input but the register s value is clobbered by the asm template execution The compiler may make no assumptions about the register s final value The operand must appear as part of the second argument to the asm construct Example d Table 1 7 lists the registers that may be allocated for each register con straint letter The use of any letter not listed in the Constraint column of this table results in unspecified behavior The compiler does not check the validity of the code by using the constraint letter Table 1 8 on page 1 66 lists the registers that may be named as part of the clobber list It is also possible to claim registers directly instead of requesting a register from a certain class using the constraint letters You can claim the registers directly by simply naming the register in the location where the class letter would be The register names are the same as those used to specify the clobber list see Table 1 8 For example asm 40 1 2 ar sum output g x G C y input ys would load x into ALU X register y into ALU Y register and sum will be cal culated in register AR 1 64 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Table 1 7 ASM Operand Constraints Compiler Constraint Description Registers b input xregs to M
273. ple the switches 1c letsi will add the C library libc d1b and the ETSI support library 1ibetsi d1b to the list of libraries to be searched by the linker For more information on the ETSI support library see ETSI Sup port on page 1 86 For more information on the LDF file see the VisualDSP 3 5 Linker and Utilities Manual for 16 Bit Processors VisualDSP 3 5 C Compiler and Library Manual 3 3 for ADSP 218x DSPs C Run Time Library Guide Table 3 15 C Run Time Library Files 218x lib Directory Description 218x_hdr doj Default C run time initialization code Calls main 218x_ezkit_hdr doj C run time initialization code with EZ Kit monitor program support Calls main 218x_int_tab doj Default interrupt vector code 218x_ezkit_int_tab doj Object files for backward compatibility 2189_int_tab doj 218x_exit doj Dummy exit object for backwards compatibility ibc dlb C run time library ibcab d1b C run time library code with autobuffering support jbetsi dlb ETSI library support ibio dlb T O library ibioab dlb T O library with autobuffering support Working With Library Source Code The source code for some functions in the C run time libraries is provided with your VisualDSP software By default the installation program copies the source code to a subdirectory of the directory where the run time libraries are kept named 218x 1ib src Each function is kept in a separ
274. port keyword inline 1 47 1 53 1 55 inlining automatic 1 50 2 13 function 2 13 inner loop 2 19 interface support macros 1 152 interfacing C assembly see mixed C assembly programming intermediate files 1 39 interprocedural analysis 1 26 1 50 analysis IPA 2 5 optimizations 1 50 interprocedural analysis IPA 1 26 interrupt control 1 85 default table 1 133 handling interrupt dispatcher 3 71 pragmas 1 102 RTI instruction 1 133 vector addresses 1 133 interrupt define interrupt handling function 3 71 interrupt table 218x_int_tab asm 1 133 interrupt table symbols system_start 1 133 __lib_int_determiner 1 133 _lib_int_table 1 133 interruptf function 3 71 interrupts see clear_interrupt interruptf interrupts signal raise functions intrinsic functions 1 83 io_space_read read I O space function 3 75 io_space_write write I O space function 3 77 IPA 1 26 1 50 ipa interprocedural analysis compiler switch 1 26 2 5 isalnum detect alphanumeric character function 3 79 isalpha detect alphabetic character function 3 80 iscntrl detect control character function 3 81 isdigit detect decimal digit function 3 82 isgraph detect printable character function 3 83 I 12 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs islower detect lowercase character function 3 86 iso646 h Boolean operator header file 3 8 iso646 h header file 3 8 isprint detect printable character function
275. proc Customxxx searches the Customxxx ini file When compiling with the proc switch the compiler defines the corre sponding __ADSP21 81 83 84 85 86 87 88 89 __ macro for the variant selected in addition to the __ADSP21XX__ and __ADSP218X__ macros which are always are defined as 1 For example __ADSP2181__ and __ADSP218X_ are pre defined to 1 by the compiler See also si revision version on page 1 39 for more information 8 on silicon revision of the specified processor R directory directory The R add source directory switch directs the compiler to add the spec ified directory to the list of directories searched for source files On Windows platforms multiple source directories are given as a comma or semicolon separated list The compiler searches for the source files in the order specified on the command line The compiler searches VisualDSP 3 5 C Compiler and Library Manual 1 37 for ADSP 218x DSPs Compiler Command Line Reference the specified directories before reverting to the current project directory This option is position dependent on the command line that is it affects only source files that follow the option Source files whose file names begin with or or Windows equivalent and contain drive specifiers on Windows platforms are not affected by this option R The R disable source path switch removes all directories from the stan dard search path for sourc
276. procedure a procedure calling other proce dures its stack frame also contains outgoing linkage and parameter space e space for the arguments to the called procedure e space for the callee to save basic linkage information Figure 1 3 provides a general overview of the ADSP 218x DSP stack The stack grows downward on the page Because the stacks grow towards smaller addresses higher addresses are found in the upwards direction The stack resides in primary data memory DM It is controlled by a pair of pointers a stack pointer SP which identifies the boundary of the in use portion of the stack space and a frame pointer FP which provides stable addressing to the current frame The C compiler environment defines reg ister 14 as the SP stack pointer and M4 as the FP frame pointer 1 136 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Incoming Arguments Linkage Information FP Linkage Information and Temporaries Save Area for caller info Free Space lt SP Figure 1 3 ADSP 218x DSP Stack Stack Frame Description This section describes each part of the stack frame as shown in Figure 1 3 Incoming Arguments The memory area for incoming arguments begins at the FP value 1 Argument words are mapped by ascending addresses so the sec ond argument word is mapped at FP 2 Linkage Information The return address is saved on the hardware stack by the
277. processor and therefore more efficient However this optimization can generate overflow results which are not consistent in some cases and may differ from expected results depending on the optimizations enabled and the way that the source is written The inconsistency and differences are seen if an overflow and truncation of the integer operands would normally occur When the optimization is applied there is no truncation When the opti mization is disabled the result of overflow will be truncated to integer size before being stored in the long result The 0 enable optimizations switch directs the compiler to produce code that is optimized for performance Optimizations are not enabled by default for the compiler You can invoke this switch by selecting the Enable optimization check box in the VisualDSP Project Options dialog box Compile tab General category 1 32 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Oa The 0a automatic function inlining switch enables the inline expansion of C functions which are not necessarily declared inline in the source code The amount of auto inlining the compiler performs is controlled using the 0v optimize for speed versus size switch on page 1 33 Therefore use of 0v100 indicates that as many functions as possible will be auto inlined whereas 0v0 prevents any function from being auto inlined Specifying 0a also implies the use of 0 When rem
278. quivalent cc218x C array initializer that uses indexed elements int abc 6 1 5 6 4 12 The following example shows how to label the array initializer elements when the indices are characters or an enum type Example 3 C Array Initializer With enum Type Indices cc218x C array initializer int charsarray 256 ES ET rome Pa eval mel rset Fc he fl rom EAA RET PEW E A fl es Pee col J VisualDSP 3 5 C Compiler and Library Manual 1 81 for ADSP 218x DSPs C Compiler Language Extensions In a structure initializer specify the name of a field to initialize with freld name before the element value The standard C and cc218x C struct ini tializers in the example below are equivalent Example 4 Standard C amp cc218x C struct Initializer Standard C struct Initializer struct point EINE Xa VSS struct point p xvalue yvalue Equivalent cc218x C struct Initializer With Labeled Elements struct point i struct point p nt x ys y yvalue x xvalue Aggregate Constructor Expression Support Extended initializer support includes support for aggregate constructor expressions which enable you to assign values to large structure types without requiring each element s value to be individually assigned The following example shows an ISO ANSI standard C struct usage followed by equivalent cc218x code that has been simplified using an constructor expression
279. r function 3 156 system header files 1 128 1 152 T T linker description file compiler switch 1 41 tan tangent function 3 158 tan_frl6 function 3 158 tangent 3 158 tanh hyperbolic tangent function 3 159 template for asm in C programs 1 57 terminate see atexit exit functions time store and return current calendar time function 3 160 time time the compiler compiler switch 1 41 timer_off disable ADSP 218x timer function 3 160 timer_on enable ADSP 218x timer function 3 161 timer_set initialize ADSP 218x timer function 3 162 tokens string convert see strtok function tolower convert from uppercase to lowercase function 3 163 toupper convert characters to upper case function 3 164 true see Boolean type support keywords bool true false type cast 1 122 typeof keyword 1 118 I 22 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs U U undefine macro compiler switch 1 21 1 42 unclobbered registers 1 113 unsigned bitfield make plain bitfields unsigned compiler switch 1 42 unsigned char make char unsigned compiler switch 1 43 upper case see isupper toupper functions user header files 1 128 user reserved registers 1 114 Vv v version amp verbose compiler switch 1 43 va_arg get next argument in variable list function 3 165 va_end reset variable list pointer function 3 168 va_end macro 3 168 va_start set variable list pointer
280. r and Library Manual 3 125 for ADSP 218x DSPs C Run Time Library Reference strchr find first occurrence of character in string Synopsis include lt string h gt char strchr const char sl int c Description The strchr function returns a pointer to the first location in s1 a null terminated string that contains the character c Error Conditions The strchr function returns a null pointer if c is not part of the string Example include lt string h gt char ptrl ptr2 ptrl TESTING ptr2 strchr ptrl E ptr2 points to the E in TESTING See Also memchr strrchr 3 126 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs strcmp compare strings Synopsis d Finclude lt string h gt C Run Time Library int strcmp const char sl const char s2 Description The strcmp function lexicographically compares the null terminated strings pointed to by s1 and s2 It returns a positive value if the s1 string is greater than the s2 string a negative value if the s2 string is greater than the s1 string and a zero if the strings are the same Error Conditions The strcmp function does not return an error condition Example d Finclude lt string h gt char string1 50 string2 50 if stremp stringl string2 o printf s is different than See Also memcmp strncmp 2s n stringl string2 VisualDSP 3 5 C Compiler and Library Manual
281. r command line may be helpful on page 1 23 This performs section elimination in the linker to remove unneeded data and code If the code produced with 0s and e does not meet the code size constraint some analysis of the source code will be required to try to reduce the code size further Note that loop transformations such as unrolling and software pipelining increase code size But it is these loop transformations that also give the greatest performance benefit Therefore in many cases compiling for min imum code size will produce significantly slower code than optimizing for speed The compiler provides a way to balance between the two extremes of 0 and 0s This is the sliding scale 0v num switch adjustable using the optimization slider bar under Project Options in the VisualDSP IDDE described on page 1 33 The n is a value between 0 and 100 where the lower value corresponds to minimum code size and the upper to maximum performance A value in between will try to optimize the fre VisualDSP 3 5 C Compiler and Library Manual 2 27 for ADSP 218x DSPs Smaller Applications Optimizing for Code Size quently executed regions of code for maximum performance while keeping the infrequently executed parts as small as possible The switch is most reliable when using profile guided optimization since the execution counts of the various code regions have been measured experimentally Without PGO the execution counts are estimat
282. rackets and sepa rated by vertical bars read the example as an optional this or that this Optional item lists in syntax descriptions appear within brackets delimited by commas and terminated with an ellipsis read the example as an optional comma separated list of this SECTION Commands directives keywords and feature names are in text with letter gothic font filename Non keyword placeholders appear in text with italic style format VisualDSP 3 5 C Compiler and Library Manual xxxiii for ADSP 218x DSPs Notation Conventions Example Description A note providing information of special interest or identifying a related topic In the online version of this book the word Note appears instead of this symbol A caution providing information about critical design or program S ming issues that influence operation of a product In the online version of this book the word Caution appears instead of this symbol XXxiv VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 1 COMPILER The C compiler cc218x is part of Analog Devices development software for ADSP 218x DSPs This chapter contains C Compiler Overview on page 1 2 Provides an overview of C compiler for ADSP 218x DSPs Compiler Command Line Reference on page 1 6 Describes the operation of the compiler as it processes programs including input and output files and command line switches C Compiler Langu
283. ractional defined in fract_typedef h long 32 bits signed 2 unsigned long 32 bits unsigned 2 function pointer 32 bits 2 float 32 bits float 2 double 32 bits float 2 fract32 32 bits fractional 2 defined in fract_typedef h On any platform the basic type int is the native word size The data type long is 32 bits as is float A pointer is the same size as an int VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 1 47 Compiler Command Line Reference On the ADSP 218x processor architecture the long long int unsigned long long int and long double data types are not implemented they are not redefined to other types In general double word data types should be expected to run more slowly relying largely on software emulated arithmetic Analog Devices does not support data sizes smaller than a single word location for ADSP 218x processors For the current processors this means that both short and char have the same size as int Although 16 bit chars are unusual they conform to the standard Type double poses a special problem The C language tends to default to double for constants and in many floating point calculations Without some special handling many programs would inadvertently end up using slow speed emulated 64 bit floating point arithmetic even when variables are declared consistently as float In order to avoid this problem and provide the best performance the size of double on the ADSP 2
284. ral System Wide Specifications The following list contains some general specifications that apply to the stacks e The stacks grow down in memory from higher to lower addresses e The current frame s base is addressed by the FP register e The first free word in each stack is addressed by the SP register Locations at that point and beyond are vulnerable and must not be used These locations may be clobbered by asynchronous activities like interrupt service routines Alternatively locations at SP and 1 138 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler beyond are always available if additional space is needed but SP must be moved to guard the space Therefore the first used pro tected word is at SP 1 Data can be pushed onto the stack by executing an instruction like the following one for the ADSP 218x DSPs DM 14 M7 rej The return address of the caller is stored at offset 1 from the address carried by the current FP if it is stored on the stack The linkage back to the previous stack frame is stored at offset 0 from the current FP At a procedure call the following must be true There must be at least one free slot on the PC stack to hold the return address At an interrupt the following must be true Space beyond the SP must be available Return Values Return values always use registers Single word return values come back in register AX1 for 0ldA
285. range 1 0 1 0 Error Conditions The cos function does not return an error condition Example d Finclude lt math h gt double y y cos 3 14159 Reyes 2 O 7 VisualDSP 3 5 C Compiler and Library Manual 3 41 for ADSP 218x DSPs C Run Time Library Reference Notes The domain of the cos_fr16 function is restricted to the fractional range 0x8000 0x7 fff which corresponds to half a period from 1 2 to 7 2 It is possible however to derive the full period using the following proper ties of the function cosine 0 mT 2 cosine T 3 2 T cosine 2 0 cosine T 2 T The function below uses these properties to calculate the full period from 0 to 2m of the cosine function using an input domain of 0 0x7fff d Finclude lt math h gt fractl6 cos2pi_frl6 fractl6 x if x lt 0x2000 lt 0 25 first quadrant 0 7 2 cos_fr16 0x0 0x7fff 0 0x7fff Kf return cos_frl6 x 4 else if x lt Ox6000 ie oo Pe es a if x lt 0x4000 second quadrant 7 2 7 cos_frl6 0x8000 0x0 Ox7fff 0 pe ao if x lt 0x6000 third quadrant 3 21 a cos_fr1i6 0x0 0x7fff O0 0x8000 x return cos_fr16 0xc000 x 4 else fourth quadrant 3 27 1 cos_frl6 0x8000 0x0 0x8000 0 return cos_fr16 0x8000 x 4 3 42 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x
286. rary Reference pow raise to a power Synopsis dFinclude lt math h gt double pow double double Description The pow function computes the value of the first argument raised to the power of the second argument Error Conditions A domain error occurs if the first argument is negative and the second argument cannot be represented as an integer If the first argument is zero the second argument is less than or equal to zero and the result cannot be represented EDOM is stored in errno Example d Finclude lt math h gt double z z pow 4 0 2 0 PX 2 VG AY See Also exp Idexp 3 108 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library qsort quicksort Synopsis d Finclude lt stdlib h gt void qsort void base size_t nelem size_t size int compare const void const void Description The qsort function sorts an array of nelem objects pointed to by base The size of each object is specified by size The contents of the array are sorted into ascending order according to a comparison function pointed to by compare which is called with two arguments that point to the objects being compared The function shall return an integer less than equal to or greater than zero if the first argu ment is considered to be respectively less than equal to or greater than the second If two elements compare as equal their order in the sorted array is unspec ifi
287. rated from the shift the compiler may not detect the possibility of using a fractional multiply The recommended coding style is to use built in functions In the follow ing example a builtin is used to multiply fractional 16 bit data dFinclude lt math h gt fract32 dot_product fractl6 a fractl6 b int i fract32 sum 0 for i 0 i lt 100 i this line is performance critical sum __ builtin _mult_frlx32 ali bLil return sum Good uses builtins to implement fractional multiplication Note that the fract16 and fract32 types used in the example above are merely typedefs to C integer types used by convention in standard include files The compiler does not have any in built knowledge of these types and treats them exactly as the integer types that they are typedefed to System Support Built in Functions Built in functions are also provided to perform low level system manage ment in particular for the manipulation of system registers defined in sysreg h It is usually better to use these built in functions rather than inline asm statements The built in functions cause the compiler to gener ate efficient inline instructions and their use often results in better optimization of the surrounding code at the point where they are used Using builtins will also usually result in improved code readability For more information on built in functions supported by the compiler refer to Compiler Built in Function
288. reg h include file is mandatory when using disable_interrupts The disable_interrupts function does not return a value Error Conditions The disable_interrupts function does not return raise or set any error conditions Example include lt sysreg h gt main disable_interrupts emits DIS INTS instruction inline See Also enable_interrupts io_space_read io_space_write sysreg_read sysreg_write 3 48 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library div division Synopsis d Finclude lt stdlib h gt div_t div int numer int denom Description The div function divides numer by denom both of type int and returns a structure of type div_t The type div_t is defined as typedef struct int quot int rem divit where quot is the quotient of the division and rem is the remainder such that if result is of type div_t result quot denom result rem numer Error Conditions If denom is zero the behavior of the div function is undefined Example d Finclude lt stdlib h gt div_t result result div 5 2 result quot 2 result rem 1 See Also fmod Idiv modf VisualDSP 3 5 C Compiler and Library Manual 3 49 for ADSP 218x DSPs C Run Time Library Reference enable_interrupts enable interrupts Synopsis include lt sysreg h gt void enable_interrupts void Description The enable_interrupts function causes the compiler
289. rim Error Conditions The setjmp function does not return an error condition Example See code example for longjmp on page 3 99 See Also longjmp VisualDSP 3 5 C Compiler and Library Manual 3 115 for ADSP 218x DSPs C Run Time Library Reference signal define signal handling Synopsis d Finclude lt signal h gt void signal int sig void func int int void signalf int sig void func int int void signals int sig void func Description These functions are Analog Devices extensions to the ANSI standard The signal function determines how a signal received during program execution is handled The signa functions cause a single execution the function pointed to by func the interrupt functions cause the function to be executed for every interrupt The different variants of the signal functions differentiate between han dler dispatching functions The variants will be appropriate for some applications and provide improved efficiency The default signal func tion dispatcher saves and restores all scratch registers and modes on the data stack around a call to the handler func when servicing an interrupt This dispatcher will pass the interrupt ID for example SIG_PWRDWN to the handler as its parameter The signalf interrupt dispatcher does the same as interrupt except it switches between primary and secondary register sets to save and restore registers instead of using the
290. ring they must be set to zero when compiled code is executing to avoid incorrect behavior There is no restriction on the value of an L regis ter when the corresponding I register has been reserved from compiler use See reserve register register on page 1 38 for more information about reserving registers 1 144 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Mode Status MSTAT Register Compiler The C runtime initializes the MSTAT register as part of the run time header code The compiler and run time libraries assume to be running in these preset modes If you change any of the modes listed in Table 1 9 ensure that they are reverted before calling C compiled functions or functions from the C run time library Failure to revert to the default modes may cause applications to fail when running Table 1 9 MSTAT Register Modes Mode Description State SEC_REG Secondary Data Registers disabled BIT_REV Bit reversed address output disabled AR_SAT ALU saturation mode disabled M_MODE MAC result mode Integer Mode 16 0 format Complete List of Registers The following tables describe all of the registers for the ADSP 218x DSPs e Table 1 10 lists the data register s file registers e Table 1 11 lists the DAG1 registers e Table 1 12 lists the DAG2 registers Table 1 10 Data Register File Registers Register Descriptuon Notes AXO scratch AX1
291. rns the value of the floating point input multi plied by 2 raised to the power of n It adds the value of the second argument n to the exponent of the first argument x Error Conditions If the result overflows 1dexp returns a NaN If the result underflows 1dexp returns a zero Example d Finclude lt math h gt double y y Idexp 0 5 2 y 2 0 See Also exp pow VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 3 95 C Run Time Library Reference Idiv long division Synopsis include lt stdlib h gt ldiv_t Idiv long int numer long int denom Description The 1div function divides numer by denom and returns a structure of type ldiv_t The type 1div_t is defined as typedef struct long int quot long int rem k ldivit where quot is the quotient of the division and rem is the remainder such that if result is of type 1div_t result quot denom result rem numer Error Conditions If denom is zero the behavior of the 1div function is undefined Example d Finclude lt stdlib h gt ldiv_t result result ldiv 7 2 result quot 3 result rem 1 See Also fmod div 3 96 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs log natural logarithm Synopsis d Finclude lt math h gt double log double float logf float Description C Run Time Library The log function computes the natural base e logarithm of its input
292. rogram you must use the assembly version of the 1 88 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler function name prefix an underscore on the name For more information on naming conventions see C and Assembly Language Interface on page 1 148 The standard reference code for the ETSI functions uses the Carry and Overflow flag global variables to keep track of any carry or overflow as a result of using on of the ETSI functions With the ETSI functions pro vided by Analog Devices this can be switched off by compiling with __NO_ETSI_FLAGS defined in the compiler command line In fact this is the default for the ADSP 218x DSP implementation If you wish to keep track of these flags for debugging purposes compile with __NO_ETSI_FLAGS set to zero This stipulates the use of the functions in accordance with the ETSI standard but will result in a reduced performance Using the ETSI Built In Functions Some of the ETSI functions have been implemented as part of cc218x compiler s set of built in functions For information on how to use these functions refer to the section Compiler Built in Functions on page 1 83 These built in implementations will be automatically defined when header file ETSI_fract_arith h is included Linking ETSI Library Functions When your C code calls an ETSI function that is not implemented using a compiler built in the call creates a reference that the linker reso
293. rror Example Typical function usage See Also Related functions 3 18 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs abort abnormal program end Synopsis d include lt stdlib h gt void abort void Description C Run Time Library The abort function causes an abnormal program termination by raising a SIGABRT signal If the SIGABRT handler returns abort calls exit to terminate the program with a failure condition Error Conditions The abort function does not return Example d Finclude lt stdlib h gt extern int errors if errors terminate program if abort errors are present See Also atexit exit VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 3 19 C Run Time Library Reference abs absolute value Synopsis d Finclude lt stdlib h gt int abs int j Description The abs function returns the absolute value of its int input The abs function is implemented through a built in The built in causes the com piler to emit an inline instruction to perform the required function at the point where abs is called abs INT_MIN returns INT_MIN Error Conditions The abs function does not return an error condition Example include lt stdlib h gt int i i abs 5 i 5 See Also fabs labs 3 20 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library acos arc cosine Synop
294. rs an unrecognized pragma directive or pragma operator The compiler will not expand any preprocessor macros used within any pragma directive or pragma operator 1 100 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Data Alignment Pragmas The data alignment pragmas include align and pad pragmas Alignments specified using these pragmas must be a power of two The compiler will reject uses of those pragmas that specify alignments that are not powers of two pragma align num The align num pragma may be used before variable and field declara tions It applies to the variable or field declaration that immediately follows the pragma Use of this pragma causes the compiler to generate the next variable or field declaration aligned on a boundary specified by num The align pragma is useful for declaring arrays that need to be on a circu lar boundary Such arrays might be required to make use of a bit reversal sorting algorithm that is implemented using the ADSP 218x processor s DAG bit reversal mode pragma align 256 int arr 128 The align pragma is also useful for declaring arrays in C at correct base adresses This way the arrays can be passed to assembly functions and used as circular buffers or storage for autobuffering If the pragma align directives cause insufficient memory errors at link time due to fragmentation compile using the flags link ip switch options described on pa
295. rting at 0 Separate multiple instructions with a semico lon then enclose the entire string within double quotes For more information on templates containing multiple instruc tions see Assembly Constructs With Multiple Instructions on page 1 67 constraint The constraint is a string that directs the compiler to use certain groups of registers for the input and output operands Enclose the constraint string within double quotes For more information on operand constraints see Assembly Construct Operand Descrip tion on page 1 61 output operand The output operand is the name of a C variable that receives out put from a corresponding operand in the assembly instruction input operand The input operand is a C expression that provides an input to a corresponding operand in the assembly instruction 1 58 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler clobber The clobber notifies the compiler that a list of registers are over written by the assembly instructions Use lowercase characters to name clobbered registers Enclose each name within double quotes and separate each quoted register name with a comma The input and output operands are guaranteed not to use any of the clobbered registers so you can read and write the clobbered registers as often as you like See Table 1 8 on page 1 66 ASM Construct Syntax Rules These rules apply to assembly construct template syntax
296. ructs that are not strictly ISO ANSI standard C compliant pplist filename on page 1 36 Outputs a raw preprocessed listing to the specified file proc identifier on page 1 36 R directory on page 1 37 Specifies that the compiler should produce code suitable for the specified DSP Appends directory to the standard search path for source files R on page 1 38 Removes all directories from the standard search path for source files reserve lt reg1 gt reg2 on page 1 38 Reserves specified registers for autobuffering ES on page 1 38 Stops compilation before running the assembler s on page 1 39 Removes debugging information from the output executable file when linking save temps on page 1 39 show on page 1 39 Saves intermediate files Displays the driver command line information si revision version on page 1 39 Specifies a silicon revision of the specified processor signed bitfield on page 1 40 Treats bitfields which have not been declared with use of signed or unsigned keyword as signed This is the default behavior signed char on page 1 40 Makes the char data type signed VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Table 1 2 Compiler Command Line Switches Contd Switch Name Description syntax only on page 1 40 Checks the source c
297. s on page 1 83 VisualDSP 3 5 C Compiler and Library Manual 2 25 for ADSP 218x DSPs Using Built in Functions in Code Optimization Examples of the two styles are int read_io int ret_val asm 40 10 0x20 e ret_val 3 return ret_val Bad uses inline asm statement d Finclude lt sysreg h gt define ADDR 0x20 int read_io return io_space_read ADDR Good uses sysreg h 2 26 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Achieving Optimal Performance from C Source Code Smaller Applications Optimizing for Code Size The same ethos for producing fast code also applies to producing small code You should present the algorithm in a way that gives the optimizer excellent visibility of the operations and data and hence the greatest free dom to safely manipulate the code to produce small applications Once the program is presented in this way the optimization strategy will depend on the code size constraint that the program must obey The first step should be to optimize the application for full performance using 0 or ipa switches If this obeys the code size constraints then no more need be done The optimize for space switch 0s on page 1 33 which may be used in conjunction with IPA will perform every performance enhancing trans formation except those that increase code size In addition the e linker switch flags link e if used from the compile
298. s 1 120 mathematical functions 3 9 flow control operations 1 70 FLT_ROUNDS macro 3 8 fmod floating point modulus function 3 60 fp associative floating point associative compiler switch 1 23 fract h header file 3 8 fractional data 2 24 frame pointer 1 136 free deallocate memory function 3 61 frexp separate fraction and exponent function 3 62 full version display version compiler switch 1 23 function arguments 1 75 call in loop 2 21 inlining 2 13 G g generate debug information compiler switch 1 23 g21 based options and extensions A 3 GCC compatibility extensions 1 117 GCC compiler compatibility 1 117 general optimization pragmas 1 105 general utilities specified by C standard 3 12 getsfirst macro 1 155 getsnext macro 1 155 globvar global variable 2 22 GNU C compiler 1 117 graphical character test see isgraph function H H list h compiler switch 1 24 hardware interrupt 1 133 header file control pragmas 1 115 header files 1 31 1 128 assert h 3 6 ctype h 3 6 def2181 h 3 7 def218x h 3 7 defESP202 h 3 7 sh 3 function_entry macro 1 153 a functions primitive I O 3 11 Pr iso646 h 3 8 1 10 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs locale h 3 9 math h 3 9 misc h 3 10 setjmp h 3 10 signal h 3 10 sport h 3 11 stdarg h 3 11 stdio h 3 11 stdlib h 3 12 string h 3 12 supplied with compiler 3 5 sysreg h 1 84 3 13 header files standard float h
299. s a function of its parameters or of global variables If any of the parameters are pointers the function may read the data they point at but it may not write it Therefore because the function call will have the same effect every time it is called between assignments to global variables the compiler need not generate the code for every call Therefore in this example pragma pure long sdot short short int long tendots short a short b int n int i long s 0 for Gi Ty i lt 10 7 s sdot a b n call can get hoisted out of loop return s the compiler can replace the ten calls to sdot with a single call made before the loop pragma const The pragma const is a more restrictive form of the pure pragma It tells the compiler that the function does not read from global variables as well as not writing to them or reading or writing volatile variables The result of the function is therefore a function of its parameters If any of the parameters are pointers the function may not even read the data they point at 1 110 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler pragma regs_clobbered string The pragma regs_clobbered string may be used with a function decla ration or definition to specify which registers are modified or clobbered by that function The string contains a list of registers and is case insensitive When used with an external function de
300. s a zero if no conversion can be made and a pointer to the invalid string is stored in the object pointed to by endptr If the correct value results in an overflow a positive or negative as appropri ate HUGE_VAL is returned If the correct value results in an underflow 0 is returned The ERANGE value is stored in errno in the case of either an over flow or underflow Example d Finclude lt stdlib h gt char rem float f f strtodf 2345 5E4 abc amp rem f 2 3455E 7 rem abc f strtodf 0x1 800p 9 123 amp rem f 768 0 rem 123 3 144 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library See Also atof strtol strtoul VisualDSP 3 5 C Compiler and Library Manual 3 145 for ADSP 218x DSPs C Run Time Library Reference strtok convert string to tokens Synopsis include lt string h gt char strtok char sl const char s2 Description The strtok function returns successive tokens from the string s1 where each token is delimited by characters from s2 A call to strtok with s1 not NULL returns a pointer to the first token in s1 where a token is a consecutive sequence of characters not in s2 s1 is modified in place to insert a null character at the end of the token returned If s1 consists entirely of characters from s2 NULL is returned Subsequent calls to strtok with s1 equal to NULL will return successive tokens from the sa
301. s before and after the function call Consider for example an simple assembly function to add two integers and mask the result to fit into 8 bits _add_mask 16 14 M5 1 MODIFY I6 M5 AY1 DM I6 M5 AX1 DM I6 M6 AYO 255 AR AX1 AY1 AR AR AND AYO AX1 AR RTS _add_mask end Clearly the function does not modify the majority of the scratch registers available and thus these could instead be used as call preserved registers This way fewer spills to the stack would be needed in the caller function Using the prototype pragma regs_clobbered I6 M5 AX1 AY1 AY1 AR ASTAT int add_mask int int Good uses regs_clobbered to increase call preserved register set VisualDSP 3 5 C Compiler and Library Manual 2 31 for ADSP 218x DSPs Pragmas the compiler is told which registers are modified by a call to the add_mask function The registers not specified by the pragma are assumed to pre serve their values across such a call and the compiler may use these spare registers to its advantage when optimizing the call sites The pragma is also powerful when all of the source code is written in C In the above example a C implementation might be int add_mask int a int b return atb amp 255 Bad function thought to clobber entire volatile register set Since this function will not need many registers when compiled it can be defined using pragma regs_clobbered AX1
302. s left in the device registry table e The DeviceID is less than zero e Some of the function pointers are NULL e The device s init routine returned a failure result Once a device is registered it can be made the default device using the following function 1 142 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler void set_default_io_device int The user passes the Device1D There is a corresponding function for retrieving the current default device int get_default_io_device void The default device is used by fopen when a file is first opened The fopen function passes the open request to the open function of the device indicated by get_default_io_device The device file identifier dfid returned by the open function is private to the device other devices may simultaneously have other files open which use the same iden tifier An open file is uniquely identified by the combination of DeviceID and dfid The fopen function records the DeviceID and dfid in the global open file table and allocates its own internal fid to this combination All future operations on the file reads writes seeks and close use this fid to retrieve the Device D and thus direct the request to the appropriate device s primitive functions passing the dfid along with other parameters Once a file has been opened by fopen the current value of get_default_io_device is irrelevant to that file Miscellane
303. s the correspondence between constraint letters and register classes The use of any letter not listed in Table 1 7 results in unspecified behavior The compiler does not check the validity of the code by using the constraint letter For example if your assembly template contains axl dm 0 m3 and the address you want to load from is in the variable p the compiler needs to know that it should put p in a DAG1 I reg ister 10 13 before it generates your instruction You convey this information to cc218x by specifying the operand w p where w is the constraint letter for DAGII registers To assign registers to the operands the compiler must also be told which operands in an assembly language instruction are inputs which are out puts and which outputs may not overlap inputs The compiler is told this in three ways VisualDSP 3 5 C Compiler and Library Manual 1 61 for ADSP 218x DSPs C Compiler Language Extensions The output operand list appears as the first argument after the assembly language template The list is separated from the assembly language template with a colon The input operands are separated from the output operands with a colon and always follow the out put operands The operand constraints describe which registers are modified by an assembly language instruction The in constraint indi cates that the operand is an output all output operand constraints must use The c
304. s the specified directory to the standard library search path when linking Searches the specified library for functions when linking on page 1 27 Generates make rules only does not compile MD on page 1 28 Generates make rules and compiles MM on page 1 28 Generates make rules and compiles Mo filename on page 1 28 Specifies a file for output when using the ED and MD switches VisualDSP 3 5 C Compiler and Library Manual 1 13 for ADSP 218x DSPs Compiler Command Line Reference Table 1 2 Compiler Command Line Switches Contd Switch Name Description Mt filename on page 1 28 Makes dependencies for the specified source file MQ on page 1 28 Generates make rules only does not compile No notification when input files are missing make autostatic on page 1 29 Directs the compiler to place all automatic variables in static store map filename on page 1 29 Directs the linker to generate a memory map of all symbols mem on page 1 29 no alttok on page 1 29 Causes the compiler to invoke the Memory Initializer after linking the executable Does not allow alternative keywords and sequences in sources no bss on page 1 30 Causes the compiler to group global zero initialized data into the same section as global data with non zero initializers no builtin on page 1 30 Disables reco
305. s used to obtain the type of an expression e complex types complex creal cimag and conj These exten sions were used to define complex numbers Although you cannot write complex number literals you can have a complex type defined with real and imaginary components These types need to be managed by the programmer e compound statements within expressions This extension was used to declare variables within an expression You can achieve similar results using in line functions e iterator types iter sum These extensions created loop expres sions that were used as a shorthand for working with arrays e assigning variables to specific registers asm This extension was used to declare a variable and specify a machine register in which to store it If you used any of these extensions in your C source code you must remove them if you modify or re compile that source A 4 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Legacy Support Compiler Switch Modifications Compiler switches listed in Table A 1 have been removed or their action has been modified If you used any of these switches to compile your C code you should remove or replace the switch before recompiling the code with the new C compiler Table A 1 Obsolete and Replaced Switches Switch Name Operation under Release 6 1 Change for VisualDSP 3 5 Specify Architecture File Replaced with T and used
306. scratch single word return AYO scratch VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 1 145 C Run Time Model and Environment Table 1 10 Data Register File Registers Cont d Register Descriptuon Notes AY1 scratch Argument 2 for compatibility call AR scratch Argument 1 for compatibility call AF scratch XO scratch X1 scratch YO scratch yl scratch R1 0 scratch R2 scratch F scratch SB scratch SE scratch SI scratch SR1 0 scratch double word return Table 1 11 DAG1 Registers Register Descriptuon 10 scratch I1 scratch 12 preserved 13 preserved 1 146 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Table 1 11 DAG1 Registers Register Descriptuon 0 preserved 1 dedicated 1 2 dedicated 0 3 scratch LO 3 not used must be zero Table 1 12 List of DAG2 Registers Register Descriptuon 14 dedicated SP 15 preserved 16 scratch 17 preserved 4 dedicated FP 5 scratch 6 dedicated 0 7 dedicated 1 L4 7 not used must be zero Compiler VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 1 147 C and Assembly Language Interface C and Assembly Language Interface This section describes how to call assembly language subroutines from within C pr
307. should be a variable of type va_list which is used by va_arg to walk through the arguments The second argument is the name of the last named parameter in the func tion s parameter list the list of variable arguments immediately follows this parameter The va_start macro must be invoked before either the va_arg or va_end macro can be invoked Error Conditions The va_start macro does not return an error condition Example See va_arg on page 3 165 See Also va_arg va_end VisualDSP 3 5 C Compiler and Library Manual 3 169 for ADSP 218x DSPs C Run Time Library Reference 3 170 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs A COMPILER LEGACY SUPPORT The VisualDSP environment and tools provide several types of support for legacy code that was developed with previous releases of the develop ment tools For more information on legacy code support see the VisualDSP 3 5 Linker and Utilities Manual for 16 Bit Processors and VisualDSP 3 5 C Assembler and Preprocessor Manual for ADSP 218x and ADSP 219x DSPs Tools Differences VisualDSP 3 5 includes an updated C compiler linker and debugger and a binary file format ELF Due to use of the VisualDSP Integrated Development and Debugging Environment IDDE and other enhance ments VisualDSP 3 5 has significant differences from Release 6 1 that you will need to be aware of In some cases you will need to modify your sources to use the n
308. significant bits and the least significant bits of a long by the same short fract32 L_mls fract32 fractl6 Multiply and subtract fract32 L_msu fract32 fractl6 fractl6 This function performs a fractional multiplication of the two 16 bit parameters and returns the saturated subtraction of the multiplication result with the 32 bit parameter Multiply and subtract without saturation fract32 L_msuNs fract32 fractl6 fractl6 This function performs a non saturating version of the L_msu operation Long multiply fract32 L_mult fractl6 fractl6 This function returns the 32 bit result of the fractional multiplication of the two 16 bit parameters Long negate fract32 L_negate fract32 This function returns the 32 bit result of the negation of the parameter Where the input parameter is 0x80000000 saturation occurs and Ox7fffffff is returned 1 96 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Long saturation fract32 L_sat fract32 The resultant variable is set to 0x80000000 if Carry and Overflow ETSI flags are set underflow condition else if Overflow is set the resultant is set to Ox7fffffff The default revision of the library simply returns as no checking or setting of the Overflow and Carry flags is performed Long shift left fract32 Leshl fract32 fractl6 This function arithmetically shifts the 32 bit first parameter to the left by the value given in the 16 bit second parameter
309. sis include lt math h gt double acos double x float acosf float x fractl6 acos_frl6 fractl6 x Description The acos function returns the arc cosine of the argument The input must be in the range 1 1 The output in radians is in the range 0 7 The acos_fr16 function is only defined for input values between 0 and 0 9 0x7333 The input argument is in radians Output values range from acos 0 2m Ox7FFF to acos 0 9 2 M 0x24C1 Error Conditions The acos function returns a zero if the input is not in the range 1 1 Example d Finclude lt math h gt double y y acos 0 0 y 71 2 See Also COS VisualDSP 3 5 C Compiler and Library Manual 3 21 for ADSP 218x DSPs C Run Time Library Reference asin arc sine Synopsis include lt math h gt double asin double x float asinf float x fractl6 asin_frl6 fractl6 x Description The asin function returns the arc sine of the argument The input must be in the range 1 1 The output in radians is in the range 7 2 to 77 2 The asin_fr16 function is only defined for input values between 0 9 0X8CCD and 0 9 0x7333 The input argument is in radians Output values range from asin 0 9 2 m OXA4C1 to asin 0 9 2 T Ox5B3F Error Conditions The asin function returns a zero if the input is not in the range 1 1 Example d Finclude lt math h gt double y y asin 1 0 y 7 2 See Also
310. sis d Finclude lt string h gt char strrchr const char sl int c Description The strrchr function returns a pointer to the last occurrence of character c in the null terminated input string s1 Error Conditions The strrchr function returns a null pointer if c is not found Example d Finclude lt string h gt char ptrl ptr2 ptrl TESTING ptr2 strrcehr ptrl T ptr2 points to the second T of TESTING See Also memchr strchr VisualDSP 3 5 C Compiler and Library Manual 3 137 for ADSP 218x DSPs C Run Time Library Reference strspn length of segment of characters in both strings Synopsis include lt string h gt size_t strspn const char s1 const char s2 Description The strspn function returns the length of the initial segment of s1 which consists entirely of characters in the string pointed to by s2 The string pointed to by s2 is treated as a set of characters The order of the charac ters in the string is not significant Error Conditions The strspn function does not return an error condition Example include lt string h gt size_t len char ptrl ptr2 ptrl TESTING ptr2 ERST len strspn ptrl ptr2 Jen 4 See Also strcspn strlen 3 138 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library strstr find string within string Synopsis d Finclude lt string h gt char strstr co
311. smCal1 register AR is used Double word return val ues are stored in SR1 0 with the most significant part in SR1 If the return value is larger than two words then the caller must allocate space and pass the address as a hidden argument The register 10 is used for this purpose VisualDSP 3 5 C Compiler and Library Manual 1 139 for ADSP 218x DSPs C Run Time Model and Environment Procedure Call and Return To call a procedure 1 Evaluate the arguments and push them onto the stack 2 Call the procedure 3 On return remove arguments if desired On Entry 1 Save the old FP then set FP to the current SP If debugging pop the PC stack and store it on the main stack Move the SP to create space for the new frame Bo ee N If g is specified push the return address back onto the hardware stack After this step the new frame is officially in place 5 Continue saving registers and then execute the procedure A leaf procedure which does not require much stack space might choose to omit steps 1 and 2 operating without its own stack frame To Return from a Procedure 1 Restore miscellaneous saved registers 2 Place the return value in the correct register if not there already 3 Restore FP for the previous frame 4 Reset SP to remove the frame for procedure 5 Return to the caller 1 140 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler File O Support T
312. snueinai i 1 117 Statement Expressions dacaanssiditassowndaciiusibipietiatiadanetidaneaaal 1 117 Type Reference Support Keyword typeof 00 eeeeeeeeeeee 1 118 GCC Generalized Lela 2ausniaisecenteeees 1 119 Conditional Expressions with Missing Operands 1 120 Hexadecimal Floating Point Numbers cscccaseroisesscercnmrecsens 1 120 Zoro LACIE fester ine R 1 121 Variable Argument Macros sissies ciaraienininsssnteariandsniioreneanes 1 121 Line Breaks in Sering Literals iepecccetonensemcemnuetess 1 121 VisualDSP 3 5 C Compiler and Library Manual xi for ADSP 218x DSPs CONTENTS Arithmetic on Pointers to Void and Pointers to Functions 1 122 Catto UGN eee eee 1 122 Ranges in Care Labib oorun 1 122 Declarations mixed with Code ccccssssccsnsensecreesesncncrsneeveses 1 122 Escape Character Constant scndussduuiaininmesnuiaecas 1 123 Alignment Inquiry Keyword __alignof__ 0 0 1 123 Keyword for Specifying Names in Generated Assembler asm 1 123 Function Variable and Type Attribute Keyword __attribute__ 1 124 Preprocessor Peatiies onioni aiino beara eii 1 125 Predefined Preprocessor Matros a ccnccctrntminiemrminrnnccn 1 125 a JZ and ADSPIISA eronuionnroni 1 126 __ADSP21 81 83 84 85 86 87 88 89 __ sesssssssseessseeees Hi ANALOG EXTENSIONS sosscasassantenrrsaeteoeagsacears 1 126 DRTE O apaa e eE 1 126 aa CE ARE FLOATS a prennon penaiis 1 126 n E E E T 1 126 ccs E E E N E N AA E E 1 126 LOG VERKIN oan Gaareneen
313. std inc directories for header files nostdlib Do not use standard system Replaced with no std lib libraries and startup files when linking runhdr Specify a particular run time Removed header This feature can now be defined in the LDF file traditional cpp Support some preprocessing Removed features Warnings The VisualDSP 3 5 compiler includes several new warning switches These switches control the number and type of messages reported during a given compilation They are described in Table A 2 Table A 2 Compiler New Warning Switches VisualDSP 3 5 Description Warning Switch warn protos Produce a warning when a function is called with out a full prototype Wdriver limit number Set a maximum number of driver errors Werror limit number Set a maximum number of compiler errors eWramarks Indicates that the compiler may issue remarks which are diagnostic messages even milder than warnings Wterse Enable terse warnings VisualDSP 3 5 C Compiler and Library Manual A 7 for ADSP 218x DSPs Tools Differences Table A 2 Compiler New Warning Switches Cont d VisualDSP 3 5 Description Warning Switch pedantic Causes the compiler to generate warnings for any constructs in a C source file that does not conform to the ANSI standard W error remark suppress warn lt num gt num Overrides the severi
314. stitutes the string if it returns NULL This is an extension to C provided for compatibility with GCC Hexadecimal Floating Point Numbers C99 style hexadecimal floating point constants are accepted They have the following syntax hexadecimal floating constant 0x 0X hex significand binary exponent part floating suffix hex significand hex digits hex digits binary exponent part p P decimal digits floating suffix f 1 F Lb The hex significand is interpreted as a hexadecimal rational number the digit sequence in the exponent part is interpreted as a decimal integer The exponent indicates the power of two by which the significand is to be scaled The floating suffix has the same meaning it does for decimal float ing constants a constant with no suffix is of type double a constant with suffix F is of type float and a constant with suffix L is of type long double Hexadecimal floating point constants enable the programmer to specify the exact bit pattern required for a floating point constant For example the declaration float f Oxlp 126f 1 120 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler causes f to be initialized with the value 0x800000 Zero Length Arrays Arrays may be declared with zero length This is an anachronism sup ported to provide compatibility with GCC Use variable length array members instead Variable Argument Macros The fina
315. stop after preprocessing compiler switch 1 22 ED run after preprocessing to file compiler switch 1 22 EE run after preprocessing compiler switch 1 22 emulated arithmetic avoiding 2 8 enable_interrupts enable interrupts function 3 50 end see atexit exit functions enumerated variables 3 154 3 156 errno h header file 3 7 escape character 1 123 ETSI built in functions 1 89 fract16 and fract32 data types 1 90 function calls 1 88 library source code 1 90 linking library functions 1 89 support operations 1 86 ETSI library functions 16 bit variable least significant bits 1 95 16 bit variable most significant bits 1 95 compose long 1 98 extract high 1 92 extract long from two shorts 1 98 extract low 1 92 fract integer division of two longs 1 99 long absolute 1 95 long add 1 95 long add with carry 1 95 long division 1 91 long multiply 1 96 long negate 1 96 long normalize 1 93 long saturation 1 97 long shift left 1 97 long shift right 1 97 long shift right with rounding 1 8 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs 1 97 long subtract 1 97 long subtract with carry 1 98 multiply and accumulate 1 95 multiply and accumulate with rounding 1 92 multiply and accumulate without saturation 1 96 multiply and subtract 1 96 multiply and subtract with rounding 1 92 multiply and subtract without saturation 1 96 multiply both most significant bits and least significant bits of
316. t 2 xb bli yb b i 1 xa a i ya aLitl VisualDSP 3 5 C Compiler and Library Manual 2 17 for ADSP 218x DSPs Loop Guidelines xc xa xb yc ya yb cli xc c i 1 ye Bad harder for the compiler to optimize Avoiding Loop Rotation by Hand Tip Do not rotate loops by hand Programmers are often tempted to rotate loops in DSP code by hand attempting to execute loads and stores from earlier or future iterations at the same time as computation from the current iteration This technique introduces loop carried dependencies that prevent the compiler from rear ranging the code effectively However it is better to give the compiler a normalized version and leave the rotation to the compiler int ss short a short b int n int sum 0 intiz for i s 08 T lt ii TEF d sum a i b i return sum Good will be rotated by the compiler int ss short a short b int n short ta tb int sum 0 int 05 ta ali tb bli for i 1 i lt n i sum ta tb tas val ids tb ib kas sum ta tb 2 18 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Achieving Optimal Performance from C Source Code return sum Bad rotated by hand hard for the compiler to optimize By rotating the loop the scalar variables ta and tb have been added intro ducing loop carried dependencies Avoiding Array Wr
317. t Clobber Registers There are certain caveats as to what registers may or must be placed in the clobbered set On ADSP 218x DSPs the registers 14 M4 MSTAT and M_MODE may not be specified in the clobbered set as the correct operation of the function call requires their value to be preserved If the user specifies these registers in the clobbered set a warning will be issued and they will be removed from the specified clobbered set The registers AR and M5 are always clobbered If the user specifies a func tion definition with the regs_clobbered pragma which does not contain these registers a warning is issued and these registers are added to the clobbered set However if the compiler sees an external function declaration with a regs_clobbered pragma that does not contain the AR and M5 registers a warning will not be issued as an assembly function may have been written which genuinely does not modify these registers Registers from these classes D I ASTAT PX SE SB PMOVLAY DMOVLAY MF may be specified in clobbered set and code will be generated to save them as necessary The L registers are required to be zero on entry and exit from a function A user may specify that a function clobbers the L registers If it is a com piler generated function then it will in fact leave the L registers zero at the end of the function If it is an assembly function then it may clobber the L registers In that case the L registers are r
318. t compiler flags as inconsistent use of memory spaces between a function prototype and a call to the function Illegal Dual Memory Support Keywords amp Calls To Prototyped Functions extern int foo int pm declare function foo which expects a pointer to n int residing in pm as its argument and which returns an int int x define int x in dm foo amp x call function foo using pm pointer location of x as the aS argument cc218x FLAGS AS AN ERROR this is an inconsistency between the function s declared memory space argument and function Fi call memory space argument Memory Keywords and Macros Using macros when making memory space specification for variables or pointers can make your code easier to maintain If you must change the definition of a variable or pointer moving it to another memory space declarations that depend on the definition may need to be changed to ensure consistency between different declarations of the same variable or pointer To make changes of this kind easier you can use C preprocessor macros to define common memory spaces that must be coordinated The following listing shows two code segments that are equivalent after preprocessing VisualDSP 3 5 C Compiler and Library Manual 1 75 for ADSP 218x DSPs C Compiler Language Extensions These code segments demonstrate how you can redefine the memory space specifications by redefini
319. t keyword section Disabled using the no extra keywords compiler switch on page 1 30 1 4 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Boolean type support keywords in C bool true false Disabled using the no extra keywords compiler switch see on page 1 30 Variable length array support Non constant aggregate initializer support Indexed initializer support Preprocessor generated warnings Support for C style comments in C programs For more information on these extensions see the C Compiler Language Extensions on page 1 52 VisualDSP 3 5 C Compiler and Library Manual 1 5 for ADSP 218x DSPs Compiler Command Line Reference Compiler Command Line Reference This section describes how the cc218x compiler is invoked from the com mand line the various types of files used by and generated from the compiler and the switches used to tailor the compiler s operation This section contains e Running the Compiler on page 1 7 e Specifying Compiler Options in VisualDSP on page 1 10 e Compiler Command Line Switches on page 1 11 e Data Type Sizes on page 1 47 e Optimization Control on page 1 49 By default the cc218x compiler runs with Analog Extensions for C code enabled This means that the compiler processes source files written in ANSI ISO standard C language supplemented with Analog Devices exten sions Table 1 1 on page 1 9 lists valid
320. t of directo ries When the name is delimited by quote characters the search begins in the directory containing the primary input file then proceeds with the list of directories specified by the 1 command line switch When the name is delimited by angle bracket characters the search proceeds directly with the directories specified by 1 If the file is not located within any direc tory on the search list the search may be continued in one or more platform dependent system directories For more information refer to the VisualDSP Component Software Engineering User s Guide VisualDSP 3 5 C Compiler and Library Manual 1 131 for ADSP 218x DSPs C Run Time Model and Environment C Run Time Model and Environment This section provides a full description of the ADSP 218x DSP run time model and run time environment The run time model which applies to compiler generated code includes descriptions of the layout of the stack data access and call entry sequence The C run time environment includes the conventions that C routines must follow to run on ADSP 218x DSPs Assembly routines linked to C routines must follow these conventions ADI recommends that assembly programmers maintain stack conventions This section describes the conventions that you must follow as you write assembly code that can be linked with C code The description of how C constructs appear in assembly language are also useful for low level pro gram analysis
321. t the real part of a signal make sure that the imaginary input array is filled with zeros before calling the function VisualDSP 3 5 C Compiler and Library Manual 3 7 for ADSP 218x DSPs C Run Time Library Guide The functions first bit reverse the input arrays and then process them with an optimized block floating point FFT or IFFT routine filters h DSP Filters This category includes the digital signal processing filter functions of the C library These functions are Analog Devices extensions to the ANSI standard float h Floating Point The float h file defines the format of floating point data types The FLT_ROUNDS macro defined in the header file is set to the C run time environment definition of the rounding mode for float variables which is round towards nearest fract h ADSP 218x DSP Macro Fract Definitions The fract h header file defines macros used to manipulate fract fixed point types Improved fractional support is provided through the new ETSI operators added for VisualDSP 3 5 see ETSI Support on page 1 86 iso646 h The is0646 h header file defines symbolic names for certain C operators the symbolic names and their associated value are shown in Table 3 17 Table 3 17 Symbolic Names Defined in iso646 h Symbolic Name Equivalent and amp amp and_eq amp 3 8 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library Tab
322. tate arrays should equal length TAPS 1 e The a_coeffs array should equal length TAPS VisualDSP 3 5 C Compiler and Library Manual 3 67 for ADSP 218x DSPs C Run Time Library Reference iir b_coeffs TAPS sample B O B output b_coeffs TAPS 1 a_coeffs TAPS 1 b_coeffs TAPS 2 a_coeffs TAPS 2 b_coeffs TAPS 3 a_coeffs TAPS 3 b_coeffs 0 a_coeffs 0 Algorithm d n x n a 1 d n 1 a 2 d n 2 y n b 0 d n b 1 d n 1 b 2 d n 2 x n is sample and y n is output 3 68 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Error Conditions C Run Time Library The iir function does not return an error condition Example Hinc Hinc defi d fi stati stati stati pragma align 8s main int i static 0x4321 static 0x1234 int samp extern c FRACT verified with matlab c FRACT e_outputL TAPS c int fail 0 state array needs tatic FRACT ne FRACT int ne TAPS 4 te exam FRACT 0x87 RACT 0x56 leLTA RACT sta for i 0 ii for i 0 output i i lt T r i lt T cne ude lt stdio h gt ude lt filters h gt outputL TAPS m ple random p 6 5 0x1234 p 78 0x9876 PS 0x11 n APS 1 i loop APS i C porary loop a_coeffs b_coeffs T tate TAPS 1 te array needs to be intial
323. tax For example define pointer T typeof T define array T N typeof T N array pointer char 4 y declares y to be an array of four pointers to char The typeof keyword is an extension to C originally implemented in the GCC compiler It should be used with caution because it is not compatible with other dialects of C and has not been adopted by the more recent C99 standard GCC Generalized Lvalues A cast is an 1value may appear on the left hand side of an assignment if its operand is an lvalue This is an extension to C provided for compati bility with GCC A comma operator is an 1value if its right operand is an lvalue This is an extension to C provided for compatibility with GCC A conditional operator is an 1value if its last two operands are 1values of the same type This is an extension to C provided for compatibility with GCC VisualDSP 3 5 C Compiler and Library Manual 1 119 for ADSP 218x DSPs C Compiler Language Extensions Conditional Expressions with Missing Operands The middle operand of a conditional operator can be left out If the con dition is non zero true then the condition itself is the result of the expression This can be used for testing and substituting a different value when a pointer is NULL The condition is only evaluated once therefore repeated side effects can be avoided For example printf name s n lookup key calls lookup once and sub
324. tement expression can be declared with the __label__ keyword For example d __label__ exit int T3 for i 0 p i i int d get p i if check d goto exit process d exit totz Statement expressions are an extension to C originally imple mented in the GCC compiler Analog Devices support the extension primarily to aid porting code written for that compiler When writing new code consider using inline functions which are compatible with ANSI ISO C99 and are as efficient as macros when optimization is enabled Type Reference Support Keyword typeof The typeof expression construct can be used as a name for the type of expression without actually knowing what that type is It is useful for making source code that is interpreted more than once such as macros or include files more generic The typeof keyword may be used where ever a typedef name is permitted such as in declarations and in casts For example define abs a 1 118 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler typeof a __a a if __a lt 0 _a _ a pane Bs shows typeof used in conjunction with a statement expression to define a generic macro with a local variable declaration The argument to typeof may also be a type name Because typeof itself is a type name it may be used in another typeof type name construct This can be used to restructure the C type declaration syn
325. the 32 bit result from the L_msu operation Short multiply fractl6 mult fract16 fractl6 This function returns the 16 bit result of the fractional multiplication of the input parameters The result is saturated 1 92 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Multiply with rounding fractl6o mult_r fractl6 fractl6 This function performs a 16 bit multiply with rounding of the result of the fractional multiplication of the two input parameters Short negate fractl6 negate fractl6 This function returns the 16 bit result of the negation of the input param eter If the input is 0x8000 saturation occurs and 0x7fff is returned Long normalize fractl6 norm_ fract16 This function returns the number of left shifts required to normalize the input variable for positive values on the interval with minimum of 0x40000000 and maximum of O0x7fffffff and for negative values on the interval with minimum of 0x80000000 and maximum of 0xc0000000 Short normalize fractl6 norm_s fractl6 This function returns the number of left shifts required to normalize the input 16 bit variable for positive values on the interval with minimum of 0x4000 and maximum of 0x7fff and for negative values on the interval with minimum of 0x8000 and maximum of 0xc000 Round fractl6 round fract32 This function rounds the lower 16 bits of the 32 bit input parameter into the most significant 16 bits with saturation The r
326. times omit the semicolon after the macro call in order to have a valid program This leads to a need to remember whether a func tion or macro is being invoked for each call and whether the macro needs a trailing semicolon With the do while 0 construct you can treat the macro as a func tion and put the semicolon after it For example SKIP_SPACES enclosed macro ends without if p 0 SKIP_SPACES p lim else This expands to if p 0 do while 0 semicolon from SKIP_SPACES else Without the do while 0 construct the expansion would be if p 0 semicolon from SKIP_SPACES else This is not legal C syntax For more information on macros see the VisualDSP 3 5 Assembler and Preprocessor Manual for ADSP 218x and ADSP 219x DSPs 1 130 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Preprocessing of IDL Files Every VisualDSP Interface Definition Language VIDL specification is analyzed by the C language preprocessor prior to syntax analysis The include directive is used to control the inclusion of additional VIDL source text from a secondary input file that is named in the direc tive Two available forms of finclude are shown in Figure 1 2 i VIDL file name VIDL file name Figure 1 2 INCLUDE Syntax Diagram The file identified by the file name is located by searching a lis
327. timization on page 2 24 and Pragmas on page 2 29 2 6 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Achieving Optimal Performance from C Source Code Data Types The compiler directly supports the following scalar data types Single Word Fixed Point Data Types Native Arithmetic char 16 bit signed integer unsigned char 16 bit unsigned integer short 16 bit signed integer unsigned short 16 bit unsigned integer int 16 bit signed integer unsigned int 16 bit unsigned integer Double Word Fixed Point Data Types Emulated Arithmetic long 32 bit signed integer unsigned long 32 bit unsigned integer Floating Point Data Types Emulated Arithmetic double 32 bit float float 32 bit float Fractional data types are represented using the integer types Manipula tion of these is best done by use of built in functions described in System Support Built in Functions on page 2 25 VisualDSP 3 5 C Compiler and Library Manual 2 7 for ADSP 218x DSPs General Guidelines Avoiding Emulated Arithmetic Arithmetic operations for some types are implemented by library func tions because the DSP hardware does not directly support these types Consequently operations for these types are far slower than native opera tions sometimes by a factor of a hundred and also produce larger code These types are marked as Emulated Arithmetic i
328. tion 3 44 cotangent 3 45 C type functions isalnum 3 79 iscntrl 3 81 isdigit 3 82 isgraph 3 83 islower 3 84 3 86 isprint 3 89 ispunct 3 90 isspace 3 91 isupper 3 92 isxdigit 3 93 tolower 3 163 INDEX toupper 3 164 ctype h header file 3 6 custom processors 1 37 D D define macro compiler switch 1 26 1 42 DAGI registers 1 146 DAG registers 1 147 data alignment pragmas 1 101 register 1 145 scalar type 2 7 types 1 47 deallocate memory see free function debug information 1 39 1 49 debug types compiler switch 1 21 declarations mixed with code 1 122 dedicated registers 1 144 def2181 h header file 3 7 default linkage assembler linkage compiler switch 1 21 demean_buffer remove mean of data buffer function 3 46 device driver 1 141 identifiers 1 141 DevicelD field 1 142 differences between releases A 1 disable_interrupts disable interrupts function 3 48 VisualDSP 3 5 C Compiler and Library Manual 1 7 for ADSP 218x DSPs INDEX disabling compiler optimization 1 32 div division function 3 49 division see div Idiv functions dm see dual memory support keywords pm dm DM support standard C library 1 76 double data type 1 48 representation 3 140 dry verbose dry run compiler switch 1 22 dryrun terse dry run compiler switch 1 22 dual memory space 1 71 support keywords pm dm 1 53 1 71 dual memory support keywords pm dm 1 71 duplicate sign bit elimination 1 87 E E
329. tomatic variables For more information see Non Constant Aggregate Initializer Sup port on page 1 80 Indexed initializers Support for indexed initializers lets you specify elements of an aggre gate initializer in an arbitrary order For more information see Indexed Initializer Support on page 1 80 Preprocessor generated warnings Support for generating warning messages from the preprocessor For more information see Preprocessor Generated Warnings on page 1 83 C style comments Support for C style comments in C programs For more information see C Style Comments on page 1 83 1 54 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Inline Function Support Keyword inline The inline keyword directs cc218x to integrate the code for the function you declare as inline into the code of its callers Inline function support and the inline keyword is a standard feature of C the compiler pro vides it as a C extension Use of this keyword eliminates the function call overhead and therefore can increase the speed of your program s execu tion Argument values that are constant and that have known values may permit simplifications at compile time The following example shows a function definition that uses the inline keyword inline int max3 int a int b int c return max a max b c A function declared inline must be defined
330. trncpy is undefined when the two objects overlap The strncpy function returns the new s1 If the s2 string contains fewer than n characters the s1 string is padded with the null character until all n characters have been written Error Conditions The strncpy function does not return an error condition Example include lt string h gt char string1 50 strncpy stringl MOREFUN 4 MORE is copied into stringl stringl 4 0 must null terminate stringl See Also memcpy Memmove strcpy VisualDSP 3 5 C Compiler and Library Manual 3 135 for ADSP 218x DSPs C Run Time Library Reference strpbrk find character match in two strings Synopsis include lt string h gt char strpbrk const char s1 const char s2 Description The strpbrk function returns a pointer to the first character in s1 that is also found in s2 The string pointed to by s2 is treated as a set of charac ters The order of the characters in the string is not significant Error Conditions In the event that no character in s1 matches any in s2 a null pointer is returned Example include lt string h gt char ptrl ptr2 ptr3 ptrl TESTING ptr2 SHOP ptr3 strpbrk ptrl ptr2 ptr3 points to the S in TESTING See Also strspn 3 136 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library strrchr find last occurrence of character in string Synop
331. ty of specific compilation diag nostic messages where num is the number repre senting the message to override The Release 6 1 warning switches that are no longer supported are listed in Table A 3 Table A 3 Obsolete Warning Switches Wchar subscripts Wcomment Werror W Wformat Wall Wimplicit Wparentheses Wswitch Wtrigraphs Wuninitialized Wunused Wreturn type See Compiler Command Line Reference on page 1 6 for com plete descriptions of current C compiler switches Run Time Model The cc218x compiler in VisualDSP 3 5 produces code that is not fully compatible with the Release 6 1 run time model However the new com piler is superior in many ways to the old one and your programs will be faster smaller and more reliable after the C code is converted to the new system A 8 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Legacy Support VisualDSP 3 5 includes significant changes to the registers stack usage and other features of the run time model these changes are especially important if you wish to call assembly language subroutines from C pro grams or C functions from assembly language programs For complete details about the VisualDSP 3 5 run time model see C Run Time Model and Environment on page 1 132 VisualDSP 3 5 C Compiler and Library Manual A 9 for ADSP 218x DSPs Tools Differences VisualDSP
332. uotes to indicate a user header file For example include file 1 128 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler Writing Preprocessor Macros A macro is a name standing for a block of text that the preprocessor sub stitutes Use the define C preprocessor command to create a macro definition When the macro definition has arguments the block of text the preprocessor substitutes can vary with each new set of arguments Compound Statements as Macros When writing macros define a macro that expands into a compound statement You can define such a macro to invoke it the same way you would call a function making your source code easier to read and maintain The following two code segments define two versions of the macro SKIP_SPACES SKIP_SPACES regular macro tdefine SKIP_SPACES p limit char lim limit while p lim if p PA N break FA AN SKIP_SPACES enclosed macro tdefine SKIP_SPACES p limit do char lim limit while p lim Tf LRI R S T p break while 0 a aa VisualDSP 3 5 C Compiler and Library Manual 1 129 for ADSP 218x DSPs Preprocessor Features Enclosing the first definition within the do while 0 pair changes the macro from expanding into a compound statement to expanding into a single statement With the macro expansion into a compound statement you must some
333. upt Service Routine ISR main enable power down interrupt and register ISR interrupt SIG_PWRDWN handler disable power down interrupt interrupt SIG_PWRDWN SIG_IGN enable power down interrupt and register ISR interruptf SIG_PWRDWN handler disable power down interrupt interruptf SIG_PWRDWN SIG_IGN VisualDSP 3 5 C Compiler and Library Manual 3 73 for ADSP 218x DSPs C Run Time Library Reference See Also raise signal 3 74 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library io_space_read read I O space Synopsis include lt sysreg h gt int io_space_read const int Description The io_space_read function returns the value read from I O memory space at the address specified by the parameter The function is implemented as a compiler built in If the input argument is a constant literal value the compiler will emit a Type 29 instruction that will be inlined at the point of io_space_read use For non literal inputs the compiler will call a library compiler support routine to per form the required read Error Conditions The io_space_read function does not return raise or set any error conditions Example include lt sysreg h gt int addr OxA main int vl io_space_read 0xA inline instruction will be generated aes int v2 jo_space_read addr library support routin
334. urce lines information on transitions into and out of include files and diagnostics generated by the compiler Each listing line begins with a key character that identifies its type as Character Meaning N Normal line of source Expanded line of source Line of source skipped by if or ifdef Change in source position Diagnostic message remark Diagnostic message warning Diagnostic message error Diagnostic message catastrophic error proc processor The proc target processor switch specifies that the compiler should pro duce code suitable for the specified processor The processor identifiers directly supported in VisualDSP 3 5 are 1 36 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Compiler ADSP 2181 ADSP 2183 ADSP 2184 ADSP 2185 ADSP 2186 ADSP 2187 ADSP 2188 and ADSP 2189 For example cc218x proc ADSP 2181 pl c If no target is specified with the proc switch the compiler will generate an error message If the processor identifier is unknown to the compiler it attempts to read required switches for code generation from the file lt processor gt ini The assembler searches for the ini file in the VisualDSP System folder For custom processors the compiler searches the section proc in the lt processor gt ini for key architecture The custom processor must be based on an architecture key that is one of the known processors For example
335. ut Example d Finclude lt math h gt double y y sqrt 2 0 PROV SE DADA ss eos EN See Also No references to this function VisualDSP 3 5 C Compiler and Library Manual 3 123 for ADSP 218x DSPs C Run Time Library Reference srand random number seed Synopsis d Finclude lt stdlib h gt void srand unsigned int seed Description The srand function is used to set the seed value for the rand function A particular seed value always produces the same sequence of pseudo random numbers Error Conditions The srand function does not return an error condition Example d Finclude lt stdlib h gt srand 22 See Also rand 3 124 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs C Run Time Library strcat concatenate strings Synopsis include lt string h gt char strcat char sl const char s2 Description The strcat function appends a copy of the null terminated string pointed to by s2 to the end of the null terminated string pointed to by s1 It returns a pointer to the new s1 string which is null terminated The behavior of strcat is undefined if the two strings overlap Error Conditions The strcat function does not return an error condition Example d Finclude lt string h gt char string1 50 stringl 0 A stringl 1 B stringl 2 0 strcat stringl CD new string is ABCD See Also strncat VisualDSP 3 5 C Compile
336. uto_static pragma is not used on func tions that are directly or indirectly recursive Function Side Effect Pragmas The function side effect pragmas are used before a function declaration to give the compiler additional information about the function in order to enable it to improve the code surrounding the function call These prag mas should be placed before a function declaration and apply to that function For example pragma pure long dot short short int pragma alloc The pragma alloc tells the compiler that the function behaves like the library function malloc returning a pointer to a newly allocated object An important property of these functions is that the pointer returned by the function does not point at any other object in the context of the call In the example pragma alloc int new_buf void int vmul int a int b int out new_buf for i 0 i lt Ns 47 outLi ali bLil return out the compiler can reorder the iterations of the loop because the pragma alloc tells it that a and b cannot overlap out The GNU attribute malloc is also be supported with the same meaning VisualDSP 3 5 C Compiler and Library Manual 1 109 for ADSP 218x DSPs C Compiler Language Extensions pragma pure The pragma pure tells the compiler that the function does not write to any global variables and does not read or write any volatile variables Its result therefore i
337. void disable_interrupts void These functions are fully described in enable_interrupts on page 3 50 and disable_interrupts on page 3 48 VisualDSP 3 5 C Compiler and Library Manual 1 85 for ADSP 218x DSPs C Compiler Language Extensions ETSI Support The ETSI European Telecommunications Standards Institute support for ADSP 218x processors is a collection of functions that provides high performance implementations for operations commonly required by DSP applications These operations provided by the ETSI library libetsi d1b and compiler built in functions defined in ETSI_fract_arith h include support for fractional or fixed point arith metic The results obtained from of use of these operations have well defined overflow and saturation conditions The ETSI support operations are Analog Devices extensions to ANSI C standard The ETSI support contains functions that you can call from your source program The following topics describe how to use this support e ETSI Support Overview on page 1 86 e Calling ETSI Library Functions on page 1 88 e Using the ETSI Built In Functions on page 1 89 e Linking ETSI Library Functions on page 1 89 e Working with ETSI Library Source Code on page 1 90 e ETSI Support for Data Types on page 1 90 e ETSI Header File on page 1 91 ETSI Support Overview The use of fractional arithmetic is vital for many applications on DSP pro cessors as
338. void init void func printf val d val int main imite func Good IPA knows val is 3 Avoiding Aliases It may seem that the iterations may be performed in any order in the fol lowing loop void fn char aL char bE int n int i for 1 0 i lt ns 47 ali bli Bad a and b may alias each other but a and b are both parameters and although they are declared with 1 they are in fact pointers which may point to the same array When the same data may be reachable through two pointers they are said to alias each other If IPA is enabled the compiler will look at the call sites of fn and try to determine whether a and b can ever point to the same array 2 10 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Achieving Optimal Performance from C Source Code Even with IPA it is quite easy to create what appear to the compiler as aliases The analysis works by associating pointers with sets of variables that they may refer to at some point in the program If the sets for two pointers are found to intersect then both pointers are assumed to point to the union of the two sets If fn above were called in two places with global arrays as arguments then IPA would have the results shown below fn globl glob2 N fn globl glob2 N Good sets for a and b do not intersect a and b are not aliases fn globl glob2 N fn glob3 glob4 N Go
339. with the usual Data Memory DM The array declaration of one of either a or b is modified to pm int a 100 and any pointers to the buffer a become for example pm int p a to allow simultaneous accesses to the two buffers Note that the explicit placement of data in PM can only be done for global data 2 16 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs Achieving Optimal Performance from C Source Code Loop Guidelines Loops are where an application will ordinarily spend the majority of its time It is therefore useful to look in detail at how to help the compiler to produce the most efficient code possible for them Keeping Loops Short For best code efficiency loops should be as small as possible Large loop bodies are usually more complex and difficult to optimize Additionally they may require register data to be stored in memory This will cause a decrease in code density and execution performance Avoiding Unrolling Loops Tip Do not unroll loops yourself Not only does loop unrolling make the program harder to read but it also prevents optimization by complicating the code for the compiler void val const short aL const short bL short cL int n int i for i 0 i lt n i cli bli ali Good the compiler will unroll if it helps void va2 const short aL const short b short cL int n short xa xb xc ya yb yc int i for i 0 i lt n i
340. x and d1b extension For example the compiler command line switch 1c directs the linker to search in the library named c for functions This library resides in a file named libc d1b Normally you should list all object files on the command line before the 1 switch This ensures that the functions and global variables the object files refer to are loaded in the given order This option may be specified more than once libraries are searched as encountered during the left to right processing of the command line The M generate make rules only switch directs the compiler not to com pile the source file but to output a rule which is suitable for the make utility describing the dependencies of the main program file The format of the make rule output by the preprocessor is object file include file VisualDSP 3 5 C Compiler and Library Manual 1 27 for ADSP 218x DSPs Compiler Command Line Reference MD The MD generate make rules and compile switch directs the preprocessor to print to a file called original_filename d a rule describing the depen dencies of the main program file After preprocessing compilation proceeds normally See also the Mo switch MM The MM generate make rules and compile switch directs the preprocessor to print to stdout a rule describing the dependencies of the main program file After preprocessing compilation proceeds normally Mo filename The Mo filename preprocessor output f
341. y Manual for ADSP 218x DSPs C Run Time Library Example d Finclude lt sysreg h gt main sysreg_write sysreg_IMASK 0x1 See Also disable_interrupts enable_interrupts io_space_read io_space_write sysreg_read VisualDSP 3 5 C Compiler and Library Manual 3 157 for ADSP 218x DSPs C Run Time Library Reference tan tangent Synopsis include lt math h gt double tan double x float tanf float x fractl6 tan_frl6 fractl6 x Description The tan function returns the tangent of the argument x The input in radians must be in the range 9099 9099 The tan_fr16 function is only defined for input values between 7 4 0x9B78 and 7 4 0x6488 The input argument is in radians Output values range from 0x8000 to 0x7FFF The library function returns zero for any input argument that is outside the defined domain Error Conditions The tan function returns zero if the input argument is outside the defined domain Example d Finclude lt math h gt double y y tan 3 14159 4 0 y 1 0 See Also atan atan2 3 158 VisualDSP 3 5 C Compiler and Library Manual for ADSP 218x DSPs tanh hyperbolic tangent Synopsis include lt math h gt double tanh double x float tanhf float x Description C Run Time Library The tanh function returns the hyperbolic tangent of the argument x Error Conditions The tanh function does not return an error condition Example

Download Pdf Manuals

Related Search

Related Contents

Predia Touch Pro - Heutink-ICT  PDF形式  Dossier d`information - Droits rechargeables: élargissement  XYZ 53 STS Manual  Fissaclip AGTC    Leaflet NTRX100_12 Released Portugal (Portuguese  ULTRA-ACT ジャンボット 取扱説明書  American Standard 2506.152 User's Manual  

Copyright © All rights reserved. Failed to retrieve file