1.4.2 DSP Fixed-Point Math Libraries
Introduction
This topic describes the DSP Fixed-Point Math Libraries.
Description
The DSP Fixed-Point Library are available for the PIC32MZ family of microcontrollers. This library was created from optimized assembly routines written specifically for devices with microAptiv™ core features that utilize DSP ASE.
The LIBQ library is required to use the DSP library.
The DSP Fixed-Point Library contains building block functions for developing digital signal processing algorithms. The library supports the Q15 and Q31 fractional data formats. The functions are implemented in efficient assembly specifically targeted at the DSP extensions in this core family.
The library makes these functions available in a simple C-callable structure.
Functions included in the DSP Fixed-Point Library include complex math, vector math, matrix math, digital filters, and transforms.
In many cases, these functions require specific data structures to operate, which are detailed in the header file and examples.
Using the Library
This topic describes the basic architecture of the DSP Fixed-Point Library and provides information and examples on its use.
Interface Header File: dsp.h
The interface to the DSP Fixed-Point library is defined in the dsp.h header file. Any C language source (.c) file that uses the DSP.
Fixed-Point library must include dsp.h. This file is automatically included by definitions.h when the library is generated using MHC.
Some functions make special use of the optimized fixed-point math library libq.h. For use of those functions, the libq.h file must also be included in a project. The libq.h file is also installed with MPLAB Harmony. Specific notes within each function will describe if the function is dependent on the LibQ Fixed-Point Math Library.
Library Files:
The DSP Fixed-Point library archive (.a) files are installed with MPLAB Harmony. Although there are two PIC32 DSP files, the linker will only utilize one of these depending on your device usage.
This library is only available in prebuilt binary form, with prototypes for each function described in the dsp.h file. The available library versions are:
• dsp_mips32_mz_ef_nfO3.a
• dsp_mips32_mz_ef_nfOs.a
The naming convention for these libraries is as follows:
<name><arch><core><fpu><codes>.a
where, "name" is the name of the library (DSP); "arch" is the 32 MIPS architecture (MIPS32); "core" is the microAptive core with DSP ASE extensions (MZ); and "fpu" indicates that a Floating Point Unit(FPU) is available. The "codes" are as follows:
• <nf, fpu> - FPU disabled or enabled
• <O3,OS> - Fully optimized for speed or optimized for size.
Configuring the Library using MHC
Select the Audio/Math/Math Libraries component to load the libq_c, libq/dsp libraries.
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.
Note: LIBQ is also required to be selected.
Library Overview
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.
Complex Math Functions
General mathematical operations using a complex structure with the form (a + bi)
Vector Math Functions
Mathematical operations on a array of numbers or vector
Matrix Math Functions
Mathematical operations on a matrix
Digital Filter Functions
FIR and IIR filtering functions with various architectures
Transform Functions
FFT, Windows and related transform elements
Support Functions
Quick support functions for numerical transform.
The DSP Fixed-Point Library uses fixed-point fractional functions to optimize execution speed. These functions limit the accuracy of the calculations to the bits specified for the function. Due to parallelism in some operations, the 16-bit version of the functions are more efficient than their 32-bit counterparts. In many cases both 16-bit and 32-bit functions are available to give the user the choice of balance between speed and functional resolution.
A majority of the DSP Fixed-Point Library uses functions with variables in Q15 or Q31 format. Representations of these numbers are given in Data Types and Constants in the Library Interface section, and generally are int16_t (for Q15 fractional representation) and int32_t (for Q31 fractional representation). This limits the equivalent numerical range to roughly -1.0 to 0.999999999. It is possible to represent other number ranges, but scaling before and after the function call are necessary.
All library functions will saturate the output if the value exceeds the maximum or is lower than the minimum allowable value for that resolution.
Some prescaling may be necessary to prevent unwanted saturation in functions that may otherwise create calculation errors.
Library Interface
Functions
| Name | Description |
|---|---|
| DSP_ComplexAdd32 | Calculates the sum of two complex numbers. |
| DSP_ComplexConj16 | Calculates the complex conjugate of a complex number. |
| DSP_ComplexConj32 | Calculates the complex conjugate of a complex number. |
| DSP_ComplexDotProd32 | Calculates the dot product of two complex numbers. |
| DSP_ComplexMult32 | Multiplies two complex numbers. |
| DSP_ComplexScalarMult32 | Multiplies a complex number and a scalar number. |
| DSP_ComplexSub32 | Calculates the difference of two complex numbers. |
| DSP_FilterFIR32 | Performs a Finite Infinite Response (FIR) filter on a vector. |
| DSP_FilterFIRDecim32 | Performs a decimating FIR filter on the input array. |
| DSP_FilterFIRInterp32 | Performs an interpolating FIR filter on the input array. |
| DSP_FilterIIR16 | Performs a single-sample cascaded biquad Infinite Impulse Response (IIR) filter. |
| DSP_FilterIIRBQ16 | Performs a single-pass IIR Biquad Filter. |
| DSP_FilterIIRBQ16_cascade8 | Performs a single-sample IIR Biquad Filter as a cascade of 8 series filters. |
| DSP_FilterIIRBQ16_fast | Performs a single-pass IIR Biquad Filter. |
| DSP_FilterIIRBQ16_parallel8 | Performs a 8 parallel single-pass IIR Biquad Filters, and sums the result. |
| DSP_FilterIIRBQ16_parallel8_fast | Performs a 8 parallel single-pass IIR Biquad Filters, and sums the result. |
| DSP_FilterIIRBQ32 | Performs a high resolution single-pass IIR Biquad Filter. |
| DSP_FilterIIRSetup16 | Converts biquad structure to coeffs array to set up IIR filter. |
| DSP_FilterLMS16 | Performs a single sample Least Mean Squares FIR Filter. |
| DSP_MatrixAdd32 | Addition of two matrices C = (A + B). |
| DSP_MatrixEqual32 | Equality of two matrices C = (A). |
| DSP_MatrixInit32 | Initializes the first N elements of a Matrix to the value num. |
| DSP_MatrixMul32 | Multiplication of two matrices C = A x B. |
| DSP_MatrixScale32 | Scales each element of an input buffer (matrix) by a fixed number. |
| DSP_MatrixSub32 | Subtraction of two matrices C = (A - B). |
| DSP_MatrixTranspose32 | Transpose of a Matrix C = A (T). |
| DSP_TransformFFT16 | Creates an Fast Fourier Transform (FFT) from a time domain input. |
| DSP_TransformFFT16_setup | Creates FFT coefficients for use in the FFT16 function. |
| DSP_TransformFFT32 | Creates an Fast Fourier Transform (FFT) from a time domain input. |
| DSP_TransformFFT32_setup | Creates FFT coefficients for use in the FFT32 function. |
| DSP_TransformIFFT16 | Creates an Inverse Fast Fourier Transform (FFT) from a frequency domain input. |
| DSP_TransformWindow_Bart16 | Perform a Bartlett window on a vector. |
| DSP_TransformWindow_Bart32 | Perform a Bartlett window on a vector. |
| DSP_TransformWindow_Black16 | Perform a Blackman window on a vector. |
| DSP_TransformWindow_Black32 | Perform a Blackman window on a vector. |
| DSP_TransformWindow_Cosine16 | Perform a Cosine (Sine) window on a vector. |
| DSP_TransformWindow_Cosine32 | Perform a Cosine (Sine) window on a vector. |
| DSP_TransformWindow_Hamm16 | Perform a Hamming window on a vector. |
| DSP_TransformWindow_Hamm32 | Perform a Hamming window on a vector. |
| DSP_TransformWindow_Hann16 | Perform a Hanning window on a vector. |
| DSP_TransformWindow_Hann32 | Perform a Hanning window on a vector. |
| DSP_TransformWindow_Kaiser16 | Perform a Kaiser window on a vector. |
| DSP_TransformWindow_Kaiser32 | Perform a Kaiser window on a vector. |
| DSP_TransformWinInit_Bart16 | Create a Bartlett window. |
| DSP_TransformWinInit_Bart32 | Create a Bartlett window. |
| DSP_TransformWinInit_Black16 | Create a Blackman window. |
| DSP_TransformWinInit_Black32 | Create a Blackman window. |
| DSP_TransformWinInit_Cosine16 | Create a Cosine (Sine) window. |
| DSP_TransformWinInit_Cosine32 | Create a Cosine (Sine) window. |
| DSP_TransformWinInit_Hamm16 | Create a Hamming window. |
| DSP_TransformWinInit_Hamm32 | Create a Hamming window. |
| DSP_TransformWinInit_Hann16 | Create a Hanning window. |
| DSP_TransformWinInit_Hann32 | Create a Hanning window. |
| DSP_TransformWinInit_Kaiser16 | Create a Kaiser window. |
| DSP_TransformWinInit_Kaiser32 | Create a Kaiser window. |
| DSP_VectorAbs16 | Calculate the absolute value of a vector. |
| DSP_VectorAbs32 | Calculate the absolute value of a vector. |
| DSP_VectorAdd16 | Calculate the sum of two vectors. |
| DSP_VectorAdd32 | Calculate the sum of two vectors. |
| DSP_VectorAddc16 | Calculate the sum of a vector and a constant. |
| DSP_VectorAddc32 | Calculate the sum of a vector and a constant. |
| DSP_VectorAutocorr16 | Computes the Autocorrelation of a Vector. |
| DSP_VectorBexp16 | Computes the maximum binary exponent of a vector. |
| DSP_VectorBexp32 | Computes the maximum binary exponent of a vector. |
| DSP_VectorChkEqu32 | Compares two input vectors, returns an integer 1 if equal, and 0 if not equal. |
| DSP_VectorCopy | Copies the elements of one vector to another. |
| DSP_VectorCopyReverse32 | Reverses the order of elements in one vector and copies them into another. |
| DSP_VectorDivC | Divides the first N elements of inVector by a constant divisor, and stores the result in outVector. |
| DSP_VectorDotp16 | Computes the dot product of two vectors, and scales the output by a binary factor. |
| DSP_VectorDotp32 | Computes the dot product of two vectors, and scales the output by a binary factor. |
| DSP_VectorExp | Computes the EXP (e^x) of the first N elements of inVector, and stores the result in outVector. |
| DSP_VectorFill | Fills an input vector with scalar data. |
| DSP_VectorLn | Computes the Natural Log, Ln(x), of the first N elements of inVector, and stores the result in outVector. |
| DSP_VectorLog10 | Computes the Log10(x), of the first N elements of inVector, and stores the result in outVector. |
| DSP_VectorLog2 | Computes the Log2(x) of the first N elements of inVector, and stores the result in outVector. |
| DSP_VectorMax32 | Returns the maximum value of a vector. |
| DSP_VectorMaxIndex32 | Returns the index of the maximum value of a vector. |
| DSP_VectorMean32 | Calculates the mean average of an input vector. |
| DSP_VectorMin32 | Returns the minimum value of a vector. |
| DSP_VectorMinIndex32 | Returns the index of the minimum value of a vector. |
| DSP_VectorMul16 | Multiplication of a series of numbers in one vector to another vector. |
| DSP_VectorMul32 | Multiplication of a series of numbers in one vector to another vector. |
| DSP_VectorMulc16 | Multiplication of a series of numbers in one vector to a scalar value. |
| DSP_VectorMulc32 | Multiplication of a series of numbers in one vector to a scalar value. |
| DSP_VectorNegate | Inverses the sign (negates) the elements of a vector. |
| DSP_VectorRecip | Computes the reciprocal (1/x) of the first N elements of inVector, and stores the result in outVector. |
| DSP_VectorRMS16 | Computes the root mean square (RMS) value of a vector. |
| DSP_VectorShift | Shifts the data index of an input data vector. |
| DSP_VectorSqrt | Computes the square root of the first N elements of inVector, and stores the result in outVector. |
| DSP_VectorStdDev16 | Computes the Standard Deviation of a Vector. |
| DSP_VectorSub16 | Calculate the difference of two vectors. |
| DSP_VectorSub32 | Calculate the difference of two vectors. |
| DSP_VectorSumSquares16 | Computes the sum of squares of a vector, and scales the output by a binary factor. |
| DSP_VectorSumSquares32 | Computes the sum of squares of a vector, and scales the output by a binary factor. |
| DSP_VectorVari16 | Computes the variance of N elements of a Vector. |
| DSP_VectorVariance | Computes the variance of N elements of inVector. |
| DSP_VectorZeroPad | Fills an input vector with zeros. |
| mul16 | Multiply and shift integer. |
| mul16r | Multiply and shift Q15. |
| mul32 | Multiply and shift Q31. |
| SAT16 | Saturate both positive and negative Q15. |
| SAT16N | Saturate negative Q15. |
| SAT16P | Saturate positive Q15. |