1 /******************************************************************************\r
2 * FILE PURPOSE:header file of SLM (signal limiter)\r
3 ******************************************************************************\r
4 * FILE NAME: slm.h\r
5 *\r
6 * DESCRIPTION: Contains external definitions&functions prototypes for SLIM\r
7 *\r
8 * Copyright (c) 2007 \96 2013 Texas Instruments Incorporated
9 *
10 * All rights reserved not granted herein.
11 *
12 * Limited License.
13 *
14 * Texas Instruments Incorporated grants a world-wide, royalty-free,
15 * non-exclusive license under copyrights and patents it now or hereafter owns
16 * or controls to make, have made, use, import, offer to sell and sell
17 * ("Utilize") this software subject to the terms herein. With respect to the
18 * foregoing patent license, such license is granted solely to the extent that
19 * any such patent is necessary to Utilize the software alone. The patent
20 * license shall not apply to any combinations which include this software,
21 * other than combinations with devices manufactured by or for TI (\93TI
22 * Devices\94). No hardware patent is licensed hereunder.
23 *
24 * Redistributions must preserve existing copyright notices and reproduce this
25 * license (including the above copyright notice and the disclaimer and (if
26 * applicable) source code license limitations below) in the documentation
27 * and/or other materials provided with the distribution
28 *
29 * Redistribution and use in binary form, without modification, are permitted
30 * provided that the following conditions are met:
31 *
32 * * No reverse engineering, decompilation, or disassembly of this software
33 * is permitted with respect to any software provided in binary form.
34 *
35 * * any redistribution and use are licensed by TI for use only with TI
36 * Devices.
37 *
38 * * Nothing shall obligate TI to provide you with source code for the
39 * software licensed and provided to you in object code.
40 *
41 * If software source code is provided to you, modification and redistribution
42 * of the source code are permitted provided that the following conditions are
43 * met:
44 *
45 * * any redistribution and use of the source code, including any resulting
46 * derivative works, are licensed by TI for use only with TI Devices.
47 *
48 * * any redistribution and use of any object code compiled from the source
49 * code and any resulting derivative works, are licensed by TI for use only
50 * with TI Devices.
51 *
52 * Neither the name of Texas Instruments Incorporated nor the names of its
53 * suppliers may be used to endorse or promote products derived from this
54 * software without specific prior written permission.
55 *
56 * DISCLAIMER.
57 *
58 * THIS SOFTWARE IS PROVIDED BY TI AND TI\92S LICENSORS "AS IS" AND ANY EXPRESS
59 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
60 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
61 * DISCLAIMED. IN NO EVENT SHALL TI AND TI\92S LICENSORS BE LIABLE FOR ANY
62 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
63 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
64 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
65 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
66 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
67 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
68 * DAMAGE. \r
69 *****************************************************************************/\r
70 #ifndef _SLM_H\r
71 #define _SLM_H\r
72 \r
73 /**\r
74 * @file slm.h\r
75 * @brief Contains external APIs for the slm module.\r
76 *\r
77 */\r
78 \r
79 /* System level header files */\r
80 #include <ti/mas/types/types.h> /* DSP types */\r
81 \r
82 /** \r
83 * @defgroup SLM Signal Limiter(SLM)\r
84 * \r
85 * @brief When a voice signal is saturated, the resulting signal is generally nonlinear \r
86 * in nature due to the (non-linear) saturation process. The Signal Limiter \r
87 * reduces the voice signal to prevent the undesirable effects of hard limiting.\r
88 */\r
89 /** @ingroup SLM */\r
90 /* @{ */\r
91 \r
92 /**\r
93 * @name SLM Mode Definitions\r
94 * \r
95 */\r
96 enum {\r
97 slm_DISABLE = 0, /**< Disable signal limiter */\r
98 slm_MODE1 = 1, /**< Signal limiter mode 1: Max -10.38 dBm0, Min -17.25 dBm0 */\r
99 slm_MODE2 = 2, /**< Signal limiter mode 2: Max -8.25 dBm0, Min -15.34 dBm0 */ \r
100 slm_MODE3 = 3, /**< Signal limiter mode 3: Max -6.44 dBm0, Min -13.43 dBm0 */\r
101 slm_MODE4 = 4, /**< Signal limiter mode 4: Max -4.28 dBm0, Min -11.41 dBm0 */\r
102 slm_MODE5 = 5, /**< Signal limiter mode 5: Max -2.17 dBm0, Min -9.18 dBm0 */ \r
103 slm_NUMOF_MODE = slm_MODE5 /**< Number of different SLM */ \r
104 };\r
105 \r
106 /** @defgroup slm_api_return_codes SLM API return codes\r
107 * These are the return codes for the SLM module API functions.\r
108 * \r
109 * @{\r
110 * @name SLM Function Return Value Definitions\r
111 *\r
112 */\r
113 /* @{ */\r
114 enum {\r
115 slm_NOERR = 0, /**< Functions returned without error */\r
116 slm_ERROR = 1, /**< Functions returned with error, such as NULL point */\r
117 slm_BADPARAM = 2 /**< Functions returned with bad parameters */ \r
118 };\r
119 /* @} */\r
120 /** @} */\r
121 \r
122 /**\r
123 * @name SLM sampling rate factor\r
124 * \remark These numbers are used as table indeces, so can't be changed.\r
125 */\r
126 enum {\r
127 slm_SRATE_FACTOR_16K = 1, /**< sampling rate is 16kHz */\r
128 slm_SRATE_FACTOR_8K = 2 /**< sampling rate is 8kHz */\r
129 }; \r
130 \r
131 /**\r
132 * @name SLM Configuration Structure Valid Bit-field\r
133 * \r
134 */\r
135 enum {\r
136 slm_CFG_BIT_SRATE = 0 /**< Bit 0: sampling rate factor */\r
137 };\r
138 \r
139 /** \r
140 * \brief SLM configure Structure\r
141 * \r
142 * Contains parameters that can be chosen to be configured by user when initializing SLM\r
143 *\r
144 */\r
145 /* @{ */\r
146 typedef struct{\r
147 tuint valid_bf; /**< Bit-fields indicating which parameters to configure \n\r
148 \link SLM::slm_CFG_BIT_SRATE bitfield definition \endlink */\r
149 tint srate_factor; /**< Sampling rate factor:\n\r
150 \link SLM::slm_SRATE_FACTOR_8K slm_SRATE_FACTOR_8K \endlink \n \r
151 \link SLM::slm_SRATE_FACTOR_16K slm_SRATE_FACTOR_16K \endlink */\r
152 } slmConfig_t;\r
153 /* @} */\r
154 \r
155 /**\r
156 * @name External APIs for SLM \r
157 *\r
158 */\r
159 /* @{ */\r
160 /**\r
161 * @brief Function slmGetSizes() get the size of a SLM instance \r
162 * \r
163 * \remark Function slmGetSizes() is the first function to be called. \r
164 *\r
165 * @param[in, out] instsize Pointer to the size of a SLM instance .\r
166 *\r
167 * @return \link SLM::slm_NOERR slm_NOERR, \endlink \n\r
168 * \link SLM::slm_ERROR slm_ERROR \endlink \r
169 */\r
170 tint slmGetSizes (tint *instsize);\r
171 \r
172 /**\r
173 * @brief Function slmInit() initializes SLM \r
174 * \r
175 * \remark Function slmInit() must be called after slmGetSizes(). After the\r
176 * function call, SLM is disabled. \r
177 * \r
178 *\r
179 * @param[in, out] inst Pointer to a SLM instance structure\r
180 * @param[in] cfg Pointer to a configuration structure slmConfig_t\r
181 *\r
182 * @return \link SLM::slm_NOERR slm_NOERR, \endlink \n\r
183 * \link SLM::slm_ERROR slm_ERROR, \endlink \n\r
184 * \link SLM::slm_BADPARAM slm_BADPARAM \endlink \r
185 * \r
186 */ \r
187 tint slmInit (void *inst, slmConfig_t *cfg);\r
188 \r
189 /**\r
190 * @brief Function slmControl() configure SLM with different types of limiter\r
191 * \r
192 * \remark Function slmControl() must be called after slmInit() to enable SLM by\r
193 * setting the mode to one of the operational modes.\r
194 * All internal parameters will be reset whenever there's a mode change \r
195 * \r
196 *\r
197 * @param[in, out] inst Pointer to a SLM instance structure.\r
198 * @param[in] mode one of \link SLM::slm_DISABLE slm modes \endlink.\r
199 *\r
200 * @return \link SLM::slm_NOERR slm_NOERR, \endlink \n\r
201 * \link SLM::slm_ERROR slm_ERROR, \endlink \n\r
202 * \link SLM::slm_BADPARAM slm_BADPARAM \endlink \r
203 */\r
204 tint slmControl (void *inst, tint mode);\r
205 \r
206 /**\r
207 * @brief This is the function that performs the signal attenuation\r
208 * \r
209 * \remark This function can only be called after slmInit() and slmControl()\r
210 * to make SLM take effect and it needs to be called every frame. \r
211 * \r
212 *\r
213 * @param[in] inst Pointer to a SLM instance structure.\r
214 * @param[in, out] speechSamples Pointer to the voice buffer\r
215 * @param[in] frame_length Number of samples processed\r
216 *\r
217 * @return \link SLM::slm_NOERR slm_NOERR \endlink\r
218 *\r
219 */\r
220 tint slmProcess (void *inst, void *speechSamples, tint frame_length);\r
221 \r
222 /* @} */\r
223 /* @} */ /* ingroup SLM */\r
224 #endif\r
225 \r
226 /* end of slm.h */\r
227 \r