tool/mbed/mbed-sdk/libraries/dsp/cmsis_dsp/FilteringFunctions/arm_fir_init_q15.c

   1 /* ----------------------------------------------------------------------
   2 * Copyright (C) 2010-2013 ARM Limited. All rights reserved.
   3 *
   4 * $Date:        17. January 2013
   5 * $Revision:    V1.4.1
   6 *
   7 * Project:          CMSIS DSP Library
   8 * Title:        arm_fir_init_q15.c
   9 *
  10 * Description:  Q15 FIR filter initialization function.
  11 *
  12 * Target Processor: Cortex-M4/Cortex-M3/Cortex-M0
  13 *
  14 * Redistribution and use in source and binary forms, with or without
  15 * modification, are permitted provided that the following conditions
  16 * are met:
  17 *   - Redistributions of source code must retain the above copyright
  18 *     notice, this list of conditions and the following disclaimer.
  19 *   - Redistributions in binary form must reproduce the above copyright
  20 *     notice, this list of conditions and the following disclaimer in
  21 *     the documentation and/or other materials provided with the
  22 *     distribution.
  23 *   - Neither the name of ARM LIMITED nor the names of its contributors
  24 *     may be used to endorse or promote products derived from this
  25 *     software without specific prior written permission.
  26 *
  27 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  28 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  29 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  30 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  31 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  32 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  33 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  34 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  35 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  36 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
  37 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  38 * POSSIBILITY OF SUCH DAMAGE.
  39 * ------------------------------------------------------------------- */
  40
  41 #include "arm_math.h"
  42
  43 /**
  44  * @ingroup groupFilters
  45  */
  46
  47 /**
  48  * @addtogroup FIR
  49  * @{
  50  */
  51
  52 /**
  53  * @param[in,out]  *S points to an instance of the Q15 FIR filter structure.
  54  * @param[in]      numTaps  Number of filter coefficients in the filter. Must be even and greater than or equal to 4.
  55  * @param[in]      *pCoeffs points to the filter coefficients buffer.
  56  * @param[in]      *pState points to the state buffer.
  57  * @param[in]      blockSize is number of samples processed per call.
  58  * @return The function returns ARM_MATH_SUCCESS if initialization is successful or ARM_MATH_ARGUMENT_ERROR if
  59  * <code>numTaps</code> is not greater than or equal to 4 and even.
  60  *
  61  * <b>Description:</b>
  62  * \par
  63  * <code>pCoeffs</code> points to the array of filter coefficients stored in time reversed order:
  64  * <pre>
  65  *    {b[numTaps-1], b[numTaps-2], b[N-2], ..., b[1], b[0]}
  66  * </pre>
  67  * Note that <code>numTaps</code> must be even and greater than or equal to 4.
  68  * To implement an odd length filter simply increase <code>numTaps</code> by 1 and set the last coefficient to zero.
  69  * For example, to implement a filter with <code>numTaps=3</code> and coefficients
  70  * <pre>
  71  *     {0.3, -0.8, 0.3}
  72  * </pre>
  73  * set <code>numTaps=4</code> and use the coefficients:
  74  * <pre>
  75  *     {0.3, -0.8, 0.3, 0}.
  76  * </pre>
  77  * Similarly, to implement a two point filter
  78  * <pre>
  79  *     {0.3, -0.3}
  80  * </pre>
  81  * set <code>numTaps=4</code> and use the coefficients:
  82  * <pre>
  83  *     {0.3, -0.3, 0, 0}.
  84  * </pre>
  85  * \par
  86  * <code>pState</code> points to the array of state variables.
  87  * <code>pState</code> is of length <code>numTaps+blockSize</code>, when running on Cortex-M4 and Cortex-M3  and is of length <code>numTaps+blockSize-1</code>, when running on Cortex-M0 where <code>blockSize</code> is the number of input samples processed by each call to <code>arm_fir_q15()</code>.
  88  */
  89
  90 arm_status arm_fir_init_q15(
  91   arm_fir_instance_q15 * S,
  92   uint16_t numTaps,
  93   q15_t * pCoeffs,
  94   q15_t * pState,
  95   uint32_t blockSize)
  96 {
  97   arm_status status;
  98
  99
 100 #ifndef ARM_MATH_CM0_FAMILY
 101
 102   /* Run the below code for Cortex-M4 and Cortex-M3 */
 103
 104   /* The Number of filter coefficients in the filter must be even and at least 4 */
 105   if(numTaps & 0x1u)
 106   {
 107     status = ARM_MATH_ARGUMENT_ERROR;
 108   }
 109   else
 110   {
 111     /* Assign filter taps */
 112     S->numTaps = numTaps;
 113
 114     /* Assign coefficient pointer */
 115     S->pCoeffs = pCoeffs;
 116
 117     /* Clear the state buffer.  The size is always (blockSize + numTaps ) */
 118     memset(pState, 0, (numTaps + (blockSize)) * sizeof(q15_t));
 119
 120     /* Assign state pointer */
 121     S->pState = pState;
 122
 123     status = ARM_MATH_SUCCESS;
 124   }
 125
 126   return (status);
 127
 128 #else
 129
 130   /* Run the below code for Cortex-M0 */
 131
 132   /* Assign filter taps */
 133   S->numTaps = numTaps;
 134
 135   /* Assign coefficient pointer */
 136   S->pCoeffs = pCoeffs;
 137
 138   /* Clear the state buffer.  The size is always (blockSize + numTaps - 1) */
 139   memset(pState, 0, (numTaps + (blockSize - 1u)) * sizeof(q15_t));
 140
 141   /* Assign state pointer */
 142   S->pState = pState;
 143
 144   status = ARM_MATH_SUCCESS;
 145
 146   return (status);
 147
 148 #endif /*  #ifndef ARM_MATH_CM0_FAMILY */
 149
 150 }
 151
 152 /**
 153  * @} end of FIR group
 154  */