1.4.3 LibQ Fixed-Point Math Library

This topic describes the LibQ Fixed-Point Math Library.

The LibQ Fixed-Point Math Library is available for the PIC32MZ family of microcontrollers. This library was created from optimized assembly routines written specifically for devices with microAptiv™ core features.

The LibQ Fixed-Point Math Library simplifies writing fixed point algorithms, supporting Q15, Q31 and other 16-bit and 32-bit data formats. Using the simple, C callable functions contained in the library, fast fixed point mathematical operations can be easily executed. Fixed-point mathematical calculations may replace some functions implemented in the floating point library (math.h), depending on performance and resolution requirements.

Functions included in the LibQ library include capabilities for trigonometric, power and logarithms, and data conversion. In many cases the functions are identical other than the precision of their operands and the corresponding value that they return.

These functions are implemented in efficient assembly, and generally tuned to optimize performance over code size. In some cases the library breaks out functions that enable one to be optimized for accuracy, while another version is optimized for speed.

These functions such as _LIBQ_Q2_29_acos_Q31 and _LIBQ_Q2_29_acos_Q31_Fast are otherwise identical and can be used interchangeably. Each of these functions are typically used in computationally intensive real-time applications where execution time is a critical parameter.

Using the Library

This topic describes the basic architecture of the LibQ Fixed-Point Math Library and provides information and examples on its use.

Interface Header File: libq.h

The interface to the LibQ Fixed-Point Math Library is defined in the libq.h header file. Any C language source (.c) file that uses the LibQ Fixed-Point Library should include libq.h.

Library File:

The LibQ Fixed-Point Math Library archive (.a) file is installed with MPLAB Harmony.

Configuring the Library using MHC

Select the Audio/Math/Math Libraries component to load the libq_c, libq/dsp libraries, as shown below.

The project configuration should now contain the Math Libraries block.

Either the Speed Optimized (as shown above) or the Space Optimized versions of the library can be selected (only 1) to be generated to the project.

The LibQ Fixed-Point Math Library contains functions for manipulating Q15, Q31 and other intermediate integer representations of real numbers. The Library Interface section details the operation of the data formats and explains each function in detail.

The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the DSP Fixed-Point Math Library.

Divide Functions

_Q16 fixed point divide function.

Square Root Functions

Square root of a positive _Q16 fixed point value function.

Log Functions

Log calculation functions.

Power Functions

Power calculation functions.

Exponential Functions

Exponential calculation functions.

Sine Functions

Sine calculation functions.

Cosine Functions

Cosine calculation functions.

Target Functions

Target calculation functions.

Arcsin Functions

Arcsin calculation functions.

Arccos Functions

Arccos calculation functions.

Arctan2 Functions

Arctan2 calculation functions.

Random Number Functions

_Q15 and _Q31 pseudo-random value functions.

Float Functions

Float conversion functions.

String Functions

ASCII to _Q15 conversions.

Signed fixed-point types are defined as follows:

Qn_m, where:

• n is the number of data bits to the left of the radix point

• m is the number of data bits to the right of the radix point

• a signed bit is implied

For convenience, short names are also defined:

Qn_m numerical values are used by the library processing data as integers. In this format the n represents the number of integer bits, and the m represents the number of fractional bits. All values assume a sign bit in the most significant bit. The range of the numerical value therefore is:

-2^(n-1) to ; with a resolution of 2(^-m).

A _Q16 format number (_Q15_16) would range from -32768.0 (0x8000 0000) to 32767.99998474 with a precision of 0.000015259 (or 2^-16). For example, a numerical representation of the number 3.14159 in _Q2_13 notation would be:

3.14159 * 2¹³ = 25735.9 => 0x6488

And converting from the _Q7_8 format with the value 0x1D89 would be:

0x1D89 / 2⁸ = 7561 / 256 => 29.5316, accurate to 0.00391

Functions in the library are prefixed with the type of the return value. For example, _LIBQ_Q16Sqrt returns a _Q16 value equal to the square root of its argument. Argument types do not always match the return type. Refer to the function prototype for a specification of its arguments.

In cases where the return value is not a fixed-point type, the argument type is appended to the function name. For example, _LIBQ_ToFloatQ31 accepts a type _Q31 argument.

In some cases, both the return type and the argument type are specified within the function name. For example:

Functions