## Using the IQmath Library

### About the IQmath Library

#### Introduction

The C28x IQmath Library blocks perform processor-optimized fixed-point
mathematical operations. These blocks correspond to functions in the Texas Instruments^{®} C28x IQmath Library, an assembly-code library for the TI C28x family of
digital signal processors.

**Note**

Implementation of this library for the TI C28x processor produces the same simulation and code-generation output as the TI version of this library, but it does not use a global Q value, as does the TI version. The Q format is dynamically adjusted based on the Q format of the input data.

The IQmath Library blocks generally input and output fixed-point data types and use numbers in Q format. The C28x IQmath Library block reference pages discuss the data types accepted and produced by each block in the library. For more information, consult the Fixed-Point Numbers and Q Format Notation topics, as well as the Fixed-Point Designer™ product documentation, which includes more information on fixed-point data types, scaling, and precision issues.

You can use IQmath Library blocks with some core Simulink^{®} blocks and Fixed-Point Designer blocks to run simulations in Simulink models before generating code. Once you develop your model, you can generate
equivalent code that is optimized to run on a TI C28x™ DSP. During code generation, a call is made to the IQmath Library for each
IQmath Library block in your model to create target-optimized code. To learn more about
creating models that include IQmath Library blocks and blocks from other blocksets,
consult Building Models.

#### Common Characteristics

The following characteristics are common to IQmath Library blocks:

Sample times are inherited from driving blocks.

Blocks are single rate.

Parameters are not tunable.

Blocks support discrete sample times.

To learn more about characteristics particular to each block in the library, see the individual block reference pages.

#### References

For detailed information on the IQmath library, see the user guide for the
*C28x IQmath Library - A Virtual Floating Point Engine*, Literature
Number SPRC087, available at the Texas Instruments website. The user guide is included in the zip file download that also
contains the IQmath library (registration required).

### Fixed-Point Numbers

#### Notation

In digital hardware, numbers are stored in binary words. A binary word is a fixed-length sequence of binary digits (1s and 0s). How hardware components or software functions interpret this sequence of 1s and 0s is defined by the data type.

Binary numbers are used to represent either fixed-point or floating-point data types. A fixed-point data type is characterized by the word size in bits, the binary point, and whether it is signed or unsigned. The position of the binary point is the means by which fixed-point values are scaled and interpreted.

For example, a binary representation of a fractional fixed-point number (either signed or unsigned) is shown below:

where

*b*_{i}is the*i*th binary digit.*ws*is the word size in bits.*b*_{ws–1}is the location of the most significant (highest) bit (MSB).b

_{0}is the location of the least significant (lowest) bit (LSB).The binary point is shown four places to the left of the LSB. In this example, therefore, the number is said to have four fractional bits, or a fraction length of 4.

**Note**For Embedded Coder

^{®}, the results of fixed-point and integer operations in MATLAB^{®}/Simulink match the results on the hardware target down to the least significant bit (bit-trueness). The results of floating-point operations in MATLAB/Simulink do not match those on the hardware target, because the libraries used by the third-party compiler may be different from those used by MATLAB/Simulink.

#### Signed Fixed-Point Numbers

Signed binary fixed-point numbers are typically represented in one of three ways:

Sign/magnitude

One's complement

Two's complement

Two's complement is the most common representation of signed fixed-point numbers and is used by TI digital signal processors.

Negation using signed two's complement representation consists of a bit inversion (translation to one's complement representation) followed by the binary addition of a 1. For example, the two's complement of 000101 is 111011, as follows:

000101 ->111010 (bit inversion) ->111011 (binary addition of a 1 to the LSB)

#### Q Format Notation

The position of the binary point in a fixed-point number determines how you interpret
the scaling of the number. When it performs basic arithmetic such as addition or
subtraction, hardware uses the same logic circuits regardless of the value of the scale
factor. In essence, the logic circuits do not have knowledge of a binary point. They
perform signed or unsigned integer arithmetic — as if the binary point is to the
right of *b*_{0}. Therefore, you determine the
binary point.

In the IQmath Library, the position of the binary point in the signed, fixed-point data types is expressed in and designated by Q format notation. This fixed-point notation takes the form

*Qm.n *

where

*Q*designates that the number is in Q format notation — the Texas Instruments representation for signed fixed-point numbers.*m*is the number of bits used to designate the two's complement integer portion of the number.*n*is the number of bits used to designate the two's complement fractional portion of the number, or the number of bits to the right of the binary point.

In Q format, the most significant bit is designated as the sign bit. Representing a signed fixed-point data type in Q format requires m+n+1 bits to account for the sign.

**Note**

