Home

Stellaris IQmath Library User's Guide

1. for the global IQ format Parameters A is the input value in IQ format Pos is the positive limit in IQ format Neg is the negative limit in IQ format Description This function limits the input IQ number between the range specified by the positive and nega tive limits Returns Returns the saturated input value 38 September 05 2012 September 05 2012 39 IMPORTANT NOTICE Texas Instruments Incorporated and its subsidiaries Tl reserve the right to make corrections modifications enhancements improvements and other changes to its products and services at any time and to discontinue any product or service without notice Customers should obtain the latest relevant information before placing orders and should verify that such information is current and complete All products are sold subject to Tl s terms and conditions of sale supplied at the time of order acknowledgment Tl warrants performance of its hardware products to the specifications applicable at the time of sale in accordance with Tl s standard warranty Testing and other quality control techniques are used to the extent TI deems necessary to support this warranty Except where mandated by government requirements testing of all parameters of each product is not necessarily performed Tl assumes no liability for applications assistance or customer product design Customers are responsible for their products and applications using TI components To minimize t
2. in IQ format September 05 2012 33 Mathematical Functions Description This function computes the base e exponential value of the input and saturates the result if it exceeds the range of the IQ format in use Returns Returns the base e exponential of the input 6 2 2 _lQNexp2 Computes the base 2 exponential value of an IQ number Prototype _igN _TQNexp2 _igN A for a specific IQ format 1 lt N lt 30 or _ig _IQexp2 _ig A for the global IQ format Parameters A is the input value in IQ format Description This function computes the base 2 exponential value of the input and saturates the result if it exceeds the range of the IQ format in use Returns Returns the base 2 exponential of the input 6 2 3 _IlQNisart Computes the inverse square root of an IQ number Prototype EGN _TOQNisqrt _igN A for a specific IQ format 1 lt N lt 30 or ig _TQisqrt _iq A for the global IQ format Parameters A is the input value in IQ format 34 September 05 2012 Mathematical Functions Description This function computes the inverse square root 1 sqrt of the input and saturates the result if it exceeds the range of the IQ format in use Negative inputs result in an output of 0 Returns Returns the inverse square root of the input 6 2 4 _lQNmag Computes the magnitude of a two dimensional vector Prototype _igN _TOQNmag _igN A _iqN B for a specific IQ forma
3. the cosine of the input value Note This function is not available for IQ30 format because the full input range through 7 cannot be represented in 1Q30 format which ranges from 2 through 2 30 September 05 2012 Returns The cosine of the input value 5 2 7 _IQNcosPU Computes the cosine of the input value in cycles per unit Prototype _igN _TONcosPU _iqN A for a specific IQ format 1 lt N lt 30 or at _TQcosPU _ig A for the global IQ format Parameters A is the input value in cycles per unit in IQ format Description This function computes the cosine of the input value Returns The cosine of the input value 5 2 8 _IQNsin Computes the sine of the input value Prototype _igN _TONsin _igN A for a specific IQ format 1 lt N lt 29 in or 19 _TQsin _ig A for the global IQ format Parameters A is the input value in radians in IQ format Description This function computes the sine of the input value Note Trigonometric Functions This function is not available for IQ30 format because the full input range through 7 cannot be represented in 1Q30 format which ranges from 2 through 2 September 05 2012 31 Trigonometric Functions Returns The sine of the input value 5 2 9 _IQNsinPU Computes the sine of the input value in cycles per unit Prototype _igN _TONsinPU _igqN A for a specific IQ format 1 lt N lt 30 at or ig _TO
4. 1Q30 format which ranges from 2 through 2 Returns The inverse cosine of the input value in radians _IQNasin Computes the inverse sine of the input value Prototype _igN _TQNasin _igN A for a specific IQ format 1 lt N lt 29 or ig _TQasin _ig A for the global IQ format Parameters A is the input value in IQ format Description This function computes the inverse sine of the input value Note This function is not available for Q30 format because the full output range through 7 cannot be represented in 1Q30 format which ranges from 2 through 2 Returns The inverse sine of the input value in radians _IQNatan Computes the inverse tangent of the input value September 05 2012 5 2 4 Trigonometric Functions Prototype _igN _TQNatan _igN A for a specific IQ format 1 lt N lt 29 or _igq _IQatan _ig A for the global IQ format Parameters A is the input value in IQ format Description This function computes the inverse tangent of the input value Note This function is not available for Q30 format because the full output range through 7 cannot be represented in 1Q30 format which ranges from 2 through 2 Returns The inverse tangent of the input value in radians _IQNatan2 Computes the inverse four quadrant tangent of the input point Prototype _igN _TQNatan2 _igN A _iqgN B for a specific IQ format 1 lt N lt 29 ia or iq
5. 750 000 000 0 250 000 000 1 073 741 824 1 073 741 823 500 000 000 0 500 000 000 In addition to these specific IQ format types there is an addition type that corresponds to the GLOBAL_Q format This is _ig and it matches one of the above IQ formats based on the setting Of GLOBAL_Q Calling Qmath Functions From C In order to call an Qmath function from C or from C using the normal C bindings the IQmath C header file I0omath TO0mathLib h must be included Then the _iq and _iqN data types along with the Qmath functions can be used by the application As an example the following code performs some simple arithmetic in 1Q24 format include IQmath IQmathLib h int main void _iq24 X Y 2 X YE _1024 1 0 _1024 7 0 oll Z _1024div X Y Calling Qmath Functions From C In C the _iq type becomes the ig class allowing for operator overloading of operations such as multiply and divide To access the library from C the lQmath C header file IQmath IQmathCPP h must be included after the IQmath C header file has been included Then call the functions using the ig and iqN classes along with the C functions which have the leading underscore removed and the math operations overloaded For example CCode Cr Code Note 7 iQ data types _IO A _ION A IQ A ION A Convert float to IQ iva 8 osata 10sqrt As an example the following code is equivalent to the C example prov
6. Qmpy8 1 30 The number of execution cycles and program memory usage provided above assumes 1Q24 format Execution cycles may vary by a few cycles for other IQ formats and program memory usage may vary by a few bytes for other IQ formats m The number of execution cycles provided in the table includes the call and return and assumes that the IQmath library is running from internal flash m Accuracy should always be tested and verified within the end application September 05 2012 17 Arithmetic Functions 4 2 4 2 1 4 2 2 4 2 3 API Functions _IQdiv2 Divides an IQ number by two Prototype _igN _IQdiv2 _iqN A Parameters A is the number to be divided in IQ format Description This function divides an IQ number by two This will work for any IQ format Returns Returns the number divided by two _IQdiv4 Divides an IQ number by four Prototype _igN _IQdiv4 _igN A Parameters A is the number to be divided in IQ format Description This function divides an IQ number by four This will work for any IQ format Returns Returns the number divided by four _IQdiv8 Divides an IQ number by eight Prototype _igN _IQdiv8 _iqN A Parameters A is the number to be divided in IQ format Description This function divides an IQ number by eight This will work for any IQ format Returns Returns the number divided by eight September 05 2012 4 2 4 4 2 5 4 2 6 Arithmet
7. Stellaris Qmath Library USER S GUIDE I TEXAS INSTRUMENTS SW IQMATH UG 9453 Copyright 2010 2012 Texas Instruments Incorporated Copyright Copyright O 2010 2012 Texas Instruments Incorporated All rights reserved Stellaris and StellarisWare are registered trademarks of Texas Instruments ARM and Thumb are registered trademarks and Cortex is a trademark of ARM Limited Other names and brands may be claimed as the property of others A please be aware that an important notice concerning availability standard warranty and use in critical applications of Texas Instruments semicon ductor products and disclaimers thereto appears at the end of this document Texas Instruments 108 Wild Basin Suite 350 m Austin TX 78746 13 TEXAS E INSTRUMENTS http www ti com stellaris e mu E E E E HE ortex Intelligent Processors by ARM a lu oc Llu 5 a E Revision Information This is version 9453 of this document last updated on September 05 2012 2 September 05 2012 Table of Contents Table of Contents CONSTE 2 e A ae ee ee BG eae oe Se Oh Gee ee 2 Revision Information a 2 1 METODO oe ie ee ee A a BP a 5 2 Using The lQmath Library 2 m2 7 cia a AA 7 2 2 Calling lQmath Functions FromC s c ca resas maa neam aaa e e eea aa a 8 23 Salling lQmath Functions From G o o e eee oe ee a ee ee ee ee oa aa a 8 2 4 Selecting The GLOBAL_Q ForMat ee 9 2 5 C
8. _IQatan2 _ig A iq B for the global IQ format Parameters A is the X coordinate input value in IQ format B is the Y coordinate input value in IQ format Description This function computes the inverse four quadrant tangent of the input point Note This function is not available for Q30 format because the full output range through 7 cannot be represented in 1Q30 format which ranges from 2 through 2 Returns The inverse four quadrant tangent of the input point in radians September 05 2012 29 Trigonometric Functions 5 25 _ QNatan2PU Computes the inverse four quadrant tangent of the input point returning the result in cycles per unit Prototype _igN _TOQNatan2PU _iqN A _iqN B for a specific IQ format 1 lt N lt 30 ia or 18 _TQatan2PU _ig A iq B for the global IQ format Parameters A is the X coordinate input value in IQ format B is the Y coordinate input value in IQ format Description This function computes the inverse four quadrant tangent of the input point returning the result in cycles per unit Returns The inverse four quadrant tangent of the input point in cycles per unit 5 2 6 _IQNcos Computes the cosine of the input value Prototype _igN _TQNcos _igN A for a specific IQ format 1 lt N lt 29 or _igq _TQcos _igq A for the global IQ format Parameters A is the input value in radians in IQ format Description This function computes
9. as 75265 Copyright 2010 2012 Texas Instruments Incorporated 40 September 05 2012
10. business practice Tl is not responsible or liable for any such statements TI products are not authorized for use in safety critical applications such as life support where a failure of the TI product would reasonably be expected to cause severe personal injury or death unless officers of the parties have executed an agreement specifically governing such use Buyers represent that they have all necessary expertise in the safety and regulatory ramifications of their applications and acknowledge and agree that they are solely responsible for all legal regulatory and safety related requirements concerning their products and any use of TI products in such safety critical applications notwithstanding any applications related information or support that may be provided by TI Further Buyers must fully indemnify TI and its representatives against any damages arising out of the use of TI products in such safety critical applications TI products are neither designed nor intended for use in military aerospace applications or environments unless the TI products are specifi cally designated by TI as military grade or enhanced plastic Only products designated by TI as military grade meet military specifications Buyers acknowledge and agree that any such use of TI products which TI has not designated as military grade is solely at the Buyer s risk and that they are solely responsible for compliance with all legal and regulatory requirements in connectio
11. ethod changes the GLOBAL_ 0 value for the entire application The method that is most appropriate varies from application to application Converting An IQmath Application To Floating Point An lQmath application can be easily converted to use floating point math instead of Qmath MATH_TYPE selects the type of math to use it can have one of two values m TO MATH the default value which performs all Qmath functions using fixed point arithmetic in the IQmath library m FLOAT_MATH which provides stubs for all the Qmath functions causing the arithmetic to be done in floating point using the tool chain s C and math library September 05 2012 9 Using The IQmath Library 2 6 10 By changing the definition of MATH_TYPE to FLOAT_MATH all the IQmath calls are replaced by their floating point equivalents This change can be easily made in one of two ways m In the source file the MATH_TYPE can be selected prior to including TQmath IQmathLib h The following example selects floating point math El Select floating point math define MATH_TYPE FLOAT_MATH include IQmath TQmathLib h m In the project file add a predefined value for MATH_TYPE for the entire project The method to add a predefined value varies from tool chain to tool chain The first method allows different modules in the application to use different math types while the second method changes the math type for the entire application The
12. he risks associated with customer products and applications customers should provide adequate design and operating safeguards TI does not warrant or represent that any license either express or implied is granted under any TI patent right copyright mask work right or other TI intellectual property right relating to any combination machine or process in which TI products or services are used Information published by TI regarding third party products or services does not constitute a license from TI to use such products or services or a warranty or endorsement thereof Use of such information may require a license from a third party under the patents or other intellectual property of the third party or a license from TI under the patents or other intellectual property of TI Reproduction of TI information in Tl data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties conditions limitations and notices Reproduction of this information with alteration is an unfair and deceptive business practice TI is not responsible or liable for such altered documentation Information of third parties may be subject to additional restrictions Resale of TI products or services with statements different from or beyond the parameters stated by TI for that product or service voids all express and any implied warranties for the associated Tl product or service and is an unfair and deceptive
13. ic Functions _IQdiv16 Divides an IQ number by sixteen Prototype _igN _IQdivl16 _igN A Parameters A is the number to be divided in IQ format Description This function divides an IQ number by sixteen This will work for any IQ format Returns Returns the number divided by sixteen _IQdiv32 Divides an IQ number by thirty two Prototype _igN _IQdiv32 _igqN A Parameters A is the number to be divided in IQ format Description This function divides an IQ number by thirty two This will work for any IQ format Returns Returns the number divided by thirty two _IQdiv64 Divides an IQ number by sixty four Prototype _igN _TIQdiv 4 _iqN A Parameters A is the number to be divided in IQ format Description This function divides an IQ number by sixty four This will work for any IQ format Returns Returns the number divided by sixty four September 05 2012 19 Arithmetic Functions 4 2 7 4 2 8 4 2 9 20 _lQmpy2 Multiplies an IQ number by two Prototype _igN _TQmpy2 _igN A Parameters A is the number to be multiplied in IQ format Description This function multiplies an IQ number by two This will work for any IQ format Returns Returns the number multiplied by two _lQmpy4 Multiplies an IQ number by four Prototype _igN _IQmpy4 _iqN A Parameters A is the number to be multiplied in IQ format Description This function multiplies an IQ
14. ided above but using the September 05 2012 2 4 2 5 Using The Qmath Library C functions include IQmath IQmathLib h include IQmath IQmathCPP h int main void iq24 X Y 2 Xx Y 1024 1 0 1024 7 0 Z X Y Selecting The GLOBAL_Q Format Numerical precision and dynamic range requirements vary considerably from one application to an other The IQmath library provides a GLOBAL_Q format using the _i q data type that an application can use to perform its computations in a generic IQ format which can be changed at compile time An application written using the GLOBAL_Q format can be changed from one IQ format to another by simply changing the GLOBAL_Q value and recompiling allowing the precision and performance effects of different IQ formats to be easily measured and evaluated The default GLOBAL_ 0 format is 1Q24 This can be easily overridden in one of two ways m n the source file the GLOBAL_Q format can be selected prior to including IQmath IQmathLib h The following example selects a GLOBAL_Q format of IQ8 Set GLOBAL_Q to 8 prior to including IQmathLib h i define GLOBAL_Q 8 include IQmath TQmathLib h m In the project file add a predefined value for GLOBAL_Q for the entire project The method to add a predefined value varies from tool chain to tool chain The first method allows different modules in the application to have different GLOBAL_Q values while the second m
15. ivides two IQ numbers Prototype _igN _IOQNdiv _igN A _iqN B for a specific IQ format 1 lt N lt 30 gt or _igq _IQdiv _ig A ig B for the global IQ format Parameters A is the numerator in IQ format B is the denominator in IQ format Description This function divides two IQ numbers returning the quotient in IQ format The result is satu rated if it exceeds the capacity of the IQ format and division by zero always results in positive saturation regardless of the sign of A Returns Returns the quotient in IQ format 4 2 14 _lQNmpy Multiplies two IQ numbers Prototype _igN _IONmpy _iaN A _iqN B for a specific IQ format 1 lt N lt 30 im or _ig _TOmpy _ig A _iq B for the global IQ format Parameters A is the first number in IQ format B is the second number in IQ format 22 September 05 2012 Arithmetic Functions Description This function multiplies two IQ numbers returning the product in IQ format The result is neither rounded nor saturated so if the product is greater than the minimum or maximum values for the given IQ format the return value wraps around and produces inaccurate results Returns Returns the product in IQ format 4 2 15 _lQNmpyl32 Multiplies an IQ number by an integer Prototype _igN _TONmpy132 _igN A long B for a specific IQ format 1 lt N lt 30 or iq IQmpyI32 _iq A long B for the global IQ fo
16. l AMG HOS A aes EA Renee E AE 37 Introduction The miscellaneous functions are useful functions that do not otherwise fit elsewhere The following table summarizes the miscellaneous functions Function Execution Accuracy Program Output Memory Name Cycles bits Format bytes ons 130332665 6 ON ION onsa 130 6 obs 14 ION ION m The number of execution cycles and program memory usage provided above assumes 1Q24 format Execution cycles may vary by a few cycles for other IQ formats and program memory usage may vary by a few bytes for other IQ formats m The number of execution cycles provided in the table includes the call and return and assumes that the IQmath library is running from internal flash m Accuracy should always be tested and verified within the end application API Functions _IQNabs Finds the absolute value of an IQ number Prototype _igN _TQNabs _igN A for a specific IQ format 1 lt N lt 30 or _igq _TQabs _ig A for the global IQ format Parameters A is the input value in IQ format Description This function computes the absolute value of the input IQ number September 05 2012 37 Miscellaneous Functions Returns Returns the absolute value of the input 7 2 2 _ QNsat Satures an IQ number Prototype _igN _TONsat _igN A _igN Pos _iqN Neg for a specific IQ format 1 lt N lt 30 gt or _igq _TQsat _ig A ci Posy iq Neg
17. method that is most appro priate varies from application to application lQmath Function Groups The IQmath routines are organized into five groups m Format conversion functions methods to convert numbers to and from the various IQ formats m Arithmetic functions methods to perform basic arithmetic on IQ numbers addition subtaction multiplication division m Trigonometric functions methods to perform trigonometric functions on IQ numbers sin cos atan and so on Mathematical functions methods to perform advanced arithmetic on IQ numbers square root e and so on m Miscellaneous miscellaneous methods that operate on IQ numbers saturation and absolute value In the chapters that follow the methods in each of these groups is covered in detail September 05 2012 3 3 1 3 2 3 2 1 Format Conversion Functions Format Conversion Functions miodu Oasan a aa bhi ea tine eta A 11 Pl AMG MOS A A A A 11 Introduction The format conversion functions provide a way to convert numbers to and from various IQ formats There are functions to convert IQ numbers to and from single and double precision floating point numbers to and from integers to and from strings to and from 16 bit QN format numbers to and from various IQ formats and to extract the integer and fractional portion of an IQ number The following table summarizes the format conversion functions Function Execution Accuracy Program Outpu
18. n with such use Tl products are neither designed nor intended for use in automotive applications or environments unless the specific TI products are designated by Tl as compliant with ISO TS 16949 requirements Buyers acknowledge and agree that if they use any non designated products in automotive applications TI will not be responsible for any failure to meet such requirements Following are URLs where you can obtain information on other Texas Instruments products and application solutions Products Applications Audio www ti com audio Automotive and Transportation www ti com automotive Amplifiers amplifier ti com Communications and Telecom www ti com communications Data Converters dataconverter ti com Computers and Peripherals www ti com computers DLP Products www dlp com Consumer Electronics www ti com consumer apps DSP dsp ti com Energy and Lighting www ti com energy Clocks and Timers www ti com clocks Industrial www ti com industrial Interface interface ti com Medical www ti com medical Logic logic ti com Security www ti com security Power Mgmt power ti com Space Avionics and Defense www ti com space avionics defense Microcontrollers microcontroller ti com Video and Imaging www ti com video RFID www ti rfid com OMAP Mobile Processors www ti com omap Wireless Connectivity www ti com wirelessconnectivity TI E2E Community Home Page e2e ti com Mailing Address Texas Instruments Post Office Box 655303 Dallas Tex
19. number by four This will work for any IQ format Returns Returns the number multiplied by four _IQmpy8 Multiplies an IQ number by eight Prototype _igN _IQmpy8 _iqN A Parameters A is the number to be multiplied in IQ format Description This function multiplies an IQ number by eight This will work for any IQ format Returns Returns the number multiplied by eight September 05 2012 4 2 10 4 2 11 4 2 12 Arithmetic Functions _lQmpy16 Multiplies an IQ number by sixteen Prototype _igN _IOmpy16 _iaN A Parameters A is the number to be multiplied in IQ format Description This function multiplies an IQ number by sixteen This will work for any IQ format Returns Returns the number multiplied by sixteen _lQmpy32 Multiplies an IQ number by thirty two Prototype _igN IQmpy32 _iqN A Parameters A is the number to be multiplied in IQ format Description This function multiplies an IQ number by thirty two This will work for any IQ format Returns Returns the number multiplied by thirty two _lQmpy64 Multiplies an IQ number by sixty four Prototype _igN IQmpy64 _iqN A Parameters A is the number to be multiplied in IQ format Description This function multiplies an IQ number by sixty four This will work for any IQ format Returns Returns the number multiplied by sixty four September 05 2012 21 Arithmetic Functions 4 2 13 _lQNdiv D
20. number in QN format Prototype short _TQtoQN _ig A for a specific Q format 1 lt N lt 15 Parameters A is the IQ number to be converted Description This function converts an IQ number in the global IQ format to a 16 bit number in QN format Returns Returns the QN number corresponding to the input IQ number _QNtolQ Converts a 16 bit QN number to an IQ number Prototype ig _ONtoIQ short A for a specific Q format 1 lt N lt 15 Parameters A is the QN number to be converted Description This function converts a 16 bit QN number to an IQ number in the global IQ format Returns Returns the IQ number corresponding to the input QN number September 05 2012 4 1 Arithmetic Functions Arithmetic Functions A CATERER TEE TE AAA A lanbieneehsm it dametaas sane E AAT 17 Pl AMG OWS A A 18 Introduction The arithmetic functions provide basic arithmetic addition subtraction multiplication division of IQ numbers No special functions are required for addition or subtraction IQ numbers can simply be added and subtracted using the underlying C addition and subtraction operators Multiplication and division require special treatment in order to maintain the IQ number of the result The following table summarizes the arithmetic functions Program Function Memory Name _lQdiv2 1 30 _lQdiv4 1 30 _1Qdiv8 1 30 _IQdiv16 1 30 _IQdiv32 1 30 _lQdiv64 1 30 _lQmpy2 1 30 _IQmpy4 1 30 _I
21. onverting An lQmath Application To Floating Point aoaaa o ooo e 9 26 lQmath Funcion GROUBS o e a ecce ee ee a a a a a eee ee D A i 10 3 Format Conversion Functions aaao a e eee ee eee 2 2 a 11 SI is A tee ee ee Sh ds a eed hs Dos Ha ap deh de SE ee GI ee E ee ee 11 32 API Functiong gt ssr 2 2 6 ee ee 11 4 Arithmetic Functions 0 00 oaa aaa a 17 A OOS sca ee ee es ee ae ae Sw wd A es my aye a a A eet a A Awe we a 17 d2 APLPUNCIONS ih ee ee PSA eo ee Ree SOD e we be a oe a a aes 18 5 Trigonometric Functions es 27 Dat WAMGOUCWON a ake eee ee a Sek Gi ee we ae ek A ee we a ee 27 o2 APIFUNGCIONS o een eee 4S ere eel RE RAW ey Doe eee Uae eee eS 27 6 Mathematical Functions 2 0 0 eee es 33 GI ss E sa nana See neat oe ee ee OD a a A EA tee a we a 33 02 APLFUNCUDOS o oci ir eae BGS ae Sa gh eee Mae a ke ee de e de oe eee 33 7 Miscellaneous Functions 1 22 ee lt lt lt lt 2 37 fal INTERNA A aa aaa a a a 37 72 APLPUDCUONS a s ema ee ec ke aa a ew ee 37 IMPORTANT NOTICE caw ee a eee a A 40 September 05 2012 3 Table of Contents 4 September 05 2012 Introduction 1 Introduction The Texas Instruments Stellaris Qmath Library is a collection of highly optimized and high precision mathematical functions for C C programmers to seamlessly port a floating point algo rithm into fixed point code on Stellaris devices These routines are
22. ototype _1GN _ION float A for a specific IQ format 1 lt N lt 30 or iq _IQ float A for the global IQ format Parameters A is the floating point variable or constant to be converted Description This function converts a floating point constant or variable into the equivalent IQ number If the input value is greater than the minimum or maximum values for the given IQ format the return value wraps around and produces inaccurate results Returns Returns the IQ number corresponding to the floating point variable or constant _IQNfrac Returns the fractional portion of an IQ number September 05 2012 Format Conversion Functions Prototype _igN _TONfrac _igN A for a specific IQ format 1 lt N lt 30 or _igq _TQfrac _ig A for the global IQ format Parameters A is the input number in IQ format Description This function returns the fractional portion of an IQ number as an IQ number Returns Returns the fractional portion of the input IQ number 3 2 4 _IQNint Returns the integer portion of an IQ number Prototype long _TONint _igN A for a specific IQ format 1 lt N lt 30 or long _TIQint _ig A for the global IQ format Parameters A is the input number in IQ format Description This function returns the integer portion of an IQ number Returns Returns the integer portion of the input IQ number 3 25 _lQNtoa Converts an IQ number to a s
23. owing table provides the characteristics of the various IQ formats the C type the number of integer bits the number of fractional bits the smallest negative value that can be represented the largest positive value that can be represented and the smallest difference that can be represented Range z Type L Pts A clation Tye agar Mn y Fractional PM Pies 4 28 ef ____7 999 999996 0 000 000 004 Pies 6 26 se __ 81 999 999 985 0 000 000015 iaa 8 24 128 127 999 999 940 0 000 000060 iaa 9 23 256 255999999881 0 000 000119 1420 ETE 0 000 003 815 Tia 0 000 007 629 a 0 000 015 259 _igl _igl _igl _igl igl Ol Oy 65 536 65 535 999 969 483 0 000 030 518 D w 131 072 131 071 999 938 965 0 000 061 035 262 144 262 143 999 877 930 0 000 122 070 e N 0 000 488 281 0 000 976 563 0 001 953 125 0 003 906 250 H Q SY fl fe OQ H 1Q Q 1 00 16 777 216 16 777 215 992 187 500 0 007 812 500 33 554 432 33 554 431 984 375 000 0 015 625 000 L 0 000244 141 NECE o aa EES 26 fd A September 05 2012 7 Using The IQmath Library 2 2 2 3 Type ra Pesolution ee OA 108 864 sr TOR BE BEETS OOO 108 863 968 750 000 0 031 250 000 laa 28 4 134 217 728 134 217 727 937 500 000 0 062 500 000 268 435 456 268 435 455 875 000 000 0 125 000 000 536 870 912 536 870 911
24. radians output for the inverse functions as well as a cycles per unit format where the range 0 1 is mapped onto the circle in other words 0 0 is O radians 0 25 is 7 2 radians 0 5 is 7 radians 0 75 is 37 2 radians and 1 0 is 27 radians The following table summarizes the trigonometric functions Function Execution Accuracy Program Output Name Cycles bits memory Format bytes ee ee eee lONatan2PO 1 30 89 otobis 208 ONION TON The number of execution cycles and program memory usage provided above assumes 1Q24 format Execution cycles may vary by a few cycles for other IQ formats and program memory usage may vary by a few bytes for other IQ formats m The number of execution cycles provided in the table includes the call and return and assumes that the Qmath library is running from internal flash Accuracy should always be tested and verified within the end application API Functions _IQNacos Computes the inverse cosine of the input value Prototype _igN _TQNacos _igN A for a specific IQ format 1 lt N lt 29 September 05 2012 27 Trigonometric Functions 5 2 2 5 2 3 28 or alg _IQacos _ig A for the global IQ format Parameters A is the input value in IQ format Description This function computes the inverse cosine of the input value Note This function is not available for Q30 format because the full output range through 7 cannot be represented in
25. rmat Parameters A is the first number in IQ format B is the second number in integer format Description This function multiplies an IQ number by an integer returning the product in IQ format The result is not saturated so if the product is greater than the minimum or maximum values for the given IQ format the return value wraps around and produces inaccurate results Returns Returns the product in IQ format 4 2 16 _IQNmpyl32frac Multiplies an IQ number by an integer returning the fractional portion of the product Prototype _igN _TONmpy1l32frac _iqN A long B for a specific IQ format 1 lt N lt 30 or ig _IQmpyI32frac _iq A long B September 05 2012 23 Arithmetic Functions for the global IQ format Parameters A is the first number in IQ format B is the second number in integer format Description This function multiplies an IQ number by an integer returning the fractional portion of the product in IQ format Returns Returns the fractional portion of the product in IQ format 4 2 17 _lQNmpyl32int Multiplies an IQ number by an integer returning the integer portion of the result Prototype long _TIONmpyI32int _iqN A long B for a specific IQ format 1 lt N lt 30 ey or long _TompylI32int ig A long B for the global IQ format Parameters A is the first number in IQ format B is the second number in integer format Description This function m
26. sinPU _ig A for the global IQ format Parameters A is the input value in cycles per unit in IQ format Description This function computes the sine of the input value Returns The sine of the input value 32 September 05 2012 6 6 1 6 2 6 2 1 Mathematical Functions Mathematical Functions A PPP a shied dhe anbiene hsm id Mab etaas tenia e ld eee a aan atere 33 Pl AMG Mee A apes Seas men eeus cee T aon eeaa 33 Introduction The mathematical functions compute a variety of advanced mathematical functions for IQ numbers The following table summarizes the mathematical functions Function Execution Accuracy Program Output Name Cycles bits Memory Format bytes ono o o 30665 184 TON ON m The number of execution cycles and program memory usage provided above assumes 1Q24 format Execution cycles may vary by a few cycles for other IQ formats and program memory usage may vary by a few bytes for other IQ formats m The number of execution cycles provided in the table includes the call and return and assumes that the IQmath library is running from internal flash m Accuracy should always be tested and verified within the end application API Functions _IQNexp Computes the base e exponential value of an IQ number Prototype _igN _TOQNexp _igN A for a specific IQ format 1 lt N lt 30 gt or iq IQexp _iq A for the global IQ format Parameters A is the input value
27. t 1 lt N lt 30 oy or 49 _IQmag _ig A _ig B for the global IQ format Parameters A is the first input value in IQ format B is the second input value in IQ format Description This function computes the magnitude of a two dimensional vector provided in IQ format The result is always positive and saturated if it exceeds the range of the IQ format in use This is functionally equivalent to _IQNsqrt _lIQNrmpy A A _IQNrmpy B B but provides better accuracy speed and intermediate overflow handling than building this computation from _IQNsqrt and _IQNrmpy For example _1Q16mag _ Q16 30000 _1Q16 1000 correctly returns _1Q16 30016 6 even though the intermediate value of _l1Q16rmpy _lQ16 30000 _1Q16 30000 overflows an _iq16 Returns Returns the inverse square root of the input 6 2 5 _lQNsqrt Computes the square root of an IQ number Prototype _igN _TONsqrt _igN A for a specific IQ format 1 lt N lt 30 Or September 05 2012 35 Mathematical Functions _ig _IQsqrt iq A for the global IQ format Parameters A is the input value in IQ format Description This function computes the square root of the input Negative inputs result in an output of 0 Returns Returns the square root of the input 36 September 05 2012 7 7 1 7 2 7 2 1 Miscellaneous Functions Miscellaneous Functions PP A shied dhe anbhene hsm dam etaas wena hela eaaaaenes 37 P
28. t Memory Name Cycles bits Format bytes a A C mna va foa ON Een Oa 0 8 as IEA E e ON The number of execution cycles and program memory usage provided above assumes 1Q24 format Execution cycles may vary by a few cycles for other IQ formats and program memory usage may vary by a few bytes for other IQ formats m The number of execution cycles provided in the table includes the call and return and assumes that the IQmath library is running from internal flash m Accuracy should always be tested and verified within the end application API Functions _atolQN Converts a string to an IQ number Prototype _igN _atolQN const char A September 05 2012 11 Format Conversion Functions 3 2 2 3 2 3 for a specific IQ format 1 lt N lt 30 im or ig _atoIQ const char xA for the global IQ format Parameters A is the string to be converted Description This function converts a string into an IQ number The input string may contain in order an optional sign and a string of digits optionally containing a radix character A unrecognized character ends the string and returns zero If the input string converts to a number greater than the minimum or maximum values for the given IQ format the return value is limited to the minimum or maximum value Returns Returns the IQ number corresponding to the input string _IQN Converts a floating point constant or variable into an IQ number Pr
29. the second number in IQ format Description This function multiplies two IQ numbers returning the product in IQ format The result is rounded but not saturated so if the product is greater than the minimum or maximum values for the given IQ format the return value wraps around and produces inaccurate results September 05 2012 25 Arithmetic Functions Returns Returns the product in IQ format 4 2 20 _lQNrsmpy Multiplies two IQ numbers with rounding and saturation Prototype _igN _TONrsmpy _igN A _igqgN B for a specific IQ format 1 lt N lt 30 in or Ag _TQrsmpy _iq A _iq B for the global IQ format Parameters A is the first number in IQ format B is the second number in IQ format Description This function multiplies two IQ numbers returning the product in IQ format The result is rounded and saturated so if the product is greater than the minimum or maximum values for the given IQ format the return value is saturated to the minimum or maximum value for the given IQ format as appropriate Returns Returns the product in IQ format 26 September 05 2012 9 1 5 2 5 2 1 Trigonometric Functions Trigonometric Functions Unesco AAA Ono A O 27 Pl AMG MOS A E eaee hoes 27 Introduction The trigonometric functions compute a variety of the trigonometric functions for IQ numbers Func tions are provided that take the traditional radians inputs or produce the traditional
30. toF _iqN A for a specific IQ format 1 lt N lt 30 or float IQtoF ig A for the global IQ format Parameters A is the IQ number to be converted Description This function converts an IQ number into a single precision floating point number Since single precision floating point values have only 24 bits of mantissa 8 bits of accuracy will be lost via this conversion Returns Returns the single precision floating point number corresponding to the input IQ number _IQNtolQ Converts an IQ number in IQN format to the global IQ format Prototype _ig _IQNtolIQ _iqN A for a specific IQ format 1 lt N lt 30 Parameters A is IQ number to be converted Description This function converts an IQ number in the specified IQ format to an IQ number in the global IQ format Returns Returns the IQ number converted into the global IQ format _IQtolQN Converts an IQ number in the global IQ format to the IQN format Prototype _igN _TOtolQN _ig A for a specific IQ format 1 lt N lt 30 September 05 2012 15 Format Conversion Functions 3 2 10 3 2 11 16 Parameters A is the IQ number to be converted Description This function converts an IQ number in the global IQ format to an IQ number in the specified IQ format be limited to the minimum or maximum value Returns Returns the IQ number converted to the specified IQ format _IQtoQN Converts an IQ number to a 16 bit
31. tring Prototype int _IONtoa char A September 05 2012 13 Format Conversion Functions 3 2 6 3 2 7 14 const char xB iqN C for a specific IQ format 1 lt N lt 30 or ime int _IQtoa char A const char xB ig C for the global IQ format Parameters A is a pointer to the buffer to store the converted IQ number B is the format string specifying how to convert the IQ number Must be of the form C is the IQ number to convert Description This function converts the IQ number to a string using the specified format Returns Returns 0 if there is no error 1 if the width is too small to hold the integer characters and 2 if an illegal format was specified If MATH_TYPE is set to FLOAT_MATH the return is the number of characters written into the output buffer _IQNtoD Converts an IQ number to a double precision floating point number Prototype double _IQNtoD _igN A for a specific IQ format 1 lt N lt 30 or double TOtoD ig A for the global IQ format Parameters A is the IQ number to be converted Description This function converts an IQ number into a double precision floating point number Returns Returns the double precision floating point number corresponding to the input IQ number _IQNtoF Converts an IQ number to a single precision floating point number September 05 2012 3 2 8 3 2 9 Format Conversion Functions Prototype float _IQN
32. typically used in computationally intensive real time applications where optimal execution speed and high accuracy is critical By us ing the I Qmath library it is possible to achieve execution speeds considerably faster than equivalent code written using floating point math The following tool chains are supported Keil RealView Microcontroller Development Kit m CodeSourcery Sourcery G for Stellaris EABI m IAR Embedded Workbench Code Red Technologies tools m Texas Instruments Code Composer Studio September 05 2012 5 Introduction 6 September 05 2012 Using The Qmath Library 2 Using The lQmath Library A ee Cane SERS Teas Sree Tee etre Tre ene eee eee eee e eee Terr Tet eres ee eats ee 7 Calling Omeath Funcions Fom E os AAA A ARA 8 Calling Tomah Funcions From Es ii 8 Selecta he GLOBAL CUESTMAL cc RA AAA AAA 9 Converting An Qmath Application To Floating Point 0 0 cece cece eee eee eee e nee eee een anes 9 CIMA Funcion ADS A A A a 10 2 1 Qmath Data Type The lQmath library uses a 32 bit fixed point signed number a long in C as its basic data type The IQ format of this fixed point number can range from IQ1 to 1Q30 where the IQ format number indicates the number of fractional bits C typedefs are provided for the various IQ formats and these IQmath data types should be used in preference to the underlying long data type to make it clear which variables are in IQ format The foll
33. ultiplies an IQ number by an integer returning the integer portion of the product The result is saturated so if the integer portion of the product is greater than the minimum or maximum values for an integer the result will be saturated to the minimum or maximum value Returns Returns the product in IQ format 4 2 18 _lQNmpylQX Multiplies two IQ numbers Prototype _igN _TONmpyIQOX _igqN A long IQA 24 September 05 2012 Arithmetic Functions iqN B long IQB for a specific IQ format 1 lt N lt 30 or i _ig _TQmpyIQX _ig A long IQA _iq B long IQB for the global IQ format Parameters A is the first number in IQ format IQA is the IQ format for the first number B is the second number in IQ format IQB is the IQ format for the second number Description This function multiplies two IQ numbers in different IQ formats returning the product in a third IQ format The result is neither rounded nor saturated so if the product is greater than the minimum or maximum values for the given output IQ format the return value will wrap around and produce inaccurate results Returns Returns the product in IQ format 4 2 19 _lQNrmpy Multiplies two IQ numbers with rounding Prototype _igN _IQNrmpy _iqN A iqN B for a specific IQ format 1 lt N lt 30 h or iq _IQrmpy _ig A iq B for the global IQ format Parameters A is the first number in IQ format B is

Stellaris IQmath Library User's Guide

Contents

Download Pdf Manuals

Related Search

Related Contents