blob: 580cbbde60c616052c3dd03c9e30584dc46aaf49 [file] [log] [blame]
 /* ---------------------------------------------------------------------- * Copyright (C) 2010-2015 ARM Limited. All rights reserved. * * $Date: 20. October 2015 *$Revision: V1.4.5 b * * Project: CMSIS DSP Library * Title: arm_math.h * * Description: Public header file for CMSIS DSP Library * * Target Processor: Cortex-M7/Cortex-M4/Cortex-M3/Cortex-M0 * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * - Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * - Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in * the documentation and/or other materials provided with the * distribution. * - Neither the name of ARM LIMITED nor the names of its contributors * may be used to endorse or promote products derived from this * software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. * -------------------------------------------------------------------- */ /** \mainpage CMSIS DSP Software Library * * Introduction * ------------ * * This user manual describes the CMSIS DSP software library, * a suite of common signal processing functions for use on Cortex-M processor based devices. * * The library is divided into a number of functions each covering a specific category: * - Basic math functions * - Fast math functions * - Complex math functions * - Filters * - Matrix functions * - Transforms * - Motor control functions * - Statistical functions * - Support functions * - Interpolation functions * * The library has separate functions for operating on 8-bit integers, 16-bit integers, * 32-bit integer and 32-bit floating-point values. * * Using the Library * ------------ * * The library installer contains prebuilt versions of the libraries in the Lib folder. * - arm_cortexM7lfdp_math.lib (Little endian and Double Precision Floating Point Unit on Cortex-M7) * - arm_cortexM7bfdp_math.lib (Big endian and Double Precision Floating Point Unit on Cortex-M7) * - arm_cortexM7lfsp_math.lib (Little endian and Single Precision Floating Point Unit on Cortex-M7) * - arm_cortexM7bfsp_math.lib (Big endian and Single Precision Floating Point Unit on Cortex-M7) * - arm_cortexM7l_math.lib (Little endian on Cortex-M7) * - arm_cortexM7b_math.lib (Big endian on Cortex-M7) * - arm_cortexM4lf_math.lib (Little endian and Floating Point Unit on Cortex-M4) * - arm_cortexM4bf_math.lib (Big endian and Floating Point Unit on Cortex-M4) * - arm_cortexM4l_math.lib (Little endian on Cortex-M4) * - arm_cortexM4b_math.lib (Big endian on Cortex-M4) * - arm_cortexM3l_math.lib (Little endian on Cortex-M3) * - arm_cortexM3b_math.lib (Big endian on Cortex-M3) * - arm_cortexM0l_math.lib (Little endian on Cortex-M0 / CortexM0+) * - arm_cortexM0b_math.lib (Big endian on Cortex-M0 / CortexM0+) * * The library functions are declared in the public file arm_math.h which is placed in the Include folder. * Simply include this file and link the appropriate library in the application and begin calling the library functions. The Library supports single * public header file arm_math.h for Cortex-M7/M4/M3/M0/M0+ with little endian and big endian. Same header file will be used for floating point unit(FPU) variants. * Define the appropriate pre processor MACRO ARM_MATH_CM7 or ARM_MATH_CM4 or ARM_MATH_CM3 or * ARM_MATH_CM0 or ARM_MATH_CM0PLUS depending on the target processor in the application. * * Examples * -------- * * The library ships with a number of examples which demonstrate how to use the library functions. * * Toolchain Support * ------------ * * The library has been developed and tested with MDK-ARM version 5.14.0.0 * The library is being tested in GCC and IAR toolchains and updates on this activity will be made available shortly. * * Building the Library * ------------ * * The library installer contains a project file to re build libraries on MDK-ARM Tool chain in the CMSIS\\DSP_Lib\\Source\\ARM folder. * - arm_cortexM_math.uvprojx * * * The libraries can be built by opening the arm_cortexM_math.uvprojx project in MDK-ARM, selecting a specific target, and defining the optional pre processor MACROs detailed above. * * Pre-processor Macros * ------------ * * Each library project have differant pre-processor macros. * * - UNALIGNED_SUPPORT_DISABLE: * * Define macro UNALIGNED_SUPPORT_DISABLE, If the silicon does not support unaligned memory access * * - ARM_MATH_BIG_ENDIAN: * * Define macro ARM_MATH_BIG_ENDIAN to build the library for big endian targets. By default library builds for little endian targets. * * - ARM_MATH_MATRIX_CHECK: * * Define macro ARM_MATH_MATRIX_CHECK for checking on the input and output sizes of matrices * * - ARM_MATH_ROUNDING: * * Define macro ARM_MATH_ROUNDING for rounding on support functions * * - ARM_MATH_CMx: * * Define macro ARM_MATH_CM4 for building the library on Cortex-M4 target, ARM_MATH_CM3 for building library on Cortex-M3 target * and ARM_MATH_CM0 for building library on Cortex-M0 target, ARM_MATH_CM0PLUS for building library on Cortex-M0+ target, and * ARM_MATH_CM7 for building the library on cortex-M7. * * - __FPU_PRESENT: * * Initialize macro __FPU_PRESENT = 1 when building on FPU supported Targets. Enable this macro for M4bf and M4lf libraries * *
* CMSIS-DSP in ARM::CMSIS Pack * ----------------------------- * * The following files relevant to CMSIS-DSP are present in the ARM::CMSIS Pack directories: * |File/Folder |Content | * |------------------------------|------------------------------------------------------------------------| * |\b CMSIS\\Documentation\\DSP | This documentation | * |\b CMSIS\\DSP_Lib | Software license agreement (license.txt) | * |\b CMSIS\\DSP_Lib\\Examples | Example projects demonstrating the usage of the library functions | * |\b CMSIS\\DSP_Lib\\Source | Source files for rebuilding the library | * *
* Revision History of CMSIS-DSP * ------------ * Please refer to \ref ChangeLog_pg. * * Copyright Notice * ------------ * * Copyright (C) 2010-2015 ARM Limited. All rights reserved. */ /** * @defgroup groupMath Basic Math Functions */ /** * @defgroup groupFastMath Fast Math Functions * This set of functions provides a fast approximation to sine, cosine, and square root. * As compared to most of the other functions in the CMSIS math library, the fast math functions * operate on individual values and not arrays. * There are separate functions for Q15, Q31, and floating-point data. * */ /** * @defgroup groupCmplxMath Complex Math Functions * This set of functions operates on complex data vectors. * The data in the complex arrays is stored in an interleaved fashion * (real, imag, real, imag, ...). * In the API functions, the number of samples in a complex array refers * to the number of complex values; the array contains twice this number of * real values. */ /** * @defgroup groupFilters Filtering Functions */ /** * @defgroup groupMatrix Matrix Functions * * This set of functions provides basic matrix math operations. * The functions operate on matrix data structures. For example, * the type * definition for the floating-point matrix structure is shown * below: *
*     typedef struct
*     {
*       uint16_t numRows;     // number of rows of the matrix.
*       uint16_t numCols;     // number of columns of the matrix.
*       float32_t *pData;     // points to the data of the matrix.
*     } arm_matrix_instance_f32;
*
* There are similar definitions for Q15 and Q31 data types. * * The structure specifies the size of the matrix and then points to * an array of data. The array is of size numRows X numCols * and the values are arranged in row order. That is, the * matrix element (i, j) is stored at: *
*     pData[i*numCols + j]
*
* * \par Init Functions * There is an associated initialization function for each type of matrix * data structure. * The initialization function sets the values of the internal structure fields. * Refer to the function arm_mat_init_f32(), arm_mat_init_q31() * and arm_mat_init_q15() for floating-point, Q31 and Q15 types, respectively. * * \par * Use of the initialization function is optional. However, if initialization function is used * then the instance structure cannot be placed into a const data section. * To place the instance structure in a const data * section, manually initialize the data structure. For example: *
* arm_matrix_instance_f32 S = {nRows, nColumns, pData};
* arm_matrix_instance_q31 S = {nRows, nColumns, pData};
* arm_matrix_instance_q15 S = {nRows, nColumns, pData};
*
* where nRows specifies the number of rows, nColumns * specifies the number of columns, and pData points to the * data array. * * \par Size Checking * By default all of the matrix functions perform size checking on the input and * output matrices. For example, the matrix addition function verifies that the * two input matrices and the output matrix all have the same number of rows and * columns. If the size check fails the functions return: *
*     ARM_MATH_SIZE_MISMATCH
*
* Otherwise the functions return *
*     ARM_MATH_SUCCESS
*
* There is some overhead associated with this matrix size checking. * The matrix size checking is enabled via the \#define *
*     ARM_MATH_MATRIX_CHECK
*