fast_math_functions.h
1 /****************************************************************************** 2 * @file fast_math_functions.h 3 * @brief Public header file for CMSIS DSP Library 4 * @version V1.10.0 5 * @date 08 July 2021 6 * Target Processor: Cortex-M and Cortex-A cores 7 ******************************************************************************/ 8 /* 9 * Copyright (c) 2010-2020 Arm Limited or its affiliates. All rights reserved. 10 * 11 * SPDX-License-Identifier: Apache-2.0 12 * 13 * Licensed under the Apache License, Version 2.0 (the License); you may 14 * not use this file except in compliance with the License. 15 * You may obtain a copy of the License at 16 * 17 * www.apache.org/licenses/LICENSE-2.0 18 * 19 * Unless required by applicable law or agreed to in writing, software 20 * distributed under the License is distributed on an AS IS BASIS, WITHOUT 21 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 22 * See the License for the specific language governing permissions and 23 * limitations under the License. 24 */ 25 26 27 #ifndef _FAST_MATH_FUNCTIONS_H_ 28 #define _FAST_MATH_FUNCTIONS_H_ 29 30 #include "arm_math_types.h" 31 #include "arm_math_memory.h" 32 33 #include "dsp/none.h" 34 #include "dsp/utils.h" 35 36 #include "dsp/basic_math_functions.h" 37 38 39 #ifdef __cplusplus 40 extern "C" 41 { 42 #endif 43 44 /** 45 * @brief Macros required for SINE and COSINE Fast math approximations 46 */ 47 48 #define FAST_MATH_TABLE_SIZE 512 49 #define FAST_MATH_Q31_SHIFT (32 - 10) 50 #define FAST_MATH_Q15_SHIFT (16 - 10) 51 52 #ifndef PI 53 #define PI 3.14159265358979f 54 #endif 55 56 57 /** 58 * @defgroup groupFastMath Fast Math Functions 59 * This set of functions provides a fast approximation to sine, cosine, and square root. 60 * As compared to most of the other functions in the CMSIS math library, the fast math functions 61 * operate on individual values and not arrays. 62 * There are separate functions for Q15, Q31, and floating-point data. 63 * 64 */ 65 66 /** 67 * @ingroup groupFastMath 68 */ 69 70 71 /** 72 @addtogroup sin 73 @{ 74 */ 75 76 /** 77 * @brief Fast approximation to the trigonometric sine function for floating-point data. 78 * @param[in] x input value in radians. 79 * @return sin(x). 80 */ 81 float32_t arm_sin_f32( 82 float32_t x); 83 84 85 /** 86 * @brief Fast approximation to the trigonometric sine function for Q31 data. 87 * @param[in] x Scaled input value in radians. 88 * @return sin(x). 89 */ 90 q31_t arm_sin_q31( 91 q31_t x); 92 93 94 /** 95 * @brief Fast approximation to the trigonometric sine function for Q15 data. 96 * @param[in] x Scaled input value in radians. 97 * @return sin(x). 98 */ 99 q15_t arm_sin_q15( 100 q15_t x); 101 102 /** 103 @} end of sin group 104 */ 105 106 /** 107 @addtogroup cos 108 @{ 109 */ 110 111 /** 112 * @brief Fast approximation to the trigonometric cosine function for floating-point data. 113 * @param[in] x input value in radians. 114 * @return cos(x). 115 */ 116 float32_t arm_cos_f32( 117 float32_t x); 118 119 120 /** 121 * @brief Fast approximation to the trigonometric cosine function for Q31 data. 122 * @param[in] x Scaled input value in radians. 123 * @return cos(x). 124 */ 125 q31_t arm_cos_q31( 126 q31_t x); 127 128 129 /** 130 * @brief Fast approximation to the trigonometric cosine function for Q15 data. 131 * @param[in] x Scaled input value in radians. 132 * @return cos(x). 133 */ 134 q15_t arm_cos_q15( 135 q15_t x); 136 137 /** 138 @} end of cos group 139 */ 140 141 142 /** 143 @brief Floating-point vector of log values. 144 @param[in] pSrc points to the input vector 145 @param[out] pDst points to the output vector 146 @param[in] blockSize number of samples in each vector 147 @return none 148 */ 149 void arm_vlog_f32( 150 const float32_t * pSrc, 151 float32_t * pDst, 152 uint32_t blockSize); 153 154 155 156 /** 157 @brief Floating-point vector of log values. 158 @param[in] pSrc points to the input vector 159 @param[out] pDst points to the output vector 160 @param[in] blockSize number of samples in each vector 161 @return none 162 */ 163 void arm_vlog_f64( 164 const float64_t * pSrc, 165 float64_t * pDst, 166 uint32_t blockSize); 167 168 169 170 /** 171 * @brief q31 vector of log values. 172 * @param[in] pSrc points to the input vector in q31 173 * @param[out] pDst points to the output vector in q5.26 174 * @param[in] blockSize number of samples in each vector 175 * @return none 176 */ 177 void arm_vlog_q31(const q31_t * pSrc, 178 q31_t * pDst, 179 uint32_t blockSize); 180 181 /** 182 * @brief q15 vector of log values. 183 * @param[in] pSrc points to the input vector in q15 184 * @param[out] pDst points to the output vector in q4.11 185 * @param[in] blockSize number of samples in each vector 186 * @return none 187 */ 188 void arm_vlog_q15(const q15_t * pSrc, 189 q15_t * pDst, 190 uint32_t blockSize); 191 192 193 194 /** 195 @brief Floating-point vector of exp values. 196 @param[in] pSrc points to the input vector 197 @param[out] pDst points to the output vector 198 @param[in] blockSize number of samples in each vector 199 @return none 200 */ 201 void arm_vexp_f32( 202 const float32_t * pSrc, 203 float32_t * pDst, 204 uint32_t blockSize); 205 206 207 208 /** 209 @brief Floating-point vector of exp values. 210 @param[in] pSrc points to the input vector 211 @param[out] pDst points to the output vector 212 @param[in] blockSize number of samples in each vector 213 @return none 214 */ 215 void arm_vexp_f64( 216 const float64_t * pSrc, 217 float64_t * pDst, 218 uint32_t blockSize); 219 220 221 222 /** 223 * @defgroup SQRT Square Root 224 * 225 * Computes the square root of a number. 226 * There are separate functions for Q15, Q31, and floating-point data types. 227 * The square root function is computed using the Newton-Raphson algorithm. 228 * This is an iterative algorithm of the form: 229 * <pre> 230 * x1 = x0 - f(x0)/f'(x0) 231 * </pre> 232 * where <code>x1</code> is the current estimate, 233 * <code>x0</code> is the previous estimate, and 234 * <code>f'(x0)</code> is the derivative of <code>f()</code> evaluated at <code>x0</code>. 235 * For the square root function, the algorithm reduces to: 236 * <pre> 237 * x0 = in/2 [initial guess] 238 * x1 = 1/2 * ( x0 + in / x0) [each iteration] 239 * </pre> 240 */ 241 242 243 /** 244 * @addtogroup SQRT 245 * @{ 246 */ 247 248 /** 249 @brief Floating-point square root function. 250 @param[in] in input value 251 @param[out] pOut square root of input value 252 @return execution status 253 - \ref ARM_MATH_SUCCESS : input value is positive 254 - \ref ARM_MATH_ARGUMENT_ERROR : input value is negative; *pOut is set to 0 255 */ 256 __STATIC_FORCEINLINE arm_status arm_sqrt_f32( 257 const float32_t in, 258 float32_t * pOut) 259 { 260 if (in >= 0.0f) 261 { 262 #if defined ( __CC_ARM ) 263 #if defined __TARGET_FPU_VFP 264 *pOut = __sqrtf(in); 265 #else 266 *pOut = sqrtf(in); 267 #endif 268 269 #elif defined ( __ICCARM__ ) 270 #if defined __ARMVFP__ 271 __ASM("VSQRT.F32 %0,%1" : "=t"(*pOut) : "t"(in)); 272 #else 273 *pOut = sqrtf(in); 274 #endif 275 276 #else 277 *pOut = sqrtf(in); 278 #endif 279 280 return (ARM_MATH_SUCCESS); 281 } 282 else 283 { 284 *pOut = 0.0f; 285 return (ARM_MATH_ARGUMENT_ERROR); 286 } 287 } 288 289 290 /** 291 @brief Q31 square root function. 292 @param[in] in input value. The range of the input value is [0 +1) or 0x00000000 to 0x7FFFFFFF 293 @param[out] pOut points to square root of input value 294 @return execution status 295 - \ref ARM_MATH_SUCCESS : input value is positive 296 - \ref ARM_MATH_ARGUMENT_ERROR : input value is negative; *pOut is set to 0 297 */ 298 arm_status arm_sqrt_q31( 299 q31_t in, 300 q31_t * pOut); 301 302 303 /** 304 @brief Q15 square root function. 305 @param[in] in input value. The range of the input value is [0 +1) or 0x0000 to 0x7FFF 306 @param[out] pOut points to square root of input value 307 @return execution status 308 - \ref ARM_MATH_SUCCESS : input value is positive 309 - \ref ARM_MATH_ARGUMENT_ERROR : input value is negative; *pOut is set to 0 310 */ 311 arm_status arm_sqrt_q15( 312 q15_t in, 313 q15_t * pOut); 314 315 316 317 /** 318 * @} end of SQRT group 319 */ 320 321 /** 322 @brief Fixed point division 323 @param[in] numerator Numerator 324 @param[in] denominator Denominator 325 @param[out] quotient Quotient value normalized between -1.0 and 1.0 326 @param[out] shift Shift left value to get the unnormalized quotient 327 @return error status 328 329 When dividing by 0, an error ARM_MATH_NANINF is returned. And the quotient is forced 330 to the saturated negative or positive value. 331 */ 332 333 arm_status arm_divide_q15(q15_t numerator, 334 q15_t denominator, 335 q15_t *quotient, 336 int16_t *shift); 337 338 /** 339 @brief Fixed point division 340 @param[in] numerator Numerator 341 @param[in] denominator Denominator 342 @param[out] quotient Quotient value normalized between -1.0 and 1.0 343 @param[out] shift Shift left value to get the unnormalized quotient 344 @return error status 345 346 When dividing by 0, an error ARM_MATH_NANINF is returned. And the quotient is forced 347 to the saturated negative or positive value. 348 */ 349 350 arm_status arm_divide_q31(q31_t numerator, 351 q31_t denominator, 352 q31_t *quotient, 353 int16_t *shift); 354 355 356 357 /** 358 @brief Arc tangent in radian of y/x using sign of x and y to determine right quadrant. 359 @param[in] y y coordinate 360 @param[in] x x coordinate 361 @param[out] result Result 362 @return error status. 363 */ 364 arm_status arm_atan2_f32(float32_t y,float32_t x,float32_t *result); 365 366 367 /** 368 @brief Arc tangent in radian of y/x using sign of x and y to determine right quadrant. 369 @param[in] y y coordinate 370 @param[in] x x coordinate 371 @param[out] result Result in Q2.29 372 @return error status. 373 */ 374 arm_status arm_atan2_q31(q31_t y,q31_t x,q31_t *result); 375 376 /** 377 @brief Arc tangent in radian of y/x using sign of x and y to determine right quadrant. 378 @param[in] y y coordinate 379 @param[in] x x coordinate 380 @param[out] result Result in Q2.13 381 @return error status. 382 */ 383 arm_status arm_atan2_q15(q15_t y,q15_t x,q15_t *result); 384 385 #ifdef __cplusplus 386 } 387 #endif 388 389 #endif /* ifndef _FAST_MATH_FUNCTIONS_H_ */