Stellaris IQmath Library User's Guide - amoBBSd1.amobbs.com/bbs_upload782111/files_33/ourdev_582876DTQPBQ.pdfIntroduction 1 Introduction The Texas Instruments® Stellaris® IQmath

Copyright © 2010 Texas Instruments Incorporated.SW-IQMATH-UG-6459

USER’S GUIDE

Stellaris® IQmath Library

CopyrightCopyright © 2010 Texas Instruments Incorporated. All rights reserved. Stellaris and StellarisWare are registered trademarks of Texas Instruments. ARMand Thumb are registered trademarks and Cortex is a trademark of ARM Limited. Other names and brands may be claimed as the property of others.

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 Instruments108 Wild Basin, Suite 350Austin, TX 78746Main: +1-512-279-8800Fax: +1-512-279-8879http://www.ti.com/stellaris

Revision InformationThis is version 6459 of this document, last updated on September 07, 2010.

2 September 07, 2010

Table of Contents

Table of ContentsCopyright . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Revision Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 Using The IQmath Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.1 IQmath Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.2 Calling IQmath Functions From C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.3 Calling IQmath Functions From C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.4 Selecting The GLOBAL_Q Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.5 Converting An IQmath Application To Floating-Point . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.6 IQmath Function Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3 Format Conversion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.2 API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4 Arithmetic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174.2 API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

5 Trigonometric Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275.2 API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

6 Mathematical Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336.2 API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

7 Miscellaneous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377.2 API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

IMPORTANT NOTICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

September 07, 2010 3

Table of Contents


Introduction

1 IntroductionThe Texas Instruments® Stellaris® IQmath 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 typically used in computationallyintensive real-time applications where optimal execution speed and high accuracy is critical. By us-ing the IQmath library, it is possible to achieve execution speeds considerably faster than equivalentcode written using floating-point math.

The following tool chains are supported:

Keil™ RealView® Microcontroller Development Kit

CodeSourcery Sourcery G++ for Stellaris EABI

IAR Embedded Workbench®

Code Red Technologies tools

Texas Instruments Code Composer Studio™


Introduction


Using The IQmath Library

2 Using The IQmath LibraryIQmath Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Calling IQmath Functions From C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Calling IQmath Functions From C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Selecting the GLOBAL_Q Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Converting An IQmath Application To Floating-Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9IQmath Function Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.1 IQmath Data Type

The IQmath 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 IQ30, where the IQ format numberindicates the number of fractional bits. C typedefs are provided for the various IQ formats, andthese IQmath data types should be used in preference to the underlying “long” data type to make itclear which variables are in IQ format.

The following table provides the characteristics of the various IQ formats (the C type, the number ofinteger bits, the number of fractional bits, the smallest negative value that can be represented, thelargest positive value that can be represented, and the smallest difference that can be represented):

Type Bits Range ResolutionInteger Fractional Min Max_iq30 2 30 -2 1.999 999 999 0.000 000 001_iq29 3 29 -4 3.999 999 998 0.000 000 002_iq28 4 28 -8 7.999 999 996 0.000 000 004_iq27 5 27 -16 15.999 999 993 0.000 000 007_iq26 6 26 -32 31.999 999 985 0.000 000 015_iq25 7 25 -64 63.999 999 970 0.000 000 030_iq24 8 24 -128 127.999 999 940 0.000 000 060_iq23 9 23 -256 255.999 999 881 0.000 000 119_iq22 10 22 -512 511.999 999 762 0.000 000 238_iq21 11 21 -1,024 1,023.999 999 523 0.000 000 477_iq20 12 20 -2,048 2,047.999 999 046 0.000 000 954_iq19 13 19 -4,096 4,095.999 998 093 0.000 001 907_iq18 14 18 -8,192 8,191.999 996 185 0.000 003 815_iq17 15 17 -16,384 16,383.999 992 371 0.000 007 629_iq16 16 16 -32,768 32,767.999 984 741 0.000 015 259_iq15 17 15 -65,536 65,535.999 969 483 0.000 030 518_iq14 18 14 -131,072 131,071.999 938 965 0.000 061 035_iq13 19 13 -262,144 262,143.999 877 930 0.000 122 070_iq12 20 12 -524,288 524,287.999 755 859 0.000 244 141_iq11 21 11 -1,048,576 1,048,575.999 511 720 0.000 488 281_iq10 22 10 -2,097,152 2,097,151.999 023 440 0.000 976 563_iq9 23 9 -4,194,304 4,194,303.998 046 880 0.001 953 125_iq8 24 8 -8,388,608 8,388,607.996 093 750 0.003 906 250_iq7 25 7 -16,777,216 16,777,215.992 187 500 0.007 812 500_iq6 26 6 -33,554,432 33,554,431.984 375 000 0.015 625 000



