# MSPM0 IQMath User’s Guide¶

## 1. Introduction¶

The Texas Instruments® MSP IQmath Library is a collection of highly optimized and high-precision mathematical functions for C programmers to seamlessly port a floating-point algorithm into fixed-point code on MSPM0 devices. These routines are typically used in computationally intensive real-time applications where optimal execution speed, high accuracy and ultra-low energy are critical. By using the IQmath library, it is possible to achieve execution speeds considerably faster and energy consumption considerably lower than equivalent code written using floating-point math.

The IQmath library provides functions for use with 32-bit data types and high accuracy.

## 2. Using the IQmath Library¶

### 2.1. IQmath Data Types¶

The IQmath library uses a 32-bit fixed-point signed number (an “int32_t” in C99) as its basic data type. The IQ format of this fixed-point number can range from IQ1 to IQ30, where the IQ format number indicates the number of fractional bits. The IQ format value is stored as an integer with an implied scale based on the IQ format and the number of fractional bits. The equation below shows how a IQ format decimal number xiq is stored using an integer value xi with an implied scale, where n represents the number of fractional bits.

$IQn(x_{iq}) = x_{i} ∗ 2^{-n}$

For example the IQ24 value of 3.625 is stored as an integer value of 60817408, shown in the equation below.

$60817408 ∗ 2^{−24} = IQ24(3.625)$

C typedefs are provided for the various IQ formats, and these IQmath data types should be used in preference to the underlying “int32_t” data type to make it clear which variables are in IQ format.

The following table provides the characteristics of the various IQ formats (the C data 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):

Type

Integer Bits

Fractional Bits

Min Range

Max Range

Resolution

_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

_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 additional type that corresponds to the GLOBAL_IQ format. This is _iq, and it matches one of the above IQ formats (based on the setting of GLOBAL_IQ). The GLOBAL_IQ format has no impact when using the specific _iqN types and function such as _iq24.

### 2.2. Using the IQMath Library¶

Two versions of the IQmath library are provided:

• RTS: C implementation using compiler Runtime System (RTS) libraries

• MathACL: leverages the MSPM0 hardware math accelerator (MathACL) ​

MSPM0 Family

RTS

MathACL

MSPM0G

Supported

Supported

MSPM0L

Supported

Not supported

The libraries are provided in easy to use archive files, named iqmath.a. The archive files should be used with projects in place of any .lib files.

To find the provided libraries, simply navigate to the device directory under source/ti/iqmath/lib where you will find the different versions of iqmath.a.

In order to use IQmath, user also need to make sure they have the right path to the IQMath include folder which is #include <ti/iqmath/include/IQmathLib.h>.

Review the corresponding IDE documentation for details on how to add files, libraries and paths to a project.

### 2.3. Calling Functions From C¶

In order to call an IQmath function from C, the C header file must be included. Then, _iq and _iqN data types, along with the IQmath functions can be used by the application.

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

#include <ti/iqmath/include/IQmathLib.h>

int main(void)
{
_iq12 X, Y, Z;
X = _IQ12(1.0);
Y = _IQ12(7.0);
Z = _IQ12div(X, Y);
}


### 2.4. Selecting the Global IQ Format¶

Numerical precision and dynamic range requirements vary considerably from one application to another. The libraries provide a GLOBAL_IQ format (using the _iq data type) that an application can use to perform its computations in a generic format which can be changed at compile time. An application written using the GLOBAL_IQ format can be changed from one format to another by simply changing the GLOBAL_IQ value and recompiling, allowing the precision and performance effects of different formats to be easily measured and evaluated.

The setting of GLOBAL_IQ does not have any influence in the _iqN format and corresponding functions. These types will always have the same fixed accuracy regardless of the GLOBAL_IQ format.

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

In the source file, the format can be selected prior to including the header file. The following example selects a GLOBAL_IQ format of IQ8:

//
// Set GLOBAL_IQ to 8 prior to including IQmathLib.h.
//
#define GLOBAL_IQ 8
#include <ti/iqmath/include/IQmathLib.h>


In the project file, add a predefined value for GLOBAL_IQ. 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 format values, while the second method changes the global format value for the entire application. The method that is most appropriate varies from application to application.

Note: Some functions are not available when GLOBAL_IQ is 30. Please see the API Guide section for a list of functions and the available IQ formats.

### 2.5. Example Projects¶

The IQmathLib provides two example projects for for RTS and MathACL to provide a starting point for users and demonstrate the use of IQmath functions, while the SDK includes several projects which leverage IQmath for more advanced applications. The included examples are:

• IQmathLib MathACL operations test example

• IQmathLib RTS operations test example

The IQmathLib projects provide a starting point for building a fixed point application. These projects will already have the libraries added and the include path set to include the header files.

The examples demonstrate how to use several of the IQmathLib functions and data types to perform math calculations, with the only difference being the use of MathACL.

## 3. API Guide¶

A complete API guide is included showing detailed information about all files, APIs, and corresponding parameters. IQmath includes five types of routines:

• Format conversion functions: methods to convert numbers to and from the various formats.

• Arithmetic functions: methods to perform basic arithmetic (addition, subtraction, multiplication, division).

• Trigonometric functions: methods to perform trigonometric functions (sin, cos, atan, and so on).

• Mathematical functions: methods to perform advanced arithmetic (square root, ex , and so on).

• Miscellaneous: miscellaneous methods (saturation and absolute value). In the chapters that follow, the methods in each of these groups are covered in detail.

The detailed guide can be found here:

## 4. Benchmarks¶

This section includes benchmarks for the IQmath libraries, measured in average cycles per function. These benchmarks were run on the device launchpads using IAR Embedded Workbench for ARM 9.20.11.43606. The tests for each function were run with a set of different values ran for 1000 iterations each, resulting in the presented average.

MSPM0G benchmarks were tested on early experimental silicon.

Function Name

(MSPM0G) MathACL IQmath

(MSPM0G) RTS IQmath

(MSPM0G) Float

(MSPM0L) RTS IQmath

(MSPM0L) Float

sin

98

291

1260

292

1223

cos

99

289

1262

291

1227

frac

21

21

N/A

24

N/A

asin

310

521

1889

522

2056

acos

311

523

1889

525

2058

atan

264

670

1404

671

1540

atan2

279

675

1379

675

1537

sqrt

105

564

238

566

254

exp

638

645

1663

646

1694

log

892

898

1479

905

1513

add

9

9

73

11

71

sub

9

9

70

9

69

mpy

34

63

76

65

74

div

52

442

228

443

294