1 /******************************************************************************\r
2 * FILE PURPOSE:header file of HLC (high-level compensation)\r
3 ******************************************************************************\r
4 * FILE NAME: hlc.h\r
5 *\r
6 * DESCRIPTION: Contains external definitions&functions prototypes for HLC\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 _HLC_H\r
71 #define _HLC_H\r
72 \r
73 /**\r
74 * @file hlc.h\r
75 * @brief Contains external APIs for the HLC 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 HLC High Level Compensation (HLC) \r
84 *\r
85 * @brief HLC is designed to attenuate the incoming signal when the signal level \r
86 * exceeds certain pre-configured threshold to avoid possible distortion \r
87 * due to future flat-top saturation. HLC is a frame-based operation and \r
88 * there's a requirement of minimum 5ms frame size, after HLC parameters \r
89 * are properly configured the signal level will be measured and compared \r
90 * with the threshold, then an attenuation will be calculated and applied \r
91 * to the signal.\r
92 *\r
93 * Application of attenuation to the signal should not be instantaneous. \r
94 * Rather HLC should gradually ramp in and eventually apply the complete \r
95 * attenuation. The ramping in time constant is relatively low to ensure \r
96 * fast action so that the signal level can be reduced before saturation \r
97 * actually occurs. It is fixed to 10ms/dB for now. Ramping in should be \r
98 * triggered only when the power exceeds thresh. During this period, \r
99 * attenuation could increase or stay constant, based on the changes in \r
100 * signal power.\r
101 *\r
102 * In the case the signal level goes below thresh, HLC attenuation should \r
103 * disengage, although slowly, so as not to cause sudden changes in the \r
104 * signal level heard by the listener, especially during short pauses in \r
105 * speech. The ramping out time constant is configurable between 10ms to \r
106 * 1000ms per dB reduction in attenuation, specified in 10ms steps. Ramping \r
107 * out should be triggered only for powers below thresh. During this period, \r
108 * attenuation should gradually reduce based on the setting of the ramp-out \r
109 * time period. \r
110 *\r
111 */\r
112 \r
113 /** @ingroup HLC */\r
114 /* @{ */\r
115 \r
116 /** @defgroup hlc_api_return_codes HLC API return codes\r
117 * These are the return codes for the HLC module API functions.\r
118 * \r
119 * @{\r
120 * @name HLC Function Return Value Definitions\r
121 *\r
122 */\r
123 /* @{ */\r
124 enum {\r
125 hlc_NOERR = 0, /**< Returned from function without error */\r
126 hlc_ERROR = 1, /**< Returned from function with error */ \r
127 hlc_BADPARAM = 2 /**< Returned from function with wrong parameters */ \r
128 };\r
129 /* @} */\r
130 /** @} */\r
131 \r
132 \r
133 /**\r
134 * @name HLC sampling rate factor\r
135 * \remark These numbers are used as multipliers, so can't be changed to other values.\r
136 */\r
137 enum {\r
138 hlc_SRATE_FACTOR_8K = 1, /**< sampling rate is 8kHz */\r
139 hlc_SRATE_FACTOR_16K = 2 /**< sampling rate is 16kHz */\r
140 }; \r
141 \r
142 \r
143 /**\r
144 * @name HLC configure bit fields\r
145 * \r
146 */\r
147 enum {\r
148 hlc_CFG_BIT_THRESH = 0, /**< Bit 0 for threshold */\r
149 hlc_CFG_BIT_RAMP_OUT = 1, /**< Bit 1 for ramp out period */\r
150 hlc_CFG_BIT_POWER_TC = 2, /**< Bit 2 for power calculation constant */\r
151 hlc_CFG_BIT_FRM_LEN = 3, /**< Bit 3 for frame length */\r
152 hlc_CFG_BIT_SRATE_FACT = 4 /**< Bit 4 for sampling rate factor */\r
153 };\r
154 \r
155 /**\r
156 * @name HLC state\r
157 * \r
158 */\r
159 enum {\r
160 hlc_DISABLED = 0, /**< HLC is disabled */\r
161 hlc_ENABLED = 1 /**< HLC is enabled */\r
162 };\r
163 \r
164 /**\r
165 * @name HLC power calculation constant \r
166 *\r
167 */\r
168 enum {\r
169 hlc_TC_PWR_4_MS = 1, /**< 4 msec time constant */\r
170 hlc_TC_PWR_8_MS = 2, /**< 8 msec time constant */\r
171 hlc_TC_PWR_16_MS = 3 /**< 16 msec time constant */\r
172 };\r
173 \r
174 /** \r
175 * \brief HLC configure Structure\r
176 * \r
177 * Contains parameters that can be chosen to be configured by user or using \r
178 * the default when initializing HLC\r
179 *\r
180 */\r
181 typedef struct{\r
182 tuint valid_bf; /**< Bit-fields indicating which parameters to configure \n\r
183 \link HLC::hlc_CFG_BIT_THRESH bitfield definitions \endlink */\r
184 Fract thresh; /**< Threshold (0.5 dBm0 units) in S14.1 format \n\r
185 valid range: -96 ~ +6 corresponding to -48~+3 dBm0 \n\r
186 default: 0 dBm0*/\r
187 tint ramp_out_period; /**< Ramping out period in ms/dB \n\r
188 valid range: 10~1000ms/dB, default 700ms/dB*/ \r
189 tint power_tc; /**< Power measurement time constant \r
190 valid numbers: \n\r
191 \link HLC::hlc_TC_PWR_4_MS hlc_TC_PWR_4_MS \endlink \n\r
192 \link HLC::hlc_TC_PWR_8_MS hlc_TC_PWR_8_MS \endlink \n\r
193 \link HLC::hlc_TC_PWR_16_MS hlc_TC_PWR_16_MS \endlink \r
194 */\r
195 tint srate_factor; /**< Sampling rate factor: \n\r
196 \link HLC::hlc_SRATE_FACTOR_8K hlc_SRATE_FACTOR_8K \endlink \n\r
197 \link HLC::hlc_SRATE_FACTOR_16K hlc_SRATE_FACTOR_16K \endlink \n \r
198 */\r
199 tint frm_len; /**< Input signal frame length in samples, must be multiple of 5ms */\r
200 } hlcConfig_t;\r
201 \r
202 /**\r
203 * @name HLC control code\r
204 * \r
205 */\r
206 enum {\r
207 hlc_CTL_DIS = 0, /**< Disable HLC */\r
208 hlc_CTL_ENA = 1, /**< Enable HLC */\r
209 hlc_CTL_THR = 2 /**< Set \link hlcConfig_t::thresh thresh\endlink in hlcConfig_t */\r
210 };\r
211 \r
212 \r
213 /** \r
214 * \brief HLC Control Structure.\r
215 * Contains control commands to change HLC parameters without \r
216 * resetting other parameters\r
217 *\r
218 */\r
219 typedef struct{\r
220 tint ctl_code; /**< Set to one of hlc_CTL_XXX control codes, \n\r
221 \link HLC::hlc_CTL_DIS Control Code \endlink */\r
222 union {\r
223 Fract thresh; /**< If ctl_code is \link HLC::hlc_CTL_THR hlc_CTL_THR \endlink, \r
224 set the \link hlcConfig_t::thresh thresh\endlink in the HLC instance */\r
225 } u;\r
226 } hlcControl_t;\r
227 \r
228 /**\r
229 * @name External APIs for HLC\r
230 *\r
231 */\r
232 /* @{ */\r
233 /**\r
234 * @brief To get the size of a HLC instance structure\r
235 * \r
236 * \remark Function hlcGetSizes() is the first function to be called. \r
237 * \r
238 *\r
239 * @param[in, out] instsize Pointer to the size of a HLC instance.\r
240 * \r
241 * @return \link HLC::hlc_NOERR hlc_NOERR, \endlink \n\r
242 * \link HLC::hlc_ERROR hlc_ERROR, \endlink \n\r
243 * \link HLC::hlc_BADPARAM hlc_BADPARAM \endlink \r
244 */ \r
245 tint hlcGetSizes (tint *instsize); \r
246 \r
247 /**\r
248 * @brief Init HLC according to the user configurations.\r
249 * \r
250 * \remark Function hlcInit() needs be called after hlcGetSizes(). After\r
251 * this function call, HLC is disabled. \r
252 * \r
253 *\r
254 * @param[in, out] inst Pointer to a HLC instance structure.\r
255 * @param[in] hlcCfg_info Pointer to a configuration structure hlcConfig_t.\r
256 * \r
257 * @return \link HLC::hlc_NOERR hlc_NOERR, \endlink \n\r
258 * \link HLC::hlc_ERROR hlc_ERROR, \endlink \n\r
259 * \link HLC::hlc_BADPARAM hlc_BADPARAM \endlink \r
260 * \r
261 */\r
262 tint hlcInit(void *inst, hlcConfig_t *hlcCfg_info);\r
263 \r
264 /**\r
265 * @brief Change parameters on the fly without re-initialzing all HLC parameters\r
266 * \r
267 * \remark Function hlcControl() must be called after hlcInit() to enable HLC. Also\r
268 * it can be called anytime to reconfigure \link hlcConfig_t::thresh thresh\endlink \r
269 * in the HLC instance. \r
270 * \r
271 *\r
272 * @param[in, out] hlcInst Pointer to a HLC instance.\r
273 * @param[in] hlc_ctrl Pointer to a control structure hlcControl_t.\r
274 * \r
275 * @return \link HLC::hlc_NOERR hlc_NOERR, \endlink \n\r
276 * \link HLC::hlc_ERROR hlc_ERROR \endlink \r
277 * \r
278 */\r
279 tint hlcControl(void *hlcInst, hlcControl_t *hlc_ctrl);\r
280 \r
281 /**\r
282 * @brief Calculate and apply attenuation when HLC is enabled\r
283 *\r
284 * \remark This function is the function that processes the voice\r
285 * samples and needs to be called every frame.\r
286 *\r
287 * @param[in] hlcInst Pointer to a HLC instance.\r
288 * @param[in, out] samples Pointer to the input/output signal buffer\r
289 * \r
290 * @return \link HLC::hlc_NOERR hlc_NOERR, \endlink \n\r
291 * \link HLC::hlc_ERROR hlc_ERROR \endlink \r
292 */\r
293 tint hlcProcess (void *hlcInst, void *samples);\r
294 \r
295 /* @} */\r
296 /* @} */ /* ingroup HLC */\r
297 #endif\r
298 \r
299 /* end of hlc.h */\r
300 \r