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:

• IQMath API Guide

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