IQmath_Quickstart.pdf

Texas Instruments Inc.,2002-2011 1 C28x IQmath Library A Virtual Floating Point Engine V1.6.0 August 31,2011 Module users Guide(SPRC990)C28x Foundation Software Texas Instruments Inc.,2002-2011 2 IMPORTANT NOTICE Texas Instruments and its subsidiaries(TI)reserve the right to make changes to their products or to discontinue any product or service without notice,and advise customers to obtain the latest version of relevant information to verify,before placing orders,that information being relied on is current and complete.All products are sold subject to the terms and conditions of sale supplied at the time of order acknowledgement,including those pertaining to warranty,patent infringement,and limitation of liability.TI warrants performance of its semiconductor products to the specifications applicable at the time of sale in accordance with TIs standard warranty.Testing and other quality control techniques are utilized to the extent TI deems necessary to support this warranty.Specific testing of all parameters of each device is not necessarily performed,except those mandated by government requirements.Customers are responsible for their applications using TI components.In order to minimize risks associated with the customers applications,adequate design and operating safeguards must be provided by the customer to minimize inherent or procedural hazards.TI assumes no liability for applications assistance or customer product design.TI does not warrant or represent that any license,either express or implied,is granted under any patent right,copyright,mask work right,or other intellectual property right of TI covering or relating to any combination,machine,or process in which such products or services might be or are used.TIs publication of information regarding any third partys products or services does not constitute TIs approval,license,warranty or endorsement thereof.Reproduction of information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties,conditions,limitations and notices.Representation or reproduction of this information with alteration voids all warranties provided for an associated TI product or service,is an unfair and deceptive business practice,and TI is not responsible or liable for any such use.Resale of TIs products or services with statements different from or beyond the parameters stated by TI for that products or service voids all express and any implied warranties for the associated TI product or service,is an unfair and deceptive business practice,and TI is not responsible nor liable for any such use.Also see:Standard Terms and Conditions of Sale for Semiconductor P Mailing Address:Texas Instruments Post Office Box 655303 Dallas,Texas 75265 Copyright 2002,Texas Instruments Incorporated Texas Instruments Inc.,2002-2011 3 Trademarks TMS320 is the trademark of Texas Instruments Incorporated.All other trademarks mentioned herein are property of their respective companies Acronyms C28x+FPU:Refers to devices with the C28x plus floating-point-unit.IQmath:High Accuracy Mathematical Functions(32-bit implementation).QMATH:Fixed Point Mathematical computation Texas Instruments Inc.,2002-2011 4 Chapter 1.Introduction.6 1.1.Introduction.6 Chapter 2.Installing the IQmath Library.7 2.1.IQmath Package Contents.7 2.2.How to Install the IQmath Library.8 Chapter 3.Using the IQmath Library.9 3.1.IQmath Arguments and Data Types.9 3.2.IQmath Data type:Range&Resolution.10 3.3.Calling an IQmath Function from C.11 3.4.Calling an IQmath function from C+.11 3.5.IQmath Section and Lookup Tables.12 3.6.Accessing IQmath Functions in the Boot ROM.17 3.7.Example Projects.19 3.8.IQmath Naming Conventions.21 3.9.Selecting the GLOBAL_Q format.22 3.10.Using the IQmath GEL file for Debugging.23 3.11.Converting an IQmath Application to Floating-Point.25 3.12.The IQmath C-Calling Convention.25 Chapter 4.Libraries Available.26 Chapter 5.Function Summary.27 5.1.Arguments and Conventions Used.27 5.2.IQmath Function Overview.28 Format conversion Utilities.28 Shift to Multiply or Divide by Powers of 2.28 Arithmetic Operations.29 Trigonometric Functions:.29 Mathematical Functions:.30 Miscellaneous.30 5.3.C28x IQmath Library Benchmarks.31 Chapter 6.Function Descriptions.33 6.1.Conversion Utilities.33 IQN.33 IQN.33 IQNtoF.35 atoIQN.36 IQNtoa.37 IQNint.39 IQNfrac.40 IQtoIQN.41 Texas Instruments Inc.,2002-2011 5 IQNtoIQ.42 IQtoQN.43 QNtoIQ.44 6.2.Shift to Multiply or Divide by Powers of 2.45 IQmpy2,4,864.45 IQdiv2,4,864.46 6.3.Arithmetic Operations.47 IQNmpy.47 IQNrmpy.48 IQNrsmpy.49 IQNmpyI32.50 IQNmpyIQX.53 IQNdiv.54 6.4.Trigonometric Functions.57 IQNasin.57 IQNsin.58 IQNsinPU.60 IQNacos.62 IQNcos.63 IQNcosPU.65 IQNatan2.67 IQNatan2PU.69 IQNatan.71 6.5.Mathematical Utilities.72 IQNexp.72 IQNlog.73 IQNsqrt.74 IQNisqrt.76 IQNmag.79 6.6.Miscellaneous Utilities.80 IQNabs.80 IQsat.81 Chapter 7.Revision History.82 Texas Instruments Inc.,2002-2011 6 Chapter 1.Introduction 1.1.Introduction Texas Instruments TMS320C28x IQmath Library is collection of highly optimized and high precision mathematical functions for C/C+programmers to seamlessly port a floating-point algorithm into fixed point code on TMS320C28x devices.These routines are typically used in computationally intensive real-time applications where optimal execution speed and high accuracy is critical.By using these routines you can achieve execution speeds considerable faster than equivalent code written in standard ANSI C language.In addition,by providing ready-to-use high precision functions,TI IQmath library can shorten significantly your DSP application development time.Texas Instruments Inc.,2002-2011 7 Chapter 2.Installing the IQmath Library 2.1.IQmath Package Contents The TI IQmath library can be used in both C and C+programs and it consists of 5 parts:1)The IQmath header files The header files include the definitions needed to interface with the IQmath library.C programs use IQmathLib.h a)C+programs use both IQmathLib.h and IQmathCPP.h 2)The IQmath object library.The library contains all of the IQmath functions and look-up tables.There are two builds of the library:a)IQmath.lib:This build of the library can be linked with code built for fixed-point.b)IQmath_f32.lib:This build of the library can be linked with code built with the -float_support=fpu32 switch.This can be useful for mixing IQmath with native floating-point code on devices with the C28x+FPU.3)Example linker command files.The example linker command files allocate the sections used by the IQmath library.For some sections the location is device specific.For example,the tables used by the IQsin and IQcos functions are located within the boot ROM of the device.4)Legacy IQmath GEL file.These gel functions are useful when using a version of Code Composer Studio that does not support IQ data types directly.The.gel file is not needed when using Code Composer Studio V3.3 or Code Composer Studio V4.5)Example programs Texas Instruments Inc.,2002-2011 8 2.2.How to Install the IQmath Library The IQmath library is distributed in the form of a self-extracting ZIP file.By default,the install restores the IQmath library individual components in the directory structure shown below.NOTE:The directory structure of some earlier versions differed from what is shown below.It has been reorganized to reduce duplication of files.The directory has been changed to correspond to ControlSUITE.install directory is C:ticontrolSUITElibsmathIQmath doc Contains this file include The IQmath header files C code uses IQmathLib.h C+code uses IQmathLib.h and IQmathCPP.h lib The IQmath library files.These are used by both C and C+Refer to Chapter 4.gel Legacy GEL file for debug Refer to section 3.10.The following example project run on CCS V4:examples_ccsv4C C example:Refer to ReadMe_SampleC.txt examples_ccsv4C Each device family has its own project folder examples_ccsv4Csource Shared source code for the C example examples_ccsv4Cpp C+code example:Refer to ReadMe_SampleCpp.txt examples_ccsv4Cppsource Shared source code for the C+example examples_ccsv4Cpp Each device family has its own project folder examplescmd Linker command files used by the examples examples_ccsv4graph_properties The files in this directory can be used to setup the watch window and graphs in CCS 4.The following example projects run on CCS V3.3:examplesC C example:Refer to ReadMe_SampleC.txt examplesCprojects CCS projects for the C example examplesCsource Source code for the C example examplesCpp C+code example:Refer to ReadMe_SampleCpp.txt examplesCppprojects CCS projects for the C+example examplesCppsource Source code for the C+example examplescmd Linker command files used by the examples Texas Instruments Inc.,2002-2011 9 Chapter 3.Using the IQmath Library 3.1.IQmath Arguments and Data Types Input/output of the IQmath functions are typically 32-bit fixed-point numbers and the Q format of the fixed-point number can vary from Q1 to Q30.We have used typedefs to create aliases for IQ data types.This facilitates the user to define the variable of IQmath data type in the application program.typedef long _iq;/*Fixed point data type:GLOBAL_Q format*/typedef long _iq30;/*Fixed point data type:Q30 format */typedef long _iq29;/*Fixed point data type:Q29 format */typedef long _iq28;/*Fixed point data type:Q28 format */typedef long _iq27;/*Fixed point data type:Q27 format */typedef long _iq26;/*Fixed point data type:Q26 format */typedef long _iq25;/*Fixed point data type:Q25 format */typedef long _iq24;/*Fixed point data type:Q24 format */typedef long _iq23;/*Fixed point data type:Q23 format */typedef long _iq22;/*Fixed point data type:Q22 format */typedef long _iq21;/*Fixed point data type:Q21 format */typedef long _iq20;/*Fixed point data type:Q20 format */typedef long _iq19;/*Fixed point data type:Q19 format */typedef long _iq18;/*Fixed point data type:Q18 format */typedef long _iq17;/*Fixed point data type:Q17 format */typedef long _iq16;/*Fixed point data type:Q16 format */typedef long _iq15;/*Fixed point data type:Q15 format */typedef long _iq14;/*Fixed point data type:Q14 format */typedef long _iq13;/*Fixed point data type:Q13 format */typedef long _iq12;/*Fixed point data type:Q12 format */typedef long _iq11;/*Fixed point data type:Q11 format */typedef long _iq10;/*Fixed point data type:Q10 format */typedef long _iq9;/*Fixed point data type:Q9 format */typedef long _iq8;/*Fixed point data type:Q8 format */typedef long _iq7;/*Fixed point data type:Q7 format */typedef long _iq6;/*Fixed point data type:Q6 format */typedef long _iq5;/*Fixed point data type:Q5 format */typedef long _iq4;/*Fixed point data type:Q4 format */typedef long _iq3;/*Fixed point data type:Q3 format */typedef long _iq2;/*Fixed point data type:Q2 format */typedef long _iq1;/*Fixed point data type:Q1 format */Texas Instruments Inc.,2002-2011 10 3.2.IQmath Data type:Range&Resolution Following table summarizes the Range&Resolution of 32-bit fixed-point number for different Q format representation.Typically IQmath function supports Q1 to Q30 format,nevertheless some functions like IQNsin,IQNcos,IQNatan2,IQNatan2PU,IQatan do not support Q30 format,due to the fact that these functions input or output vary between to radians.Data Type Range Resolution/Precision Min Max _iq30-2 1.999 999 999 0.000 000 001 _iq29-4 3.999 999 998 0.000 000 002 _iq28-8 7.999 999 996 0.000 000 004 _iq27-16 15.999 999 993 0.000 000 007 _iq26-32 31.999 999 985 0.000 000 015 _iq25-64 63.999 999 970 0.000 000 030 _iq24-128 127.999 999 940 0.000 000 060 _iq23-256 255.999 999 981 0.000 000 119 _iq22-512 511.999 999 762 0.000 000 238 _iq21-1024 1023.999 999 523 0.000 000 477 _iq20-2048 2047.999 999 046 0.000 000 954 _iq19-4096 4095.999 998 093 0.000 001 907 _iq18-8192 8191.999 996 185 0.000 003 815 _iq17-16384 16383.999 992 371 0.000 007 629 _iq16-32768 32767.999 984 741 0.000 015 259 _iq15-65536 65535.999 969 482 0.000 030 518 _iq14-131072 131071.999 938 965 0.000 061 035 _iq13-262144 262143.999 877 930 0.000 122 070 _iq12-524288 524287.999 755 859 0.000 244 141 _iq11-1048576 1048575.999 511 719 0.000 488 281 _iq10-2097152 2097151.999 023 437 0.000 976 563 _iq9-4194304 4194303.998 046 875 0.001 953 125 _iq8-8388608 8388607.996 093 750 0.003 906 250 _iq7-16777216 16777215.992 187 500 0.007 812 500 _iq6-33554432 33554431.984 375 000 0.015 625 000 _iq5-67108864 67108863.968 750 000 0.031 250 000 _iq4-134217728 134217727.937 500 000 0.062 500 000 _iq3-268435456 268435455.875 000 000 0.125 000 000 _iq2-536870912 536870911.750 000 000 0.250 000 000 _iq1-1073741824 1 073741823.500 000 000 0.500 000 000 Texas Instruments Inc.,2002-2011 11 3.3.Calling an IQmath Function from C In addition to installing the IQmath software,to include an IQmath function in your code you have to:Include the IQmathLib.h include file Link your code with the IQmath object code library.This will normally be the IQmath.lib library.If you have a C28x with floating-point device and wish to mix IQmath and native floating-point,then use the IQmath_fpu32.lib.This file contains all of the IQmath functions in object format.The library is constructed such that ONLY the functions that are used are included as part of the project.This minimizes code size.The linker command file should be updated to properly access the IQmath lookup tables and place the IQmath code in the memory block you wish.These sections are described later in this chapter.Call the functions using the _iq and _iqN data types along with the C-code function definitions.For example,the following code contains a call to the IQ25sin routines in IQmath Library:#include#define PI 3.14159 _iq input,sin_out;void main(void)/*0.25 x PI radians represented in Q29 format*/input=_IQ29(0.25*PI);sin_out=_IQ29sin(input);3.4.Calling an IQmath function from C+In C+the _iq type becomes the iq class.This allows for function overloading of operators such as multiply and divide.To access the library from C+follow these steps:Include both the IQmathLib.h and the IQmathCPP.h header file as shown below:extern C#include IQmathLib.h#include IQmathCPP.h Link your code with the IQmath object code library.This will normally be the IQmath.lib library.If you have a C28x with floating-point device and wish to mix IQmath and native floating-point,then use the IQmath_fpu32.lib.Notice the same library is used by both C and C+code.This file contains all of the IQmath functions in object format.The library is constructed such that ONLY the functions that are used are included as part of the project.This minimizes code size.The linker command file should be updated to properly access the IQmath lookup tables and place the IQmath code in the memory block you wish.These sections are described later in this chapter.Texas Instruments Inc.,2002-2011 12 Call the functions using the iq and iqN classes along with the C+code function definitions.In C+the functions are called without the leading und