Type Bits Range ResolutionInteger Fractional Min Max_iq5 27 5 -67,108,864 67,108,863.968 750 000 0.031 250 000_iq4 28 4 -134,217,728 134,217,727.937 500 000 0.062 500 000_iq3 29 3 -268,435,456 268,435,455.875 000 000 0.125 000 000_iq2 30 2 -536,870,912 536,870,911.750 000 000 0.250 000 000_iq1 31 1 -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 theGLOBAL_Q format. This is _iq, and it matches one of the above IQ formats (based on the settingof GLOBAL_Q).

2.2 Calling IQmath Functions From C

In order to call an IQmath function from C (or from C++ using the normal C bindings), the IQmath Cheader file (IQmath/IQmathLib.h) must be included. Then, the _iq and _iqN data types, alongwith the IQmath functions can be used by the application.

As an example, the following code performs some simple arithmetic in IQ24 format:

#include "IQmath/IQmathLib.h"

intmain(void){

_iq24 X, Y, Z;

X = _IQ24(1.0);Y = _IQ24(7.0);

Z = _IQ24div(X, Y);}

2.3 Calling IQmath Functions From C++

In C++, the _iq type becomes the iq class, allowing for operator overloading of operationssuch as multiply and divide. To access the library from C++, the IQmath C++ header file(IQmath/IQmathCPP.h) must be included after the IQmath C header file has been included.Then, call the functions using the iq and iqN classes along with the C++ functions, which have theleading underscore removed and the math operations overloaded. For example:

C Code C++ Code Note_iq, _iqN iq, iqN IQ data types_IQ(A), _IQN(A) IQ(A), IQN(A) Convert float to IQ_IQdiv(A, B) A / B Division_IQsqrt(A) IQsqrt(A) Square root

As an example, the following code is equivalent to the C example provided above, but using the



C++ functions:

#include "IQmath/IQmathLib.h"#include "IQmath/IQmathCPP.h"

intmain(void){

iq24 X, Y, Z;

X = IQ24(1.0);Y = IQ24(7.0);

Z = X / Y;}

2.4 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 _iq data type) that an applicationcan 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 anotherby simply changing the GLOBAL_Q value and recompiling, allowing the precision and performanceeffects of different IQ formats to be easily measured and evaluated.

The default GLOBAL_Q format is IQ24. This can be easily overridden in one of two ways:

In the source file, the GLOBAL_Q format can be selected prior to includingIQmath/IQmathLib.h. The following example selects a GLOBAL_Q format of IQ8:

//// Set GLOBAL_Q to 8 prior to including IQmathLib.h.//#define GLOBAL_Q 8#include "IQmath/IQmathLib.h"

In the project file, add a predefined value for GLOBAL_Q for the entire project. The method toadd 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 method changes the GLOBAL_Q value for the entire application. The method thatis most appropriate varies from application to application.

2.5 Converting An IQmath Application To Floating-Point

An IQmath application can be easily converted to use floating-point math instead of IQmath.MATH_TYPE selects the type of math to use; it can have one of two values:

IQ_MATH - the default value, which performs all IQmath functions using fixed-point arithmeticin the IQmath library.

FLOAT_MATH - which provides stubs for all the IQmath functions causing the arithmetic to bedone in floating-point using the tool chain’s C and math library.