The range and resolution varies for different Q formats. For specific details, see
Section 3.2 in the *Texas Instruments C28x Foundation Software, IQmath Library
Module User's Guide. *

When converting from Q format to floating-point format, the accuracy of the conversion depends on the values and formats of the numbers. For example, for single-precision floating-point numbers that use 24 bits, the resolution of the corresponding 32-bit number cannot be achieved. The 24-bit number approximates its value by truncating the lower end. For example:

32-bit integer 11110000 11001100 10101010 00001111 |

Single-precision float +1.1110000 11001100 10101010 x 231 |

Corresponding value 11110000 11001100 10101010 00000000 |

**Expressing Q Format — Q.15. **For example, a signed 16-bit number with n = 15 bits to the right of the binary
point is expressed as

Q0.15

Q.15

In Fixed-Point Designer software, this data type is expressed as

sfrac16

sfix16_En15

In DSP System Toolbox™ software, this data type is expressed as

[16 15]

**Expressing Q Format — Q1.30. **Multiplying two Q0.15 numbers yields a product that is a signed 32-bit data type
with n = 30 bits to the right of the binary point. One bit is the designated sign bit,
thereby forcing m to be 1:

m+n+1 = 1+30+1 = 32 bits total

Therefore, this number is expressed as

Q1.30

In Fixed-Point Designer software, this data type is expressed as

sfix32_En30

In DSP System Toolbox software, this data type is expressed as

[32 30]

**Expressing Q Format — Q-2.17. **Consider a signed 16-bit number with a scaling of 2^{(-17)}.
This requires n = 17 bits to the right of the binary point, meaning that the most
significant bit is a *sign-extended* bit.

*Sign extension* fills additional bits with the value of the MSB.
For example, consider a 4-bit two's complement number 1011. When this number is extended
to 7 bits with sign extension, the number becomes 1111101 and the value of the number
remains the same.

One bit is the designated sign bit, forcing m to be -2:

m+n+1 = -2+17+1 = 16 bits total

Therefore, this number is expressed as

Q-2.17

In Fixed-Point Designer software, this data type is expressed as

sfix16_En17

In DSP System Toolbox software, this data type is expressed as

[16 17]

**Expressing Q Format — Q17.-2. **Consider a signed 16-bit number with a scaling of 2^(2) or 4. This means that the
binary point is implied to be 2 bits to the right of the 16 bits, or that there are n =
-2 bits to the right of the binary point. One bit must be the sign bit, thereby forcing
m to be 17:

m+n+1 = 17+(-2)+1 = 16

Therefore, this number is expressed as

Q17.-2

In Fixed-Point Designer software, this data type is expressed as

sfix16_E2

In DSP System Toolbox software, this data type is expressed as

[16 -2]

### Building Models

#### Overview

You can use IQmath Library blocks in models along with certain core Simulink, Fixed-Point Designer, and other blockset blocks. This section discusses issues you should consider when building a model with blocks from these different libraries.

#### Converting Data Types

It is vital to make sure that blocks you connect in a model have compatible input and output data types. In most cases, IQmath Library blocks handle only a limited number of specific data types. You can refer to the block reference page for a discussion of the data types that the block accepts and produces.

When you connect IQmath Library blocks and Fixed-Point Designer blocks, you often need to set the data type and scaling in the block parameters of the Fixed-Point Designer block to match the data type of the IQmath Library block. Many Fixed-Point Designer blocks allow you to set their data type and scaling through inheritance from the driving block, or through backpropagation from the next block. This can be a good way to set the data type of a Fixed-Point Designer block to match a connected IQmath Library block.

Some DSP System Toolbox blocks and core Simulink blocks also accept fixed-point data types. Choose the right settings in these blocks' parameters when you connect them to an IQmath Library block.

#### Using Sources and Sinks

The IQmath Library does not include source or sink blocks. Use source or sink blocks from the core Simulink library or Fixed-Point Designer in your models with IQmath Library blocks.

#### Choosing Blocks to Optimize Code

In some cases, blocks that perform similar functions appear in more than one blockset. For example, the IQmath Library and Fixed-Point Designer software have a Multiply block. When you are building a model to run on C2000™ DSP, choosing the block from the IQmath Library yields better optimized code. You can use a similar block from another library if it gives you functionality that the IQmath Library block does not support, but you will generate code that is less optimized.

#### Double and Single-Precision Parameter Values

When you enter double-precision floating-point values for parameters in the IQ Math
blocks, the software converts them to single-precision values that are compatible with the
behavior on C28x processor. For example, with the **Ramp Generator** block,
the software converts the value of the **Maximum step angle **parameter
to a single-precision value.