LCOV - code coverage report
Current view: top level - zephyr/dsp - basicmath.h Coverage Total Hit
Test: new.info Lines: 100.0 % 52 52
Test Date: 2025-09-05 22:20:39

            Line data    Source code
       1            1 : /* Copyright (C) 2010-2021 ARM Limited or its affiliates. All rights reserved.
       2              :  * SPDX-License-Identifier: Apache-2.0
       3              :  */
       4              : 
       5              : /**
       6              :  * @file zephyr/dsp/basicmath.h
       7              :  *
       8              :  * @brief Public APIs for DSP basicmath
       9              :  */
      10              : 
      11              : #ifndef ZEPHYR_INCLUDE_DSP_BASICMATH_H_
      12              : #define ZEPHYR_INCLUDE_DSP_BASICMATH_H_
      13              : 
      14              : #include <zephyr/dsp/dsp.h>
      15              : 
      16              : #ifdef __cplusplus
      17              : extern "C" {
      18              : #endif
      19              : 
      20              : /**
      21              :  * @ingroup math_dsp
      22              :  * @defgroup math_dsp_basic Basic Math Functions
      23              :  * Basic element-wise math operations for DSP.
      24              :  * @{
      25              :  */
      26              : 
      27              : /**
      28              :  * @ingroup math_dsp_basic
      29              :  * @defgroup math_dsp_basic_mult Vector Multiplication
      30              :  *
      31              :  * Element-by-element multiplication of two vectors.
      32              :  * <pre>
      33              :  *     dst[n] = src_a[n] * src_b[n],   0 <= n < block_size.
      34              :  * </pre>
      35              :  * There are separate functions for floating-point, Q7, Q15, and Q31 data types.
      36              :  * @{
      37              :  */
      38              : 
      39              : /**
      40              :  * @brief Q7 vector multiplication.
      41              :  *
      42              :  * @par Scaling and Overflow Behavior
      43              :  *   The function uses saturating arithmetic.
      44              :  *   Results outside of the allowable Q7 range [0x80 0x7F] are saturated.
      45              :  *
      46              :  * @param[in]  src_a      points to the first input vector
      47              :  * @param[in]  src_b      points to the second input vector
      48              :  * @param[out] dst        points to the output vector
      49              :  * @param[in]  block_size number of samples in each vector
      50              :  */
      51            1 : DSP_FUNC_SCOPE void zdsp_mult_q7(const DSP_DATA q7_t *src_a, const DSP_DATA q7_t *src_b,
      52              :                                 DSP_DATA q7_t *dst, uint32_t block_size);
      53              : 
      54              : /**
      55              :  * @brief Q15 vector multiplication.
      56              :  *
      57              :  * @par Scaling and Overflow Behavior
      58              :  *   The function uses saturating arithmetic.
      59              :  *   Results outside of the allowable Q15 range [0x8000 0x7FFF] are saturated.
      60              :  *
      61              :  * @param[in]  src_a      points to the first input vector
      62              :  * @param[in]  src_b      points to the second input vector
      63              :  * @param[out] dst        points to the output vector
      64              :  * @param[in]  block_size number of samples in each vector
      65              :  */
      66            1 : DSP_FUNC_SCOPE void zdsp_mult_q15(const DSP_DATA q15_t *src_a, const DSP_DATA q15_t *src_b,
      67              :                                 DSP_DATA q15_t *dst, uint32_t block_size);
      68              : 
      69              : /**
      70              :  * @brief Q31 vector multiplication.
      71              :  *
      72              :  * @par Scaling and Overflow Behavior
      73              :  *   The function uses saturating arithmetic.
      74              :  *   Results outside of the allowable Q31 range[0x80000000 0x7FFFFFFF] are saturated.
      75              :  *
      76              :  * @param[in]  src_a      points to the first input vector
      77              :  * @param[in]  src_b      points to the second input vector
      78              :  * @param[out] dst        points to the output vector
      79              :  * @param[in]  block_size number of samples in each vector
      80              :  */
      81            1 : DSP_FUNC_SCOPE void zdsp_mult_q31(const DSP_DATA q31_t *src_a, const DSP_DATA q31_t *src_b,
      82              :                                 DSP_DATA q31_t *dst, uint32_t block_size);
      83              : 
      84              : /**
      85              :  * @brief Floating-point vector multiplication.
      86              :  * @param[in]  src_a      points to the first input vector
      87              :  * @param[in]  src_b      points to the second input vector
      88              :  * @param[out] dst        points to the output vector
      89              :  * @param[in]  block_size number of samples in each vector
      90              :  */
      91            1 : DSP_FUNC_SCOPE void zdsp_mult_f32(const DSP_DATA float32_t *src_a, const DSP_DATA float32_t *src_b,
      92              :                                 DSP_DATA float32_t *dst, uint32_t block_size);
      93              : 
      94              : /**
      95              :  * @}
      96              :  */
      97              : 
      98              : /**
      99              :  * @ingroup math_dsp_basic
     100              :  * @defgroup math_dsp_basic_add Vector Addition
     101              :  *
     102              :  * Element-by-element addition of two vectors.
     103              :  * <pre>
     104              :  *     dst[n] = src_a[n] + src_b[n],   0 <= n < block_size.
     105              :  * </pre>
     106              :  * There are separate functions for floating-point, Q7, Q15, and Q31 data types.
     107              :  * @{
     108              :  */
     109              : 
     110              : /**
     111              :  * @brief Floating-point vector addition.
     112              :  * @param[in]  src_a      points to the first input vector
     113              :  * @param[in]  src_b      points to the second input vector
     114              :  * @param[out] dst        points to the output vector
     115              :  * @param[in]  block_size number of samples in each vector
     116              :  */
     117            1 : DSP_FUNC_SCOPE void zdsp_add_f32(const DSP_DATA float32_t *src_a, const DSP_DATA float32_t *src_b,
     118              :                                 DSP_DATA float32_t *dst, uint32_t block_size);
     119              : 
     120              : /**
     121              :  * @brief Q7 vector addition.
     122              :  *
     123              :  * @par Scaling and Overflow Behavior
     124              :  *   The function uses saturating arithmetic.
     125              :  *   Results outside of the allowable Q7 range [0x80 0x7F] are saturated.
     126              :  *
     127              :  * @param[in]  src_a      points to the first input vector
     128              :  * @param[in]  src_b      points to the second input vector
     129              :  * @param[out] dst        points to the output vector
     130              :  * @param[in]  block_size number of samples in each vector
     131              :  */
     132            1 : DSP_FUNC_SCOPE void zdsp_add_q7(const DSP_DATA q7_t *src_a, const DSP_DATA q7_t *src_b,
     133              :                                 DSP_DATA q7_t *dst, uint32_t block_size);
     134              : 
     135              : /**
     136              :  * @brief Q15 vector addition.
     137              :  *
     138              :  * @par Scaling and Overflow Behavior
     139              :  *   The function uses saturating arithmetic.
     140              :  *   Results outside of the allowable Q15 range [0x8000 0x7FFF] are saturated.
     141              :  *
     142              :  * @param[in]  src_a      points to the first input vector
     143              :  * @param[in]  src_b      points to the second input vector
     144              :  * @param[out] dst        points to the output vector
     145              :  * @param[in]  block_size number of samples in each vector
     146              :  */
     147            1 : DSP_FUNC_SCOPE void zdsp_add_q15(const DSP_DATA q15_t *src_a, const DSP_DATA q15_t *src_b,
     148              :                                 DSP_DATA q15_t *dst, uint32_t block_size);
     149              : 
     150              : /**
     151              :  * @brief Q31 vector addition.
     152              :  *
     153              :  * @par Scaling and Overflow Behavior
     154              :  *   The function uses saturating arithmetic.
     155              :  *   Results outside of the allowable Q31 range [0x80000000 0x7FFFFFFF] are saturated.
     156              :  *
     157              :  * @param[in]  src_a      points to the first input vector
     158              :  * @param[in]  src_b      points to the second input vector
     159              :  * @param[out] dst        points to the output vector
     160              :  * @param[in]  block_size number of samples in each vector
     161              :  */
     162            1 : DSP_FUNC_SCOPE void zdsp_add_q31(const DSP_DATA q31_t *src_a, const DSP_DATA q31_t *src_b,
     163              :                                 DSP_DATA q31_t *dst, uint32_t block_size);
     164              : 
     165              : /**
     166              :  * @}
     167              :  */
     168              : 
     169              : /**
     170              :  * @ingroup math_dsp_basic
     171              :  * @defgroup math_dsp_basic_sub Vector Subtraction
     172              :  *
     173              :  * Element-by-element subtraction of two vectors.
     174              :  * <pre>
     175              :  *     dst[n] = src_a[n] - src_b[n],   0 <= n < block_size.
     176              :  * </pre>
     177              :  * There are separate functions for floating-point, Q7, Q15, and Q31 data types.
     178              :  * @{
     179              :  */
     180              : 
     181              : /**
     182              :  * @brief Floating-point vector subtraction.
     183              :  * @param[in]  src_a      points to the first input vector
     184              :  * @param[in]  src_b      points to the second input vector
     185              :  * @param[out] dst        points to the output vector
     186              :  * @param[in]  block_size number of samples in each vector
     187              :  */
     188            1 : DSP_FUNC_SCOPE void zdsp_sub_f32(const DSP_DATA float32_t *src_a, const DSP_DATA float32_t *src_b,
     189              :                                 DSP_DATA float32_t *dst, uint32_t block_size);
     190              : 
     191              : /**
     192              :  * @brief Q7 vector subtraction.
     193              :  *
     194              :  * @par Scaling and Overflow Behavior
     195              :  *   The function uses saturating arithmetic.
     196              :  *   Results outside of the allowable Q7 range [0x80 0x7F] will be saturated.
     197              :  *
     198              :  * @param[in]  src_a      points to the first input vector
     199              :  * @param[in]  src_b      points to the second input vector
     200              :  * @param[out] dst        points to the output vector
     201              :  * @param[in]  block_size number of samples in each vector
     202              :  */
     203            1 : DSP_FUNC_SCOPE void zdsp_sub_q7(const DSP_DATA q7_t *src_a, const DSP_DATA q7_t *src_b,
     204              :                                 DSP_DATA q7_t *dst, uint32_t block_size);
     205              : 
     206              : /**
     207              :  * @brief Q15 vector subtraction.
     208              :  *
     209              :  * @par Scaling and Overflow Behavior
     210              :  *   The function uses saturating arithmetic.
     211              :  *   Results outside of the allowable Q15 range [0x8000 0x7FFF] are saturated.
     212              :  *
     213              :  * @param[in]  src_a      points to the first input vector
     214              :  * @param[in]  src_b      points to the second input vector
     215              :  * @param[out] dst        points to the output vector
     216              :  * @param[in]  block_size number of samples in each vector
     217              :  */
     218            1 : DSP_FUNC_SCOPE void zdsp_sub_q15(const DSP_DATA q15_t *src_a, const DSP_DATA q15_t *src_b,
     219              :                                 DSP_DATA q15_t *dst, uint32_t block_size);
     220              : 
     221              : /**
     222              :  * @brief Q31 vector subtraction.
     223              :  *
     224              :  * @par Scaling and Overflow Behavior
     225              :  *   The function uses saturating arithmetic.
     226              :  *   Results outside of the allowable Q31 range [0x80000000 0x7FFFFFFF] are saturated.
     227              :  *
     228              :  * @param[in]  src_a      points to the first input vector
     229              :  * @param[in]  src_b      points to the second input vector
     230              :  * @param[out] dst        points to the output vector
     231              :  * @param[in]  block_size number of samples in each vector
     232              :  */
     233            1 : DSP_FUNC_SCOPE void zdsp_sub_q31(const DSP_DATA q31_t *src_a, const DSP_DATA q31_t *src_b,
     234              :                                 DSP_DATA q31_t *dst, uint32_t block_size);
     235              : 
     236              : /**
     237              :  * @}
     238              :  */
     239              : 
     240              : /**
     241              :  * @ingroup math_dsp_basic
     242              :  * @defgroup math_dsp_basic_scale Vector Scale
     243              :  *
     244              :  * Multiply a vector by a scalar value. For floating-point data, the algorithm used is:
     245              :  * <pre>
     246              :  *     dst[n] = src[n] * scale,   0 <= n < block_size.
     247              :  * </pre>
     248              :  *
     249              :  * In the fixed-point Q7, Q15, and Q31 functions, scale is represented by a fractional
     250              :  * multiplication <code>scale_fract</code> and an arithmetic shift <code>shift</code>. The shift
     251              :  * allows the gain of the scaling operation to exceed 1.0. The algorithm used with fixed-point data
     252              :  * is:
     253              :  * <pre>
     254              :  *     dst[n] = (src[n] * scale_fract) << shift,   0 <= n < block_size.
     255              :  * </pre>
     256              :  *
     257              :  * The overall scale factor applied to the fixed-point data is
     258              :  * <pre>
     259              :  *     scale = scale_fract * 2^shift.
     260              :  * </pre>
     261              :  * The functions support in-place computation allowing the source and destination pointers to
     262              :  * reference the same memory buffer.
     263              :  * @{
     264              :  */
     265              : 
     266              : /**
     267              :  * @brief Multiplies a floating-point vector by a scalar.
     268              :  * @param[in]  src        points to the input vector
     269              :  * @param[in]  scale      scale factor to be applied
     270              :  * @param[out] dst        points to the output vector
     271              :  * @param[in]  block_size number of samples in the vector
     272              :  */
     273            1 : DSP_FUNC_SCOPE void zdsp_scale_f32(const DSP_DATA float32_t *src, float32_t scale,
     274              :                                 DSP_DATA float32_t *dst, uint32_t block_size);
     275              : 
     276              : /**
     277              :  * @brief Multiplies a Q7 vector by a scalar.
     278              :  *
     279              :  * @par Scaling and Overflow Behavior
     280              :  *   The input data <code>*src</code> and <code>scale_fract</code> are in 1.7 format.
     281              :  *   These are multiplied to yield a 2.14 intermediate result and this is shifted with saturation to
     282              :  *   1.7 format.
     283              :  *
     284              :  * @param[in]  src         points to the input vector
     285              :  * @param[in]  scale_fract fractional portion of the scale value
     286              :  * @param[in]  shift       number of bits to shift the result by
     287              :  * @param[out] dst         points to the output vector
     288              :  * @param[in]  block_size  number of samples in the vector
     289              :  */
     290            1 : DSP_FUNC_SCOPE void zdsp_scale_q7(const DSP_DATA q7_t *src, q7_t scale_fract, int8_t shift,
     291              :                                 DSP_DATA q7_t *dst, uint32_t block_size);
     292              : 
     293              : /**
     294              :  * @brief Multiplies a Q15 vector by a scalar.
     295              :  *
     296              :  * @par Scaling and Overflow Behavior
     297              :  *   The input data <code>*src</code> and <code>scale_fract</code> are in 1.15 format.
     298              :  *   These are multiplied to yield a 2.30 intermediate result and this is shifted with saturation to
     299              :  *   1.15 format.
     300              :  *
     301              :  * @param[in]  src         points to the input vector
     302              :  * @param[in]  scale_fract fractional portion of the scale value
     303              :  * @param[in]  shift       number of bits to shift the result by
     304              :  * @param[out] dst         points to the output vector
     305              :  * @param[in]  block_size  number of samples in the vector
     306              :  */
     307            1 : DSP_FUNC_SCOPE void zdsp_scale_q15(const DSP_DATA q15_t *src, q15_t scale_fract, int8_t shift,
     308              :                                 DSP_DATA q15_t *dst, uint32_t block_size);
     309              : 
     310              : /**
     311              :  * @brief Multiplies a Q31 vector by a scalar.
     312              :  *
     313              :  * @par Scaling and Overflow Behavior
     314              :  *   The input data <code>*src</code> and <code>scale_fract</code> are in 1.31 format.
     315              :  *   These are multiplied to yield a 2.62 intermediate result and this is shifted with saturation to
     316              :  *   1.31 format.
     317              :  *
     318              :  * @param[in]  src         points to the input vector
     319              :  * @param[in]  scale_fract fractional portion of the scale value
     320              :  * @param[in]  shift       number of bits to shift the result by
     321              :  * @param[out] dst         points to the output vector
     322              :  * @param[in]  block_size  number of samples in the vector
     323              :  */
     324            1 : DSP_FUNC_SCOPE void zdsp_scale_q31(const DSP_DATA q31_t *src, q31_t scale_fract, int8_t shift,
     325              :                                 DSP_DATA q31_t *dst, uint32_t block_size);
     326              : 
     327              : /**
     328              :  * @}
     329              :  */
     330              : 
     331              : /**
     332              :  * @ingroup math_dsp_basic
     333              :  * @defgroup math_dsp_basic_abs Vector Absolute Value
     334              :  *
     335              :  * Computes the absolute value of a vector on an element-by-element basis.
     336              :  * <pre>
     337              :  *     dst[n] = abs(src[n]),   0 <= n < block_size.
     338              :  * </pre>
     339              :  * The functions support in-place computation allowing the source and destination pointers to
     340              :  * reference the same memory buffer. There are separate functions for floating-point, Q7, Q15, and
     341              :  * Q31 data types.
     342              :  * @{
     343              :  */
     344              : 
     345              : /**
     346              :  * @brief Floating-point vector absolute value.
     347              :  * @param[in]  src        points to the input buffer
     348              :  * @param[out] dst        points to the output buffer
     349              :  * @param[in]  block_size number of samples in each vector
     350              :  */
     351            1 : DSP_FUNC_SCOPE void zdsp_abs_f32(const DSP_DATA float32_t *src, DSP_DATA float32_t *dst,
     352              :                                 uint32_t block_size);
     353              : 
     354              : /**
     355              :  * @brief Q7 vector absolute value.
     356              :  *
     357              :  * @par Scaling and Overflow Behavior
     358              :  *   The function uses saturating arithmetic.
     359              :  *   The Q7 value -1 (0x80) will be saturated to the maximum allowable positive value 0x7F.
     360              :  *
     361              :  * @param[in]  src        points to the input buffer
     362              :  * @param[out] dst        points to the output buffer
     363              :  * @param[in]  block_size number of samples in each vector
     364              :  */
     365            1 : DSP_FUNC_SCOPE void zdsp_abs_q7(const DSP_DATA q7_t *src, DSP_DATA q7_t *dst, uint32_t block_size);
     366              : 
     367              : /**
     368              :  * @brief Q15 vector absolute value.
     369              :  *
     370              :  * @par Scaling and Overflow Behavior
     371              :  *   The function uses saturating arithmetic.
     372              :  *   The Q15 value -1 (0x8000) will be saturated to the maximum allowable positive value 0x7FFF.
     373              :  *
     374              :  * @param[in]  src        points to the input buffer
     375              :  * @param[out] dst        points to the output buffer
     376              :  * @param[in]  block_size number of samples in each vector
     377              :  */
     378            1 : DSP_FUNC_SCOPE void zdsp_abs_q15(const DSP_DATA q15_t *src, DSP_DATA q15_t *dst,
     379              :                                 uint32_t block_size);
     380              : 
     381              : /**
     382              :  * @brief Q31 vector absolute value.
     383              :  *
     384              :  * @par Scaling and Overflow Behavior
     385              :  *   The function uses saturating arithmetic.
     386              :  *   The Q31 value -1 (0x80000000) will be saturated to the maximum allowable positive value
     387              :  *   0x7FFFFFFF.
     388              :  *
     389              :  * @param[in]  src        points to the input buffer
     390              :  * @param[out] dst        points to the output buffer
     391              :  * @param[in]  block_size number of samples in each vector
     392              :  */
     393            1 : DSP_FUNC_SCOPE void zdsp_abs_q31(const DSP_DATA q31_t *src, DSP_DATA q31_t *dst,
     394              :                                 uint32_t block_size);
     395              : 
     396              : /**
     397              :  * @}
     398              :  */
     399              : 
     400              : /**
     401              :  * @ingroup math_dsp_basic
     402              :  * @defgroup math_dsp_basic_dot Vector Dot Product
     403              :  *
     404              :  * Computes the dot product of two vectors. The vectors are multiplied element-by-element and then
     405              :  * summed.
     406              :  * <pre>
     407              :  *     sum = src_a[0]*src_b[0] + src_a[1]*src_b[1] + ... + src_a[block_size-1]*src_b[block_size-1]
     408              :  * </pre>
     409              :  * There are separate functions for floating-point, Q7, Q15, and Q31 data types.
     410              :  * @{
     411              :  */
     412              : 
     413              : /**
     414              :  * @brief Dot product of floating-point vectors.
     415              :  * @param[in]  src_a      points to the first input vector
     416              :  * @param[in]  src_b      points to the second input vector
     417              :  * @param[in]  block_size number of samples in each vector
     418              :  * @param[out] result     output result returned here
     419              :  */
     420            1 : DSP_FUNC_SCOPE void zdsp_dot_prod_f32(const DSP_DATA float32_t *src_a,
     421              :                                 const DSP_DATA float32_t *src_b, uint32_t block_size,
     422              :                                 DSP_DATA float32_t *result);
     423              : 
     424              : /**
     425              :  * @brief Dot product of Q7 vectors.
     426              :  *
     427              :  * @par Scaling and Overflow Behavior
     428              :  *   The intermediate multiplications are in 1.7 x 1.7 = 2.14 format and these results are added to
     429              :  *   an accumulator in 18.14 format. Nonsaturating additions are used and there is no danger of wrap
     430              :  *   around as long as the vectors are less than 2^18 elements long. The return result is in 18.14
     431              :  *   format.
     432              :  *
     433              :  * @param[in]  src_a      points to the first input vector
     434              :  * @param[in]  src_b      points to the second input vector
     435              :  * @param[in]  block_size number of samples in each vector
     436              :  * @param[out] result     output result returned here
     437              :  */
     438            1 : DSP_FUNC_SCOPE void zdsp_dot_prod_q7(const DSP_DATA q7_t *src_a, const DSP_DATA q7_t *src_b,
     439              :                                 uint32_t block_size, DSP_DATA q31_t *result);
     440              : 
     441              : /**
     442              :  * @brief Dot product of Q15 vectors.
     443              :  *
     444              :  * @par Scaling and Overflow Behavior
     445              :  *   The intermediate multiplications are in 1.15 x 1.15 = 2.30 format and these results are added
     446              :  *   to a 64-bit accumulator in 34.30 format. Nonsaturating additions are used and given that there
     447              :  *   are 33 guard bits in the accumulator there is no risk of overflow. The return result is in
     448              :  *   34.30 format.
     449              :  *
     450              :  * @param[in]  src_a      points to the first input vector
     451              :  * @param[in]  src_b      points to the second input vector
     452              :  * @param[in]  block_size number of samples in each vector
     453              :  * @param[out] result     output result returned here
     454              :  */
     455            1 : DSP_FUNC_SCOPE void zdsp_dot_prod_q15(const DSP_DATA q15_t *src_a, const DSP_DATA q15_t *src_b,
     456              :                                 uint32_t block_size, DSP_DATA q63_t *result);
     457              : 
     458              : /**
     459              :  * @brief Dot product of Q31 vectors.
     460              :  *
     461              :  * @par Scaling and Overflow Behavior
     462              :  *   The intermediate multiplications are in 1.31 x 1.31 = 2.62 format and these are truncated to
     463              :  *   2.48 format by discarding the lower 14 bits. The 2.48 result is then added without saturation
     464              :  *   to a 64-bit accumulator in 16.48 format. There are 15 guard bits in the accumulator and there
     465              :  *   is no risk of overflow as long as the length of the vectors is less than 2^16 elements. The
     466              :  *   return result is in 16.48 format.
     467              :  *
     468              :  * @param[in]  src_a      points to the first input vector
     469              :  * @param[in]  src_b      points to the second input vector
     470              :  * @param[in]  block_size number of samples in each vector
     471              :  * @param[out] result     output result returned here
     472              :  */
     473            1 : DSP_FUNC_SCOPE void zdsp_dot_prod_q31(const DSP_DATA q31_t *src_a, const DSP_DATA q31_t *src_b,
     474              :                                 uint32_t block_size, DSP_DATA q63_t *result);
     475              : 
     476              : /**
     477              :  * @}
     478              :  */
     479              : 
     480              : /**
     481              :  * @ingroup math_dsp_basic
     482              :  * @defgroup math_dsp_basic_shift Vector Shift
     483              :  *
     484              :  * Shifts the elements of a fixed-point vector by a specified number of bits.
     485              :  * There are separate functions for Q7, Q15, and Q31 data types. The underlying algorithm used is:
     486              :  * <pre>
     487              :  *     dst[n] = src[n] << shift,   0 <= n < block_size.
     488              :  * </pre>
     489              :  * If <code>shift</code> is positive then the elements of the vector are shifted to the left.
     490              :  * If <code>shift</code> is negative then the elements of the vector are shifted to the right.
     491              :  *
     492              :  * The functions support in-place computation allowing the source and destination pointers to
     493              :  * reference the same memory buffer.
     494              :  * @{
     495              :  */
     496              : 
     497              : /**
     498              :  * @brief  Shifts the elements of a Q7 vector a specified number of bits.
     499              :  *
     500              :  * @par Scaling and Overflow Behavior
     501              :  *   The function uses saturating arithmetic.
     502              :  *   Results outside of the allowable Q7 range [0x80 0x7F] are saturated.
     503              :  *
     504              :  * @param[in]  src        points to the input vector
     505              :  * @param[in]  shift_bits number of bits to shift.  A positive value shifts left; a negative value
     506              :  *                        shifts right.
     507              :  * @param[out] dst        points to the output vector
     508              :  * @param[in]  block_size number of samples in the vector
     509              :  */
     510            1 : DSP_FUNC_SCOPE void zdsp_shift_q7(const DSP_DATA q7_t *src, int8_t shift_bits, DSP_DATA q7_t *dst,
     511              :                                 uint32_t block_size);
     512              : 
     513              : /**
     514              :  * @brief  Shifts the elements of a Q15 vector a specified number of bits.
     515              :  *
     516              :  * @pre Scaling and Overflow Behavior
     517              :  *   The function uses saturating arithmetic.
     518              :  *   Results outside of the allowable Q15 range [0x8000 0x7FFF] are saturated.
     519              :  *
     520              :  * @param[in]  src        points to the input vector
     521              :  * @param[in]  shift_bits number of bits to shift.  A positive value shifts left; a negative value
     522              :  *                        shifts right.
     523              :  * @param[out] dst        points to the output vector
     524              :  * @param[in]  block_size number of samples in the vector
     525              :  */
     526            1 : DSP_FUNC_SCOPE void zdsp_shift_q15(const DSP_DATA q15_t *src, int8_t shift_bits,
     527              :                                 DSP_DATA q15_t *dst, uint32_t block_size);
     528              : 
     529              : /**
     530              :  * @brief  Shifts the elements of a Q31 vector a specified number of bits.
     531              :  *
     532              :  * @par Scaling and Overflow Behavior
     533              :  *   The function uses saturating arithmetic.
     534              :  *   Results outside of the allowable Q31 range [0x80000000 0x7FFFFFFF] are saturated.
     535              :  *
     536              :  * @param[in]  src       points to the input vector
     537              :  * @param[in]  shift_bits  number of bits to shift.  A positive value shifts left; a negative value
     538              :  * shifts right.
     539              :  * @param[out] dst       points to the output vector
     540              :  * @param[in]  block_size  number of samples in the vector
     541              :  */
     542            1 : DSP_FUNC_SCOPE void zdsp_shift_q31(const DSP_DATA q31_t *src, int8_t shift_bits,
     543              :                                 DSP_DATA q31_t *dst, uint32_t block_size);
     544              : 
     545              : /**
     546              :  * @}
     547              :  */
     548              : 
     549              : /**
     550              :  * @ingroup math_dsp_basic
     551              :  * @defgroup math_dsp_basic_offset Vector Offset
     552              :  *
     553              :  * Adds a constant offset to each element of a vector.
     554              :  * <pre>
     555              :  *     dst[n] = src[n] + offset,   0 <= n < block_size.
     556              :  * </pre>
     557              :  * The functions support in-place computation allowing the source and destination pointers to
     558              :  * reference the same memory buffer. There are separate functions for floating-point, Q7, Q15, and
     559              :  * Q31 data types.
     560              :  *
     561              :  * @{
     562              :  */
     563              : 
     564              : /**
     565              :  * @brief  Adds a constant offset to a floating-point vector.
     566              :  * @param[in]  src       points to the input vector
     567              :  * @param[in]  offset     is the offset to be added
     568              :  * @param[out] dst       points to the output vector
     569              :  * @param[in]  block_size  number of samples in the vector
     570              :  */
     571            1 : DSP_FUNC_SCOPE void zdsp_offset_f32(const DSP_DATA float32_t *src, float32_t offset,
     572              :                                 DSP_DATA float32_t *dst, uint32_t block_size);
     573              : 
     574              : /**
     575              :  * @brief  Adds a constant offset to a Q7 vector.
     576              :  *
     577              :  * @par Scaling and Overflow Behavior
     578              :  *   The function uses saturating arithmetic.
     579              :  *   Results outside of the allowable Q7 range [0x80 0x7F] are saturated.
     580              :  *
     581              :  * @param[in]  src       points to the input vector
     582              :  * @param[in]  offset     is the offset to be added
     583              :  * @param[out] dst       points to the output vector
     584              :  * @param[in]  block_size  number of samples in the vector
     585              :  */
     586            1 : DSP_FUNC_SCOPE void zdsp_offset_q7(const DSP_DATA q7_t *src, q7_t offset, DSP_DATA q7_t *dst,
     587              :                                 uint32_t block_size);
     588              : 
     589              : /**
     590              :  * @brief  Adds a constant offset to a Q15 vector.
     591              :  *
     592              :  * @par Scaling and Overflow Behavior
     593              :  *   The function uses saturating arithmetic.
     594              :  *   Results outside of the allowable Q15 range [0x8000 0x7FFF] are saturated.
     595              :  *
     596              :  * @param[in]  src        points to the input vector
     597              :  * @param[in]  offset     is the offset to be added
     598              :  * @param[out] dst        points to the output vector
     599              :  * @param[in]  block_size number of samples in the vector
     600              :  */
     601            1 : DSP_FUNC_SCOPE void zdsp_offset_q15(const DSP_DATA q15_t *src, q15_t offset, DSP_DATA q15_t *dst,
     602              :                                 uint32_t block_size);
     603              : 
     604              : /**
     605              :  * @brief  Adds a constant offset to a Q31 vector.
     606              :  *
     607              :  * @par Scaling and Overflow Behavior
     608              :  *   The function uses saturating arithmetic.
     609              :  *   Results outside of the allowable Q31 range [0x80000000 0x7FFFFFFF] are saturated.
     610              :  *
     611              :  * @param[in]  src       points to the input vector
     612              :  * @param[in]  offset     is the offset to be added
     613              :  * @param[out] dst       points to the output vector
     614              :  * @param[in]  block_size  number of samples in the vector
     615              :  */
     616            1 : DSP_FUNC_SCOPE void zdsp_offset_q31(const DSP_DATA q31_t *src, q31_t offset, DSP_DATA q31_t *dst,
     617              :                                 uint32_t block_size);
     618              : 
     619              : /**
     620              :  * @}
     621              :  */
     622              : 
     623              : /**
     624              :  * @ingroup math_dsp_basic
     625              :  * @defgroup math_dsp_basic_negate Vector Negate
     626              :  *
     627              :  * Negates the elements of a vector.
     628              :  * <pre>
     629              :  *     dst[n] = -src[n],   0 <= n < block_size.
     630              :  * </pre>
     631              :  * The functions support in-place computation allowing the source and destination pointers to
     632              :  * reference the same memory buffer. There are separate functions for floating-point, Q7, Q15, and
     633              :  * Q31 data types.
     634              :  *
     635              :  * @{
     636              :  */
     637              : 
     638              : /**
     639              :  * @brief  Negates the elements of a floating-point vector.
     640              :  * @param[in]  src        points to the input vector
     641              :  * @param[out] dst        points to the output vector
     642              :  * @param[in]  block_size number of samples in the vector
     643              :  */
     644            1 : DSP_FUNC_SCOPE void zdsp_negate_f32(const DSP_DATA float32_t *src, DSP_DATA float32_t *dst,
     645              :                                 uint32_t block_size);
     646              : 
     647              : /**
     648              :  * @brief  Negates the elements of a Q7 vector.
     649              :  *
     650              :  * @par Scaling and Overflow Behavior
     651              :  *   The function uses saturating arithmetic.
     652              :  *   The Q7 value -1 (0x80) is saturated to the maximum allowable positive value 0x7F.
     653              :  *
     654              :  * @param[in]  src        points to the input vector
     655              :  * @param[out] dst        points to the output vector
     656              :  * @param[in]  block_size number of samples in the vector
     657              :  */
     658            1 : DSP_FUNC_SCOPE void zdsp_negate_q7(const DSP_DATA q7_t *src, DSP_DATA q7_t *dst,
     659              :                                 uint32_t block_size);
     660              : 
     661              : /**
     662              :  * @brief  Negates the elements of a Q15 vector.
     663              :  *
     664              :  * @par Scaling and Overflow Behavior
     665              :  *   The function uses saturating arithmetic.
     666              :  *   The Q15 value -1 (0x8000) is saturated to the maximum allowable positive value 0x7FFF.
     667              :  *
     668              :  * @param[in]  src        points to the input vector
     669              :  * @param[out] dst        points to the output vector
     670              :  * @param[in]  block_size number of samples in the vector
     671              :  */
     672            1 : DSP_FUNC_SCOPE void zdsp_negate_q15(const DSP_DATA q15_t *src, DSP_DATA q15_t *dst,
     673              :                                 uint32_t block_size);
     674              : 
     675              : /**
     676              :  * @brief  Negates the elements of a Q31 vector.
     677              :  *
     678              :  * @par Scaling and Overflow Behavior
     679              :  *   The function uses saturating arithmetic.
     680              :  *   The Q31 value -1 (0x80000000) is saturated to the maximum allowable positive value 0x7FFFFFFF.
     681              :  *
     682              :  * @param[in]  src        points to the input vector
     683              :  * @param[out] dst        points to the output vector
     684              :  * @param[in]  block_size number of samples in the vector
     685              :  */
     686            1 : DSP_FUNC_SCOPE void zdsp_negate_q31(const DSP_DATA q31_t *src, DSP_DATA q31_t *dst,
     687              :                                 uint32_t block_size);
     688              : 
     689              : /**
     690              :  * @}
     691              :  */
     692              : 
     693              : /**
     694              :  * @ingroup math_dsp_basic
     695              :  * @defgroup math_dsp_basic_and Vector bitwise AND
     696              :  *
     697              :  * Compute the logical bitwise AND.
     698              :  *
     699              :  * There are separate functions for uint32_t, uint16_t, and uint7_t data types.
     700              :  * @{
     701              :  */
     702              : 
     703              : /**
     704              :  * @brief         Compute the logical bitwise AND of two fixed-point vectors.
     705              :  * @param[in]     src_a      points to input vector A
     706              :  * @param[in]     src_b      points to input vector B
     707              :  * @param[out]    dst        points to output vector
     708              :  * @param[in]     block_size number of samples in each vector
     709              :  */
     710            1 : DSP_FUNC_SCOPE void zdsp_and_u8(const DSP_DATA uint8_t *src_a, const DSP_DATA uint8_t *src_b,
     711              :                                 DSP_DATA uint8_t *dst, uint32_t block_size);
     712              : 
     713              : /**
     714              :  * @brief         Compute the logical bitwise AND of two fixed-point vectors.
     715              :  * @param[in]     src_a      points to input vector A
     716              :  * @param[in]     src_b      points to input vector B
     717              :  * @param[out]    dst        points to output vector
     718              :  * @param[in]     block_size number of samples in each vector
     719              :  */
     720            1 : DSP_FUNC_SCOPE void zdsp_and_u16(const DSP_DATA uint16_t *src_a, const DSP_DATA uint16_t *src_b,
     721              :                                 DSP_DATA uint16_t *dst, uint32_t block_size);
     722              : 
     723              : /**
     724              :  * @brief         Compute the logical bitwise AND of two fixed-point vectors.
     725              :  * @param[in]     src_a      points to input vector A
     726              :  * @param[in]     src_b      points to input vector B
     727              :  * @param[out]    dst        points to output vector
     728              :  * @param[in]     block_size number of samples in each vector
     729              :  */
     730            1 : DSP_FUNC_SCOPE void zdsp_and_u32(const DSP_DATA uint32_t *src_a, const DSP_DATA uint32_t *src_b,
     731              :                                 DSP_DATA uint32_t *dst, uint32_t block_size);
     732              : 
     733              : /**
     734              :  * @}
     735              :  */
     736              : 
     737              : /**
     738              :  * @ingroup math_dsp_basic
     739              :  * @defgroup math_dsp_basic_or Vector bitwise OR
     740              :  *
     741              :  * Compute the logical bitwise OR.
     742              :  *
     743              :  * There are separate functions for uint32_t, uint16_t, and uint7_t data types.
     744              :  * @{
     745              :  */
     746              : 
     747              : /**
     748              :  * @brief         Compute the logical bitwise OR of two fixed-point vectors.
     749              :  * @param[in]     src_a      points to input vector A
     750              :  * @param[in]     src_b      points to input vector B
     751              :  * @param[out]    dst        points to output vector
     752              :  * @param[in]     block_size number of samples in each vector
     753              :  */
     754            1 : DSP_FUNC_SCOPE void zdsp_or_u8(const DSP_DATA uint8_t *src_a, const DSP_DATA uint8_t *src_b,
     755              :                                 DSP_DATA uint8_t *dst, uint32_t block_size);
     756              : 
     757              : /**
     758              :  * @brief         Compute the logical bitwise OR of two fixed-point vectors.
     759              :  * @param[in]     src_a      points to input vector A
     760              :  * @param[in]     src_b      points to input vector B
     761              :  * @param[out]    dst        points to output vector
     762              :  * @param[in]     block_size number of samples in each vector
     763              :  */
     764            1 : DSP_FUNC_SCOPE void zdsp_or_u16(const DSP_DATA uint16_t *src_a, const DSP_DATA uint16_t *src_b,
     765              :                                 DSP_DATA uint16_t *dst, uint32_t block_size);
     766              : 
     767              : /**
     768              :  * @brief         Compute the logical bitwise OR of two fixed-point vectors.
     769              :  * @param[in]     src_a      points to input vector A
     770              :  * @param[in]     src_b      points to input vector B
     771              :  * @param[out]    dst        points to output vector
     772              :  * @param[in]     block_size number of samples in each vector
     773              :  */
     774            1 : DSP_FUNC_SCOPE void zdsp_or_u32(const DSP_DATA uint32_t *src_a, const DSP_DATA uint32_t *src_b,
     775              :                                 DSP_DATA uint32_t *dst, uint32_t block_size);
     776              : 
     777              : /**
     778              :  * @}
     779              :  */
     780              : 
     781              : /**
     782              :  * @ingroup math_dsp_basic
     783              :  * @defgroup math_dsp_basic_not Vector bitwise NOT
     784              :  *
     785              :  * Compute the logical bitwise NOT.
     786              :  *
     787              :  * There are separate functions for uint32_t, uint16_t, and uint7_t data types.
     788              :  * @{
     789              :  */
     790              : 
     791              : /**
     792              :  * @brief         Compute the logical bitwise NOT of a fixed-point vector.
     793              :  * @param[in]     src        points to input vector
     794              :  * @param[out]    dst        points to output vector
     795              :  * @param[in]     block_size number of samples in each vector
     796              :  */
     797            1 : DSP_FUNC_SCOPE void zdsp_not_u8(const DSP_DATA uint8_t *src, DSP_DATA uint8_t *dst,
     798              :                                 uint32_t block_size);
     799              : 
     800              : /**
     801              :  * @brief         Compute the logical bitwise NOT of a fixed-point vector.
     802              :  * @param[in]     src        points to input vector
     803              :  * @param[out]    dst        points to output vector
     804              :  * @param[in]     block_size number of samples in each vector
     805              :  */
     806            1 : DSP_FUNC_SCOPE void zdsp_not_u16(const DSP_DATA uint16_t *src, DSP_DATA uint16_t *dst,
     807              :                                 uint32_t block_size);
     808              : 
     809              : /**
     810              :  * @brief         Compute the logical bitwise NOT of a fixed-point vector.
     811              :  * @param[in]     src        points to input vector
     812              :  * @param[out]    dst        points to output vector
     813              :  * @param[in]     block_size number of samples in each vector
     814              :  */
     815            1 : DSP_FUNC_SCOPE void zdsp_not_u32(const DSP_DATA uint32_t *src, DSP_DATA uint32_t *dst,
     816              :                                 uint32_t block_size);
     817              : 
     818              : /**
     819              :  * @}
     820              :  */
     821              : 
     822              : /**
     823              :  * @ingroup math_dsp_basic
     824              :  * @defgroup math_dsp_basic_xor Vector bitwise XOR
     825              :  *
     826              :  * Compute the logical bitwise XOR.
     827              :  *
     828              :  * There are separate functions for uint32_t, uint16_t, and uint7_t data types.
     829              :  * @{
     830              :  */
     831              : 
     832              : /**
     833              :  * @brief         Compute the logical bitwise XOR of two fixed-point vectors.
     834              :  * @param[in]     src_a      points to input vector A
     835              :  * @param[in]     src_b      points to input vector B
     836              :  * @param[out]    dst        points to output vector
     837              :  * @param[in]     block_size number of samples in each vector
     838              :  */
     839            1 : DSP_FUNC_SCOPE void zdsp_xor_u8(const DSP_DATA uint8_t *src_a, const DSP_DATA uint8_t *src_b,
     840              :                                 DSP_DATA uint8_t *dst, uint32_t block_size);
     841              : 
     842              : /**
     843              :  * @brief         Compute the logical bitwise XOR of two fixed-point vectors.
     844              :  * @param[in]     src_a      points to input vector A
     845              :  * @param[in]     src_b      points to input vector B
     846              :  * @param[out]    dst        points to output vector
     847              :  * @param[in]     block_size number of samples in each vector
     848              :  */
     849            1 : DSP_FUNC_SCOPE void zdsp_xor_u16(const DSP_DATA uint16_t *src_a, const DSP_DATA uint16_t *src_b,
     850              :                                 DSP_DATA uint16_t *dst, uint32_t block_size);
     851              : 
     852              : /**
     853              :  * @brief         Compute the logical bitwise XOR of two fixed-point vectors.
     854              :  * @param[in]     src_a      points to input vector A
     855              :  * @param[in]     src_b      points to input vector B
     856              :  * @param[out]    dst        points to output vector
     857              :  * @param[in]     block_size number of samples in each vector
     858              :  */
     859            1 : DSP_FUNC_SCOPE void zdsp_xor_u32(const DSP_DATA uint32_t *src_a, const DSP_DATA uint32_t *src_b,
     860              :                                 DSP_DATA uint32_t *dst, uint32_t block_size);
     861              : 
     862              : /**
     863              :  * @}
     864              :  */
     865              : 
     866              : /**
     867              :  * @ingroup math_dsp_basic
     868              :  * @defgroup math_dsp_basic_clip Vector Clipping
     869              :  *
     870              :  * Element-by-element clipping of a value.
     871              :  *
     872              :  * The value is constrained between 2 bounds.
     873              :  *
     874              :  * There are separate functions for floating-point, Q7, Q15, and Q31 data types.
     875              :  * @{
     876              :  */
     877              : 
     878              : /**
     879              :  * @brief         Elementwise floating-point clipping
     880              :  * @param[in]     src          points to input values
     881              :  * @param[out]    dst          points to output clipped values
     882              :  * @param[in]     low          lower bound
     883              :  * @param[in]     high         higher bound
     884              :  * @param[in]     num_samples  number of samples to clip
     885              :  */
     886            1 : DSP_FUNC_SCOPE void zdsp_clip_f32(const DSP_DATA float32_t *src, DSP_DATA float32_t *dst,
     887              :                                 float32_t low, float32_t high, uint32_t num_samples);
     888              : 
     889              : /**
     890              :  * @brief         Elementwise fixed-point clipping
     891              :  * @param[in]     src          points to input values
     892              :  * @param[out]    dst          points to output clipped values
     893              :  * @param[in]     low          lower bound
     894              :  * @param[in]     high         higher bound
     895              :  * @param[in]     num_samples  number of samples to clip
     896              :  */
     897            1 : DSP_FUNC_SCOPE void zdsp_clip_q31(const DSP_DATA q31_t *src, DSP_DATA q31_t *dst, q31_t low,
     898              :                                 q31_t high, uint32_t num_samples);
     899              : 
     900              : /**
     901              :  * @brief         Elementwise fixed-point clipping
     902              :  * @param[in]     src          points to input values
     903              :  * @param[out]    dst          points to output clipped values
     904              :  * @param[in]     low          lower bound
     905              :  * @param[in]     high         higher bound
     906              :  * @param[in]     num_samples  number of samples to clip
     907              :  */
     908            1 : DSP_FUNC_SCOPE void zdsp_clip_q15(const DSP_DATA q15_t *src, DSP_DATA q15_t *dst, q15_t low,
     909              :                                 q15_t high, uint32_t num_samples);
     910              : 
     911              : /**
     912              :  * @brief         Elementwise fixed-point clipping
     913              :  * @param[in]     src          points to input values
     914              :  * @param[out]    dst          points to output clipped values
     915              :  * @param[in]     low          lower bound
     916              :  * @param[in]     high         higher bound
     917              :  * @param[in]     num_samples  number of samples to clip
     918              :  */
     919            1 : DSP_FUNC_SCOPE void zdsp_clip_q7(const DSP_DATA q7_t *src, DSP_DATA q7_t *dst, q7_t low, q7_t high,
     920              :                                 uint32_t num_samples);
     921              : 
     922              : /**
     923              :  * @}
     924              :  */
     925              : 
     926              : /**
     927              :  * @}
     928              :  */
     929              : 
     930              : #ifdef __cplusplus
     931              : }
     932              : #endif
     933              : 
     934              : #ifdef CONFIG_FP16
     935              : #include <zephyr/dsp/basicmath_f16.h>
     936              : #endif /* CONFIG_FP16 */
     937              : 
     938              : #endif /* ZEPHYR_INCLUDE_DSP_BASICMATH_H_ */
        

Generated by: LCOV version 2.0-1