By changing the definition of MATH_TYPE to FLOAT_MATH, all the IQmath calls are replaced bytheir floating-point equivalents. This change can be easily made in one of two ways:

In the source file, the MATH_TYPE can be selected prior to including IQmath/IQmathLib.h.The following example selects floating-point math:

//// Select floating-point math.//#define MATH_TYPE FLOAT_MATH#include "IQmath/IQmathLib.h"

In the project file, add a predefined value for MATH_TYPE for the entire project. The method toadd 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 thesecond method changes the math type for the entire application. The method that is most appro-priate varies from application to application.

2.6 IQmath Function Groups

The IQmath routines are organized into five groups:

Format conversion functions - methods to convert numbers to and from the various IQ formats.

Arithmetic functions - methods to perform basic arithmetic on IQ numbers (addition, subtaction,multiplication, division).

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,ex, and so on).

Miscellaneous - miscellaneous methods that operate on IQ numbers (saturation and absolutevalue).

In the chapters that follow, the methods in each of these groups is covered in detail.


Format Conversion Functions

3 Format Conversion FunctionsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

3.1 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-pointnumbers, to and from integers, to and from strings, to and from 16-bit QN format numbers, to andfrom various IQ formats, and to extract the integer and fractional portion of an IQ number. Thefollowing table summarizes the format conversion functions:

FunctionName

IQFormat

ExecutionCycles

Accuracy(bits)

ProgramMemory(bytes)

InputFormat

OutputFormat

_atoIQN 1-30 n/a n/a 304 char * IQN_IQN 1-30 n/a n/a n/a float IQN

_IQNfrac 1-30 8 32 bits 12 IQN IQN_IQNint 1-30 1 32 bits 2 IQN long_IQNtoa 1-30 n/a n/a 286 IQN char *_IQNtoD 1-30 20 n/a 52 IQN double_IQNtoF 1-30 17 n/a 36 IQN float_IQNtoIQ 1-30 1 n/a 2 IQN GLOBAL_Q_IQtoIQN 1-30 1 n/a 2 GLOBAL_Q IQN_IQtoQN 1-15 1 n/a 2 GLOBAL_Q QN_QNtoIQ 1-15 1 n/a 2 QN GLOBAL_Q

The number of execution cycles and program memory usage provided above assumes IQ24format. Execution cycles may vary by a few cycles for other IQ formats, and program memoryusage may vary by a few bytes for other IQ formats.

The number of execution cycles provided in the table includes the call and return and assumesthat the IQmath library is running from internal flash.

Accuracy should always be tested and verified within the end application.

3.2 API Functions

3.2.1 _atoIQN

Converts a string to an IQ number.

Prototype:_iqN_atoIQN(const char *A)



for a specific IQ format (1 <= N <= 30)

- or -

_iq_atoIQ(const char *A)

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) anoptional sign and a string of digits optionally containing a radix character. A unrecognizedcharacter ends the string and returns zero. If the input string converts to a number greaterthan the minimum or maximum values for the given IQ format, the return value is limited to theminimum or maximum value.

Returns:Returns the IQ number corresponding to the input string.

3.2.2 _IQN

Converts a floating-point constant or variable into an IQ number.

Prototype:_iqN_IQN(float A)


- or -

_iq_IQ(float A)


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 theinput value is greater than the minimum or maximum values for the given IQ format, the returnvalue wraps around and produces inaccurate results.

Returns:Returns the IQ number corresponding to the floating-point variable or constant.

3.2.3 _IQNfrac

Returns the fractional portion of an IQ number.



Prototype:_iqN_IQNfrac(_iqN A)


- or -

_iq_IQfrac(_iq A)


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_IQNint(_iqN A)


- or -

long_IQint(_iq A)


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.2.5 _IQNtoa

Converts an IQ number to a string.

Prototype:int_IQNtoa(char *A,



const char *B,_iqN C)


- or -

int_IQtoa(char *A,

const char *B,_iq C)


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 anillegal format was specified. If MATH_TYPE is set to FLOAT_MATH, the return is the numberof characters written into the output buffer.

