1 /******************************************************************************
2 * @file fast_math_functions.h
3 * @brief Public header file for CMSIS DSP Library
4 * @version V1.9.0
5 * @date 23 April 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 #ifdef __cplusplus
37 extern "C"
38 {
39 #endif
40
41 /**
42 * @brief Macros required for SINE and COSINE Fast math approximations
43 */
44
45 #define FAST_MATH_TABLE_SIZE 512
46 #define FAST_MATH_Q31_SHIFT (32 - 10)
47 #define FAST_MATH_Q15_SHIFT (16 - 10)
48
49 #ifndef PI
50 #define PI 3.14159265358979f
51 #endif
52
53
54 /**
55 * @defgroup groupFastMath Fast Math Functions
56 * This set of functions provides a fast approximation to sine, cosine, and square root.
57 * As compared to most of the other functions in the CMSIS math library, the fast math functions
58 * operate on individual values and not arrays.
59 * There are separate functions for Q15, Q31, and floating-point data.
60 *
61 */
62
63 /**
64 * @ingroup groupFastMath
65 */
66
67
68 /**
69 @addtogroup sin
70 @{
71 */
72
73 /**
74 * @brief Fast approximation to the trigonometric sine function for floating-point data.
75 * @param[in] x input value in radians.
76 * @return sin(x).
77 */
78 float32_t arm_sin_f32(
79 float32_t x);
80
81
82 /**
83 * @brief Fast approximation to the trigonometric sine function for Q31 data.
84 * @param[in] x Scaled input value in radians.
85 * @return sin(x).
86 */
87 q31_t arm_sin_q31(
88 q31_t x);
89
90
91 /**
92 * @brief Fast approximation to the trigonometric sine function for Q15 data.
93 * @param[in] x Scaled input value in radians.
94 * @return sin(x).
95 */
96 q15_t arm_sin_q15(
97 q15_t x);
98
99 /**
100 @} end of sin group
101 */
102
103 /**
104 @addtogroup cos
105 @{
106 */
107
108 /**
109 * @brief Fast approximation to the trigonometric cosine function for floating-point data.
110 * @param[in] x input value in radians.
111 * @return cos(x).
112 */
113 float32_t arm_cos_f32(
114 float32_t x);
115
116
117 /**
118 * @brief Fast approximation to the trigonometric cosine function for Q31 data.
119 * @param[in] x Scaled input value in radians.
120 * @return cos(x).
121 */
122 q31_t arm_cos_q31(
123 q31_t x);
124
125
126 /**
127 * @brief Fast approximation to the trigonometric cosine function for Q15 data.
128 * @param[in] x Scaled input value in radians.
129 * @return cos(x).
130 */
131 q15_t arm_cos_q15(
132 q15_t x);
133
134 /**
135 @} end of cos group
136 */
137
138
139 /**
140 @brief Floating-point vector of log values.
141 @param[in] pSrc points to the input vector
142 @param[out] pDst points to the output vector
143 @param[in] blockSize number of samples in each vector
144 @return none
145 */
146 void arm_vlog_f32(
147 const float32_t * pSrc,
148 float32_t * pDst,
149 uint32_t blockSize);
150
151 /**
152 @brief Floating-point vector of exp values.
153 @param[in] pSrc points to the input vector
154 @param[out] pDst points to the output vector
155 @param[in] blockSize number of samples in each vector
156 @return none
157 */
158 void arm_vexp_f32(
159 const float32_t * pSrc,
160 float32_t * pDst,
161 uint32_t blockSize);
162
163 /**
164 * @defgroup SQRT Square Root
165 *
166 * Computes the square root of a number.
167 * There are separate functions for Q15, Q31, and floating-point data types.
168 * The square root function is computed using the Newton-Raphson algorithm.
169 * This is an iterative algorithm of the form:
170 * <pre>
171 * x1 = x0 - f(x0)/f'(x0)
172 * </pre>
173 * where <code>x1</code> is the current estimate,
174 * <code>x0</code> is the previous estimate, and
175 * <code>f'(x0)</code> is the derivative of <code>f()</code> evaluated at <code>x0</code>.
176 * For the square root function, the algorithm reduces to:
177 * <pre>
178 * x0 = in/2 [initial guess]
179 * x1 = 1/2 * ( x0 + in / x0) [each iteration]
180 * </pre>
181 */
182
183
184 /**
185 * @addtogroup SQRT
186 * @{
187 */
188
189 /**
190 @brief Floating-point square root function.
191 @param[in] in input value
192 @param[out] pOut square root of input value
193 @return execution status
194 - \ref ARM_MATH_SUCCESS : input value is positive
195 - \ref ARM_MATH_ARGUMENT_ERROR : input value is negative; *pOut is set to 0
196 */
arm_sqrt_f32(float32_t in,float32_t * pOut)197 __STATIC_FORCEINLINE arm_status arm_sqrt_f32(
198 float32_t in,
199 float32_t * pOut)
200 {
201 if (in >= 0.0f)
202 {
203 #if defined ( __CC_ARM )
204 #if defined __TARGET_FPU_VFP
205 *pOut = __sqrtf(in);
206 #else
207 *pOut = sqrtf(in);
208 #endif
209
210 #elif defined ( __ICCARM__ )
211 #if defined __ARMVFP__
212 __ASM("VSQRT.F32 %0,%1" : "=t"(*pOut) : "t"(in));
213 #else
214 *pOut = sqrtf(in);
215 #endif
216
217 #else
218 *pOut = sqrtf(in);
219 #endif
220
221 return (ARM_MATH_SUCCESS);
222 }
223 else
224 {
225 *pOut = 0.0f;
226 return (ARM_MATH_ARGUMENT_ERROR);
227 }
228 }
229
230
231 /**
232 @brief Q31 square root function.
233 @param[in] in input value. The range of the input value is [0 +1) or 0x00000000 to 0x7FFFFFFF
234 @param[out] pOut points to square root of input value
235 @return execution status
236 - \ref ARM_MATH_SUCCESS : input value is positive
237 - \ref ARM_MATH_ARGUMENT_ERROR : input value is negative; *pOut is set to 0
238 */
239 arm_status arm_sqrt_q31(
240 q31_t in,
241 q31_t * pOut);
242
243
244 /**
245 @brief Q15 square root function.
246 @param[in] in input value. The range of the input value is [0 +1) or 0x0000 to 0x7FFF
247 @param[out] pOut points to square root of input value
248 @return execution status
249 - \ref ARM_MATH_SUCCESS : input value is positive
250 - \ref ARM_MATH_ARGUMENT_ERROR : input value is negative; *pOut is set to 0
251 */
252 arm_status arm_sqrt_q15(
253 q15_t in,
254 q15_t * pOut);
255
256 /**
257 * @brief Vector Floating-point square root function.
258 * @param[in] pIn input vector.
259 * @param[out] pOut vector of square roots of input elements.
260 * @param[in] len length of input vector.
261 * @return The function returns ARM_MATH_SUCCESS if input value is positive value or ARM_MATH_ARGUMENT_ERROR if
262 * <code>in</code> is negative value and returns zero output for negative values.
263 */
264 void arm_vsqrt_f32(
265 float32_t * pIn,
266 float32_t * pOut,
267 uint16_t len);
268
269 void arm_vsqrt_q31(
270 q31_t * pIn,
271 q31_t * pOut,
272 uint16_t len);
273
274 void arm_vsqrt_q15(
275 q15_t * pIn,
276 q15_t * pOut,
277 uint16_t len);
278
279 /**
280 * @} end of SQRT group
281 */
282
283 /**
284 @brief Fixed point division
285 @param[in] numerator Numerator
286 @param[in] denominator Denominator
287 @param[out] quotient Quotient value normalized between -1.0 and 1.0
288 @param[out] shift Shift left value to get the unnormalized quotient
289 @return error status
290
291 When dividing by 0, an error ARM_MATH_NANINF is returned. And the quotient is forced
292 to the saturated negative or positive value.
293 */
294
295 arm_status arm_divide_q15(q15_t numerator,
296 q15_t denominator,
297 q15_t *quotient,
298 int16_t *shift);
299
300
301 #ifdef __cplusplus
302 }
303 #endif
304
305 #endif /* ifndef _FAST_MATH_FUNCTIONS_H_ */
306