3.2.6 _IQNtoD

Converts an IQ number to a double-precision floating-point number.

Prototype:double_IQNtoD(_iqN A)


- or -

double_IQtoD(_iq A)


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.

3.2.7 _IQNtoF

Converts an IQ number to a single-precision floating-point number.



Prototype:float_IQNtoF(_iqN A)


- or -

float_IQtoF(_iq A)



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 viathis conversion.

Returns:Returns the single-precision floating-point number corresponding to the input IQ number.

3.2.8 _IQNtoIQ

Converts an IQ number in IQN format to the global IQ format.

Prototype:_iq_IQNtoIQ(_iqN A)


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 globalIQ format.

Returns:Returns the IQ number converted into the global IQ format.

3.2.9 _IQtoIQN

Converts an IQ number in the global IQ format to the IQN format.

Prototype:_iqN_IQtoIQN(_iq A)





Description:This function converts an IQ number in the global IQ format to an IQ number in the specifiedIQ format. be limited to the minimum or maximum value.

Returns:Returns the IQ number converted to the specified IQ format.

3.2.10 _IQtoQN

Converts an IQ number to a 16-bit number in QN format.

Prototype:short_IQtoQN(_iq A)

for a specific Q format (1 <= N <= 15)


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.

3.2.11 _QNtoIQ

Converts a 16-bit QN number to an IQ number.

Prototype:_iq_QNtoIQ(short A)

for a specific Q format (1 <= N <= 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.


Arithmetic Functions

4 Arithmetic FunctionsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

4.1 Introduction

The arithmetic functions provide basic arithmetic (addition, subtraction, multiplication, division) ofIQ numbers. No special functions are required for addition or subtraction; IQ numbers can simplybe added and subtracted using the underlying C addition and subtraction operators. Multiplicationand division require special treatment in order to maintain the IQ number of the result. The followingtable summarizes the arithmetic functions:

FunctionName

IQFormat

ExecutionCycles

Accuracy(bits)


InputFormat

OutputFormat

_IQdiv2 1-30 1 32 bits 2 IQN IQN_IQdiv4 1-30 1 32 bits 2 IQN IQN_IQdiv8 1-30 1 32 bits 2 IQN IQN_IQdiv16 1-30 1 32 bits 2 IQN IQN_IQdiv32 1-30 1 32 bits 2 IQN IQN_IQdiv64 1-30 1 32 bits 2 IQN IQN_IQmpy2 1-30 1 32 bits 2 IQN IQN_IQmpy4 1-30 1 32 bits 2 IQN IQN_IQmpy8 1-30 1 32 bits 2 IQN IQN_IQmpy16 1-30 1 32 bits 2 IQN IQN_IQmpy32 1-30 1 32 bits 2 IQN IQN_IQmpy64 1-30 1 32 bits 2 IQN IQN_IQNdiv 1-30 59 32 bits 144 IQN/IQN IQN

_IQNmpy 1-30 13 32 bits 16 IQN*IQN IQN_IQNmpyI32 1-30 1 32 bits 2 IQN*long IQN

_IQNmpyI32frac 1-30 14 32 bits 20 IQN*long IQN_IQNmpyI32int 1-30 17 32 bits 20 IQN*long long_IQNmpyIQX 1-30 20 32 bits 52 IQN*IQN IQN

_IQNrmpy 1-30 13 32 bits 12 IQN*IQN IQN_IQNrsmpy 1-30 17 32 bits 36 IQN*IQN IQN






4.2 API Functions

4.2.1 _IQdiv2

Divides an IQ number by two.

Prototype:_iqN_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.

4.2.2 _IQdiv4

Divides an IQ number by four.



Description:This function divides an IQ number by four. This will work for any IQ format.

Returns:Returns the number divided by four.

4.2.3 _IQdiv8

Divides an IQ number by eight.



Description:This function divides an IQ number by eight. This will work for any IQ format.

Returns:Returns the number divided by eight.



4.2.4 _IQdiv16

Divides an IQ number by sixteen.



Description:This function divides an IQ number by sixteen. This will work for any IQ format.

Returns:Returns the number divided by sixteen.

4.2.5 _IQdiv32

Divides an IQ number by thirty two.



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.

4.2.6 _IQdiv64

Divides an IQ number by sixty four.



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.



4.2.7 _IQmpy2

Multiplies an IQ number by two.

Prototype:_iqN_IQmpy2(_iqN 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.

4.2.8 _IQmpy4

Multiplies an IQ number by four.



Description:This function multiplies an IQ number by four. This will work for any IQ format.

Returns:Returns the number multiplied by four.

4.2.9 _IQmpy8

Multiplies an IQ number by eight.



Description:This function multiplies an IQ number by eight. This will work for any IQ format.

Returns:Returns the number multiplied by eight.



4.2.10 _IQmpy16

Multiplies an IQ number by sixteen.



Description:This function multiplies an IQ number by sixteen. This will work for any IQ format.

Returns:Returns the number multiplied by sixteen.

4.2.11 _IQmpy32

Multiplies an IQ number by thirty two.



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.

4.2.12 _IQmpy64

Multiplies an IQ number by sixty four.



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.



4.2.13 _IQNdiv

Divides two IQ numbers.

Prototype:_iqN_IQNdiv(_iqN A,

_iqN B)


- or -

_iq_IQdiv(_iq A,

_iq B)


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 positivesaturation (regardless of the sign of A).

Returns:Returns the quotient in IQ format.

4.2.14 _IQNmpy

Multiplies two IQ numbers.

Prototype:_iqN_IQNmpy(_iqN A,

_iqN B)


- or -

_iq_IQmpy(_iq A,

_iq B)


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 neitherrounded nor saturated, so if the product is greater than the minimum or maximum values forthe given IQ format, the return value wraps around and produces inaccurate results.

Returns:Returns the product in IQ format.

4.2.15 _IQNmpyI32

Multiplies an IQ number by an integer.

Prototype:_iqN_IQNmpyI32(_iqN A,

long B)


- or -

_iq_IQmpyI32(_iq A,

long B)


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. Theresult is not saturated, so if the product is greater than the minimum or maximum values for thegiven IQ format, the return value wraps around and produces inaccurate results.


4.2.16 _IQNmpyI32frac

Multiplies an IQ number by an integer, returning the fractional portion of the product.

Prototype:_iqN_IQNmpyI32frac(_iqN A,

long B)


- or -

_iq_IQmpyI32frac(_iq A,

long B)





Description:This function multiplies an IQ number by an integer, returning the fractional portion of theproduct in IQ format.

Returns:Returns the fractional portion of the product in IQ format.

4.2.17 _IQNmpyI32int

Multiplies an IQ number by an integer, returning the integer portion of the result.

Prototype:long_IQNmpyI32int(_iqN A,

long B)


- or -

long_IQmpyI32int(_iq A,

long B)



Description:This function multiplies 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 ormaximum values for an integer, the result will be saturated to the minimum or maximum value.


4.2.18 _IQNmpyIQX

Multiplies two IQ numbers.

Prototype:_iqN_IQNmpyIQX(_iqN A,

long IQA,



_iqN B,long IQB)


- or -

_iq_IQmpyIQX(_iq A,

long IQA,_iq B,long IQB,)


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 thirdIQ format. The result is neither rounded nor saturated, so if the product is greater than theminimum or maximum values for the given output IQ format, the return value will wrap aroundand produce inaccurate results.


4.2.19 _IQNrmpy

Multiplies two IQ numbers, with rounding.

Prototype:_iqN_IQNrmpy(_iqN A,

_iqN B)


- or -

_iq_IQrmpy(_iq A,

_iq B)



Description:This function multiplies two IQ numbers, returning the product in IQ format. The result isrounded but not saturated, so if the product is greater than the minimum or maximum valuesfor the given IQ format, the return value wraps around and produces inaccurate results.




4.2.20 _IQNrsmpy

Multiplies two IQ numbers, with rounding and saturation.

Prototype:_iqN_IQNrsmpy(_iqN A,

_iqN B)


- or -

_iq_IQrsmpy(_iq A,

_iq B)



Description:This function multiplies two IQ numbers, returning the product in IQ format. The result isrounded and saturated, so if the product is greater than the minimum or maximum values forthe given IQ format, the return value is saturated to the minimum or maximum value for thegiven IQ format (as appropriate).



Trigonometric Functions

5 Trigonometric FunctionsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

5.1 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 radians outputfor the inverse functions), as well as a cycles per unit format where the range [0, 1) is mapped ontothe circle (in other words, 0.0 is 0 radians, 0.25 is π/2 radians, 0.5 is π radians, 0.75 is 3π/2 radians,and 1.0 is 2π radians). The following table summarizes the trigonometric functions.

FunctionName

IQFormat

ExecutionCycles

Accuracy(bits)


InputFormat

OutputFormat

_IQNacos 1-29 58 28 bits 148 IQN IQN_IQNasin 1-29 54 28 bits 140 IQN IQN_IQNatan 1-29 109 30 bits 218 IQN IQN_IQNatan2 1-29 107 30 bits 216 IQN,IQN IQN

_IQNatan2PU 1-30 99 31 bits 208 IQN,IQN IQN_IQNcos 1-29 56 30 bits 184 IQN IQN

_IQNcosPU 1-30 50 30 bits 128 IQN IQN_IQNsin 1-29 56 30 bits 180 IQN IQN

_IQNsinPU 1-30 50 30 bits 124 IQN IQN




5.2 API Functions

5.2.1 _IQNacos

Computes the inverse cosine of the input value.

Prototype:_iqN_IQNacos(_iqN A)




- or -

_iq_IQacos(_iq A)


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 IQ30 format because the full output range (-π through π) cannotbe represented in IQ30 format (which ranges from -2 through 2).

Returns:The inverse cosine of the input value, in radians.

5.2.2 _IQNasin

Computes the inverse sine of the input value.

Prototype:_iqN_IQNasin(_iqN A)


- or -

_iq_IQasin(_iq A)



Description:This function computes the inverse sine of the input value.


Returns:The inverse sine of the input value, in radians.

5.2.3 _IQNatan

Computes the inverse tangent of the input value.



Prototype:_iqN_IQNatan(_iqN A)


- or -

_iq_IQatan(_iq A)



Description:This function computes the inverse tangent of the input value.


Returns:The inverse tangent of the input value, in radians.

5.2.4 _IQNatan2

Computes the inverse four-quadrant tangent of the input point.

Prototype:_iqN_IQNatan2(_iqN A,

_iqN B)


- or -

_iq_IQatan2(_iq A,

_iq B)


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.


Returns:The inverse four-quadrant tangent of the input point, in radians.



5.2.5 _IQNatan2PU

Computes the inverse four-quadrant tangent of the input point, returning the result in cycles perunit.

Prototype:_iqN_IQNatan2PU(_iqN A,

_iqN B)


- or -

_iq_IQatan2PU(_iq A,

_iq B)


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 resultin 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:_iqN_IQNcos(_iqN A)


- or -

_iq_IQcos(_iq A)


Parameters:A is the input value in radians, in IQ format.

Description:This function computes the cosine of the input value.

Note:This function is not available for IQ30 format because the full input range (-π through π) cannotbe represented in IQ30 format (which ranges from -2 through 2).



Returns:The cosine of the input value.

5.2.7 _IQNcosPU

Computes the cosine of the input value in cycles per unit.

Prototype:_iqN_IQNcosPU(_iqN A)


- or -

_iq_IQcosPU(_iq A)


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:_iqN_IQNsin(_iqN A)


- or -

_iq_IQsin(_iq A)


Parameters:A is the input value in radians, in IQ format.

Description:This function computes the sine of the input value.

Note:This function is not available for IQ30 format because the full input range (-π through π) cannotbe represented in IQ30 format (which ranges from -2 through 2).



Returns:The sine of the input value.

5.2.9 _IQNsinPU

Computes the sine of the input value in cycles per unit.

Prototype:_iqN_IQNsinPU(_iqN A)


- or -

_iq_IQsinPU(_iq A)


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.


Mathematical Functions

6 Mathematical FunctionsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33

6.1 Introduction

The mathematical functions compute a variety of advanced mathematical functions for IQ numbers.The following table summarizes the mathematical functions:

FunctionName

IQFormat

ExecutionCycles

Accuracy(bits)


InputFormat

OutputFormat

_IQNexp 1-30 96 30 bits 184 IQN IQN_IQNexp2 1-30 72 30 bits 128 IQN IQN_IQNisqrt 1-30 62 30 bits 116 IQN IQN_IQNmag 1-30 83 30 bits 136 IQN,IQN IQN_IQNsqrt 1-30 63 31 bits 108 IQN IQN




6.2 API Functions

6.2.1 _IQNexp

Computes the base-e exponential value of an IQ number.

Prototype:_iqN_IQNexp(_iqN A)


- or -

_iq_IQexp(_iq A)


Parameters:A is the input value, in IQ format.



Description:This function computes the base-e exponential value of the input, and saturates the result if itexceeds the range of the IQ format in use.

Returns:Returns the base-e exponential of the input.

6.2.2 _IQNexp2

Computes the base-2 exponential value of an IQ number.

Prototype:_iqN_IQNexp2(_iqN A)


- or -

_iq_IQexp2(_iq A)



Description:This function computes the base-2 exponential value of the input, and saturates the result if itexceeds the range of the IQ format in use.

Returns:Returns the base-2 exponential of the input.

6.2.3 _IQNisqrt

Computes the inverse square root of an IQ number.

Prototype:_iqN_IQNisqrt(_iqN A)


- or -

_iq_IQisqrt(_iq A)





Description:This function computes the inverse square root (1 / sqrt) of the input, and saturates the resultif 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 _IQNmag

Computes the magnitude of a two dimensional vector.

Prototype:_iqN_IQNmag(_iqN A,

_iqN B)


- or -

_iq_IQmag(_iq A,

_iq B)


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. Theresult is always positive and saturated if it exceeds the range of the IQ format in use.

This is functionally equivalent to _IQNsqrt(_IQNrmpy(A, A) + _IQNrmpy(B, B)), but providesbetter accuracy, speed, and intermediate overflow handling than building this computation from_IQNsqrt() and _IQNrmpy(). For example, _IQ16mag(_IQ16(30000), _IQ16(1000)) correctlyreturns _IQ16(30016.6...), even though the intermediate value of _IQ16rmpy(_IQ16(30000),_IQ16(30000)) overflows an _iq16.

Returns:Returns the inverse square root of the input.

6.2.5 _IQNsqrt

Computes the square root of an IQ number.

Prototype:_iqN_IQNsqrt(_iqN A)


- or -



_iq_IQsqrt(_iq A)



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.


Miscellaneous Functions

7 Miscellaneous FunctionsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37

7.1 Introduction

The miscellaneous functions are useful functions that do not otherwise fit elsewhere. The followingtable summarizes the miscellaneous functions:

FunctionName

IQFormat

ExecutionCycles

Accuracy(bits)


InputFormat

OutputFormat

_IQNabs 1-30 3 32 bits 6 IQN IQN_IQNsat 1-30 6 32 bits 14 IQN IQN




7.2 API Functions

7.2.1 _IQNabs

Finds the absolute value of an IQ number.

Prototype:_iqN_IQNabs(_iqN A)


- or -

_iq_IQabs(_iq A)



Description:This function computes the absolute value of the input IQ number.


Miscellaneous Functions

Returns:Returns the absolute value of the input.

7.2.2 _IQNsat

Satures an IQ number.

Prototype:_iqN_IQNsat(_iqN A,

_iqN Pos,_iqN Neg)


- or -

_iq_IQsat(_iq A,

_iq Pos,_iq Neg)


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.



IMPORTANT NOTICETexas Instruments Incorporated and its subsidiaries (TI) 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 shouldobtain the latest relevant information before placing orders and should verify that such information is current and complete. All products aresold subject to TI’s terms and conditions of sale supplied at the time of order acknowledgment.

TI warrants performance of its hardware products to the specifications applicable at the time of sale in accordance with TI’s standardwarranty. Testing and other quality control techniques are used to the extent TI deems necessary to support this warranty. Except wheremandated by government requirements, testing of all parameters of each product is not necessarily performed.

TI assumes no liability for applications assistance or customer product design. Customers are responsible for their products and applicationsusing TI components. To minimize the risks associated with customer products and applications, customers should provide adequate designand operating safeguards.

TI does not warrant or represent that any license, either express or implied, is granted under any TI patent right, copyright, mask workright, 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 servicesor a warranty or endorsement thereof. Use of such information may require a license from a third party under the patents or other intellectualproperty of the third party, or a license from TI under the patents or other intellectual property of TI.

Reproduction of TI information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompaniedby all associated warranties, conditions, limitations, and notices. Reproduction of this information with alteration is an unfair and deceptivebusiness practice. TI is not responsible or liable for such altered documentation. Information of third parties may be subject to additionalrestrictions.

Resale of TI products or services with statements different from or beyond the parameters stated by TI for that product or service voidsall express and any implied warranties for the associated TI product or service and is an unfair and deceptive business practice. TI is notresponsible 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 reasonablybe expected to cause severe personal injury or death, unless officers of the parties have executed an agreement specifically governingsuch use. Buyers represent that they have all necessary expertise in the safety and regulatory ramifications of their applications, andacknowledge and agree that they are solely responsible for all legal, regulatory and safety-related requirements concerning their productsand any use of TI products in such safety-critical applications, notwithstanding any applications-related information or support that may beprovided by TI. Further, Buyers must fully indemnify TI and its representatives against any damages arising out of the use of TI products insuch 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 connection with such use.

TI products are neither designed nor intended for use in automotive applications or environments unless the specific TI products aredesignated by TI as compliant with ISO/TS 16949 requirements. Buyers acknowledge and agree that, if they use any non-designatedproducts 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:

ProductsAmplifiersData ConvertersDLP® ProductsDSPClocks and TimersInterfaceLogicPower MgmtMicrocontrollersRFIDRF/IF and ZigBee® Solutions

amplifier.ti.comdataconverter.ti.comwww.dlp.comdsp.ti.comwww.ti.com/clocksinterface.ti.comlogic.ti.compower.ti.commicrocontroller.ti.comwww.ti-rfid.comwww.ti.com/lprf

ApplicationsAudioAutomotiveBroadbandDigital ControlMedicalMilitaryOptical NetworkingSecurityTelephonyVideo & ImagingWireless

www.ti.com/audiowww.ti.com/automotivewww.ti.com/broadbandwww.ti.com/digitalcontrolwww.ti.com/medicalwww.ti.com/militarywww.ti.com/opticalnetworkwww.ti.com/securitywww.ti.com/telephonywww.ti.com/videowww.ti.com/wireless

Mailing Address: Texas Instruments, Post Office Box 655303, Dallas, Texas 75265Copyright © 2010, Texas Instruments Incorporated


amplifier.ti.com

dataconverter.ti.com

www.dlp.com

dsp.ti.com

www.ti.com/clocks

interface.ti.com

logic.ti.com

power.ti.com

microcontroller.ti.com

www.ti-rfid.com

www.ti.com/lprf

www.ti.com/audio

www.ti.com/automotive

www.ti.com/broadband

www.ti.com/digitalcontrol

www.ti.com/medical

www.ti.com/military

www.ti.com/opticalnetwork

www.ti.com/security

www.ti.com/telephony

www.ti.com/video

www.ti.com/wireless

Documents

Stellaris IQmath Library User's Guide - amoBBSd1.amobbs.com/bbs_upload782111/files_33/ourdev_582876DTQPBQ.pdfIntroduction 1 Introduction The Texas Instruments® Stellaris® IQmath