1
2 /*
3 * SpanDSP - a series of DSP components for telephony
4 *
5 * bit_operations.h - Various bit level operations, such as bit reversal
6 *
7 * Written by Steve Underwood <steveu@coppice.org>
8 *
9 * Copyright (C) 2006 Steve Underwood
10 *
11 * All rights reserved.
12 *
13 * This program is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License version 2, as
15 * published by the Free Software Foundation.
16 *
17 * This program is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU General Public License for more details.
21 *
22 * You should have received a copy of the GNU General Public License
23 * along with this program; if not, write to the Free Software
24 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
25 *
26 * $Id: bit_operations.h,v 1.15 2007/02/23 13:16:13 steveu Exp $
27 */
28
29 /*! \file */
30
31 #ifndef _CELLIAX_SPANDSP_H
32 #define _CELLIAX_SPANDSP_H
33
34 #include <math.h>
35
36 /*! \brief Find the bit position of the highest set bit in a word
37 \param bits The word to be searched
38 \return The bit number of the highest set bit, or -1 if the word is zero. */
top_bit(unsigned int bits)39 static __inline__ int top_bit(unsigned int bits)
40 {
41 int res;
42
43 #if defined(__i386__) || defined(__x86_64__)
44 __asm__(" xorl %[res],%[res];\n" " decl %[res];\n" " bsrl %[bits],%[res]\n":[res] "=&r"
45 (res)
46 : [bits] "rm"(bits));
47 return res;
48 #elif defined(__ppc__) || defined(__powerpc__)
49 __asm__("cntlzw %[res],%[bits];\n":[res] "=&r"(res)
50 : [bits] "r"(bits));
51 return 31 - res;
52 #else
53 if (bits == 0)
54 return -1;
55 res = 0;
56 if (bits & 0xFFFF0000) {
57 bits &= 0xFFFF0000;
58 res += 16;
59 }
60 if (bits & 0xFF00FF00) {
61 bits &= 0xFF00FF00;
62 res += 8;
63 }
64 if (bits & 0xF0F0F0F0) {
65 bits &= 0xF0F0F0F0;
66 res += 4;
67 }
68 if (bits & 0xCCCCCCCC) {
69 bits &= 0xCCCCCCCC;
70 res += 2;
71 }
72 if (bits & 0xAAAAAAAA) {
73 bits &= 0xAAAAAAAA;
74 res += 1;
75 }
76 return res;
77 #endif
78 }
79
80 /*- End of function --------------------------------------------------------*/
81
82 /*! \brief Find the bit position of the lowest set bit in a word
83 \param bits The word to be searched
84 \return The bit number of the lowest set bit, or -1 if the word is zero. */
bottom_bit(unsigned int bits)85 static __inline__ int bottom_bit(unsigned int bits)
86 {
87 int res;
88
89 #if defined(__i386__) || defined(__x86_64__)
90 __asm__(" xorl %[res],%[res];\n" " decl %[res];\n" " bsfl %[bits],%[res]\n":[res] "=&r"
91 (res)
92 : [bits] "rm"(bits));
93 return res;
94 #else
95 if (bits == 0)
96 return -1;
97 res = 31;
98 if (bits & 0x0000FFFF) {
99 bits &= 0x0000FFFF;
100 res -= 16;
101 }
102 if (bits & 0x00FF00FF) {
103 bits &= 0x00FF00FF;
104 res -= 8;
105 }
106 if (bits & 0x0F0F0F0F) {
107 bits &= 0x0F0F0F0F;
108 res -= 4;
109 }
110 if (bits & 0x33333333) {
111 bits &= 0x33333333;
112 res -= 2;
113 }
114 if (bits & 0x55555555) {
115 bits &= 0x55555555;
116 res -= 1;
117 }
118 return res;
119 #endif
120 }
121
122 /*- End of function --------------------------------------------------------*/
123
124 /*! \brief Bit reverse a byte.
125 \param data The byte to be reversed.
126 \return The bit reversed version of data. */
bit_reverse8(uint8_t x)127 static __inline__ uint8_t bit_reverse8(uint8_t x)
128 {
129 #if defined(__i386__) || defined(__x86_64__) || defined(__ppc__) || defined(__powerpc__)
130 /* If multiply is fast */
131 return ((x * 0x0802U & 0x22110U) | (x * 0x8020U & 0x88440U)) * 0x10101U >> 16;
132 #else
133 /* If multiply is slow, but we have a barrel shifter */
134 x = (x >> 4) | (x << 4);
135 x = ((x & 0xCC) >> 2) | ((x & 0x33) << 2);
136 return ((x & 0xAA) >> 1) | ((x & 0x55) << 1);
137 #endif
138 }
139
140 /*- End of function --------------------------------------------------------*/
141
142 /*! \brief Bit reverse a 16 bit word.
143 \param data The word to be reversed.
144 \return The bit reversed version of data. */
145 uint16_t bit_reverse16(uint16_t data);
146
147 /*! \brief Bit reverse a 32 bit word.
148 \param data The word to be reversed.
149 \return The bit reversed version of data. */
150 uint32_t bit_reverse32(uint32_t data);
151
152 /*! \brief Bit reverse each of the four bytes in a 32 bit word.
153 \param data The word to be reversed.
154 \return The bit reversed version of data. */
155 uint32_t bit_reverse_4bytes(uint32_t data);
156
157 #if defined(__x86_64__)
158 /*! \brief Bit reverse each of the eight bytes in a 64 bit word.
159 \param data The word to be reversed.
160 \return The bit reversed version of data. */
161 uint64_t bit_reverse_8bytes(uint64_t data);
162 #endif
163
164 /*! \brief Bit reverse each bytes in a buffer.
165 \param to The buffer to place the reversed data in.
166 \param from The buffer containing the data to be reversed.
167 \param The length of the data in the buffer. */
168 void bit_reverse(uint8_t to[], const uint8_t from[], int len);
169
170 /*! \brief Find the number of set bits in a 32 bit word.
171 \param x The word to be searched.
172 \return The number of set bits. */
173 int one_bits32(uint32_t x);
174
175 /*! \brief Create a mask as wide as the number in a 32 bit word.
176 \param x The word to be searched.
177 \return The mask. */
178 uint32_t make_mask32(uint32_t x);
179
180 /*! \brief Create a mask as wide as the number in a 16 bit word.
181 \param x The word to be searched.
182 \return The mask. */
183 uint16_t make_mask16(uint16_t x);
184
185 /*! \brief Find the least significant one in a word, and return a word
186 with just that bit set.
187 \param x The word to be searched.
188 \return The word with the single set bit. */
least_significant_one32(uint32_t x)189 static __inline__ uint32_t least_significant_one32(uint32_t x)
190 {
191 return (x & (-(int32_t) x));
192 }
193
194 /*- End of function --------------------------------------------------------*/
195
196 /*! \brief Find the most significant one in a word, and return a word
197 with just that bit set.
198 \param x The word to be searched.
199 \return The word with the single set bit. */
most_significant_one32(uint32_t x)200 static __inline__ uint32_t most_significant_one32(uint32_t x)
201 {
202 #if defined(__i386__) || defined(__x86_64__) || defined(__ppc__) || defined(__powerpc__)
203 return 1 << top_bit(x);
204 #else
205 x = make_mask32(x);
206 return (x ^ (x >> 1));
207 #endif
208 }
209
210 /*- End of function --------------------------------------------------------*/
211
212 /*! \brief Find the parity of a byte.
213 \param x The byte to be checked.
214 \return 1 for odd, or 0 for even. */
parity8(uint8_t x)215 static __inline__ int parity8(uint8_t x)
216 {
217 x = (x ^ (x >> 4)) & 0x0F;
218 return (0x6996 >> x) & 1;
219 }
220
221 /*- End of function --------------------------------------------------------*/
222
223 /*! \brief Find the parity of a 16 bit word.
224 \param x The word to be checked.
225 \return 1 for odd, or 0 for even. */
parity16(uint16_t x)226 static __inline__ int parity16(uint16_t x)
227 {
228 x ^= (x >> 8);
229 x = (x ^ (x >> 4)) & 0x0F;
230 return (0x6996 >> x) & 1;
231 }
232
233 /*- End of function --------------------------------------------------------*/
234
235 /*! \brief Find the parity of a 32 bit word.
236 \param x The word to be checked.
237 \return 1 for odd, or 0 for even. */
parity32(uint32_t x)238 static __inline__ int parity32(uint32_t x)
239 {
240 x ^= (x >> 16);
241 x ^= (x >> 8);
242 x = (x ^ (x >> 4)) & 0x0F;
243 return (0x6996 >> x) & 1;
244 }
245
246 /*- End of function --------------------------------------------------------*/
247
248 /*- End of file ------------------------------------------------------------*/
249 /*
250 * SpanDSP - a series of DSP components for telephony
251 *
252 * fir.h - General telephony FIR routines
253 *
254 * Written by Steve Underwood <steveu@coppice.org>
255 *
256 * Copyright (C) 2002 Steve Underwood
257 *
258 * All rights reserved.
259 *
260 * This program is free software; you can redistribute it and/or modify
261 * it under the terms of the GNU General Public License version 2, as
262 * published by the Free Software Foundation.
263 *
264 * This program is distributed in the hope that it will be useful,
265 * but WITHOUT ANY WARRANTY; without even the implied warranty of
266 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
267 * GNU General Public License for more details.
268 *
269 * You should have received a copy of the GNU General Public License
270 * along with this program; if not, write to the Free Software
271 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
272 *
273 * $Id: fir.h,v 1.8 2006/10/24 13:45:28 steveu Exp $
274 */
275
276 /*! \page fir_page FIR filtering
277 \section fir_page_sec_1 What does it do?
278 ???.
279
280 \section fir_page_sec_2 How does it work?
281 ???.
282 */
283
284 #if 0
285 #if defined(USE_MMX) || defined(USE_SSE2)
286 #include "mmx.h"
287 #endif
288
289 /*!
290 16 bit integer FIR descriptor. This defines the working state for a single
291 instance of an FIR filter using 16 bit integer coefficients.
292 */
293 typedef struct {
294 int taps;
295 int curr_pos;
296 const int16_t *coeffs;
297 int16_t *history;
298 } fir16_state_t;
299
300 /*!
301 32 bit integer FIR descriptor. This defines the working state for a single
302 instance of an FIR filter using 32 bit integer coefficients, and filtering
303 16 bit integer data.
304 */
305 typedef struct {
306 int taps;
307 int curr_pos;
308 const int32_t *coeffs;
309 int16_t *history;
310 } fir32_state_t;
311
312 /*!
313 Floating point FIR descriptor. This defines the working state for a single
314 instance of an FIR filter using floating point coefficients and data.
315 */
316 typedef struct {
317 int taps;
318 int curr_pos;
319 const float *coeffs;
320 float *history;
321 } fir_float_state_t;
322
323 static __inline__ const int16_t *fir16_create(fir16_state_t * fir, const int16_t * coeffs,
324 int taps)
325 {
326 fir->taps = taps;
327 fir->curr_pos = taps - 1;
328 fir->coeffs = coeffs;
329 #if defined(USE_MMX) || defined(USE_SSE2)
330 if ((fir->history = malloc(2 * taps * sizeof(int16_t))))
331 memset(fir->history, 0, 2 * taps * sizeof(int16_t));
332 #else
333 if ((fir->history = (int16_t *) malloc(taps * sizeof(int16_t))))
334 memset(fir->history, 0, taps * sizeof(int16_t));
335 #endif
336 return fir->history;
337 }
338
339 /*- End of function --------------------------------------------------------*/
340
341 static __inline__ void fir16_flush(fir16_state_t * fir)
342 {
343 #if defined(USE_MMX) || defined(USE_SSE2)
344 memset(fir->history, 0, 2 * fir->taps * sizeof(int16_t));
345 #else
346 memset(fir->history, 0, fir->taps * sizeof(int16_t));
347 #endif
348 }
349
350 /*- End of function --------------------------------------------------------*/
351
352 static __inline__ void fir16_free(fir16_state_t * fir)
353 {
354 free(fir->history);
355 }
356
357 /*- End of function --------------------------------------------------------*/
358
359 static __inline__ int16_t fir16(fir16_state_t * fir, int16_t sample)
360 {
361 int i;
362 int32_t y;
363 #if defined(USE_MMX)
364 mmx_t *mmx_coeffs;
365 mmx_t *mmx_hist;
366
367 fir->history[fir->curr_pos] = sample;
368 fir->history[fir->curr_pos + fir->taps] = sample;
369
370 mmx_coeffs = (mmx_t *) fir->coeffs;
371 mmx_hist = (mmx_t *) & fir->history[fir->curr_pos];
372 i = fir->taps;
373 pxor_r2r(mm4, mm4);
374 /* 8 samples per iteration, so the filter must be a multiple of 8 long. */
375 while (i > 0) {
376 movq_m2r(mmx_coeffs[0], mm0);
377 movq_m2r(mmx_coeffs[1], mm2);
378 movq_m2r(mmx_hist[0], mm1);
379 movq_m2r(mmx_hist[1], mm3);
380 mmx_coeffs += 2;
381 mmx_hist += 2;
382 pmaddwd_r2r(mm1, mm0);
383 pmaddwd_r2r(mm3, mm2);
384 paddd_r2r(mm0, mm4);
385 paddd_r2r(mm2, mm4);
386 i -= 8;
387 }
388 movq_r2r(mm4, mm0);
389 psrlq_i2r(32, mm0);
390 paddd_r2r(mm0, mm4);
391 movd_r2m(mm4, y);
392 emms();
393 #elif defined(USE_SSE2)
394 xmm_t *xmm_coeffs;
395 xmm_t *xmm_hist;
396
397 fir->history[fir->curr_pos] = sample;
398 fir->history[fir->curr_pos + fir->taps] = sample;
399
400 xmm_coeffs = (xmm_t *) fir->coeffs;
401 xmm_hist = (xmm_t *) & fir->history[fir->curr_pos];
402 i = fir->taps;
403 pxor_r2r(xmm4, xmm4);
404 /* 16 samples per iteration, so the filter must be a multiple of 16 long. */
405 while (i > 0) {
406 movdqu_m2r(xmm_coeffs[0], xmm0);
407 movdqu_m2r(xmm_coeffs[1], xmm2);
408 movdqu_m2r(xmm_hist[0], xmm1);
409 movdqu_m2r(xmm_hist[1], xmm3);
410 xmm_coeffs += 2;
411 xmm_hist += 2;
412 pmaddwd_r2r(xmm1, xmm0);
413 pmaddwd_r2r(xmm3, xmm2);
414 paddd_r2r(xmm0, xmm4);
415 paddd_r2r(xmm2, xmm4);
416 i -= 16;
417 }
418 movdqa_r2r(xmm4, xmm0);
419 psrldq_i2r(8, xmm0);
420 paddd_r2r(xmm0, xmm4);
421 movdqa_r2r(xmm4, xmm0);
422 psrldq_i2r(4, xmm0);
423 paddd_r2r(xmm0, xmm4);
424 movd_r2m(xmm4, y);
425 #else
426 int offset1;
427 int offset2;
428
429 fir->history[fir->curr_pos] = sample;
430
431 offset2 = fir->curr_pos;
432 offset1 = fir->taps - offset2;
433 y = 0;
434 for (i = fir->taps - 1; i >= offset1; i--)
435 y += fir->coeffs[i] * fir->history[i - offset1];
436 for (; i >= 0; i--)
437 y += fir->coeffs[i] * fir->history[i + offset2];
438 #endif
439 if (fir->curr_pos <= 0)
440 fir->curr_pos = fir->taps;
441 fir->curr_pos--;
442 return (int16_t) (y >> 15);
443 }
444
445 /*- End of function --------------------------------------------------------*/
446
447 static __inline__ const int16_t *fir32_create(fir32_state_t * fir, const int32_t * coeffs,
448 int taps)
449 {
450 fir->taps = taps;
451 fir->curr_pos = taps - 1;
452 fir->coeffs = coeffs;
453 fir->history = (int16_t *) malloc(taps * sizeof(int16_t));
454 if (fir->history)
455 memset(fir->history, '\0', taps * sizeof(int16_t));
456 return fir->history;
457 }
458
459 /*- End of function --------------------------------------------------------*/
460
461 static __inline__ void fir32_flush(fir32_state_t * fir)
462 {
463 memset(fir->history, 0, fir->taps * sizeof(int16_t));
464 }
465
466 /*- End of function --------------------------------------------------------*/
467
468 static __inline__ void fir32_free(fir32_state_t * fir)
469 {
470 free(fir->history);
471 }
472
473 /*- End of function --------------------------------------------------------*/
474
475 static __inline__ int16_t fir32(fir32_state_t * fir, int16_t sample)
476 {
477 int i;
478 int32_t y;
479 int offset1;
480 int offset2;
481
482 fir->history[fir->curr_pos] = sample;
483 offset2 = fir->curr_pos;
484 offset1 = fir->taps - offset2;
485 y = 0;
486 for (i = fir->taps - 1; i >= offset1; i--)
487 y += fir->coeffs[i] * fir->history[i - offset1];
488 for (; i >= 0; i--)
489 y += fir->coeffs[i] * fir->history[i + offset2];
490 if (fir->curr_pos <= 0)
491 fir->curr_pos = fir->taps;
492 fir->curr_pos--;
493 return (int16_t) (y >> 15);
494 }
495
496 /*- End of function --------------------------------------------------------*/
497
498 static __inline__ const float *fir_float_create(fir_float_state_t * fir,
499 const float *coeffs, int taps)
500 {
501 fir->taps = taps;
502 fir->curr_pos = taps - 1;
503 fir->coeffs = coeffs;
504 fir->history = (float *) malloc(taps * sizeof(float));
505 if (fir->history)
506 memset(fir->history, '\0', taps * sizeof(float));
507 return fir->history;
508 }
509
510 /*- End of function --------------------------------------------------------*/
511
512 static __inline__ void fir_float_free(fir_float_state_t * fir)
513 {
514 free(fir->history);
515 }
516
517 /*- End of function --------------------------------------------------------*/
518
519 static __inline__ int16_t fir_float(fir_float_state_t * fir, int16_t sample)
520 {
521 int i;
522 float y;
523 int offset1;
524 int offset2;
525
526 fir->history[fir->curr_pos] = sample;
527
528 offset2 = fir->curr_pos;
529 offset1 = fir->taps - offset2;
530 y = 0;
531 for (i = fir->taps - 1; i >= offset1; i--)
532 y += fir->coeffs[i] * fir->history[i - offset1];
533 for (; i >= 0; i--)
534 y += fir->coeffs[i] * fir->history[i + offset2];
535 if (fir->curr_pos <= 0)
536 fir->curr_pos = fir->taps;
537 fir->curr_pos--;
538 return (int16_t) y;
539 }
540
541 /*- End of function --------------------------------------------------------*/
542 #endif
543
544 /*- End of file ------------------------------------------------------------*/
545
546 /*
547 * SpanDSP - a series of DSP components for telephony
548 *
549 * echo.h - An echo cancellor, suitable for electrical and acoustic
550 * cancellation. This code does not currently comply with
551 * any relevant standards (e.g. G.164/5/7/8).
552 *
553 * Written by Steve Underwood <steveu@coppice.org>
554 *
555 * Copyright (C) 2001 Steve Underwood
556 *
557 * Based on a bit from here, a bit from there, eye of toad,
558 * ear of bat, etc - plus, of course, my own 2 cents.
559 *
560 * All rights reserved.
561 *
562 * This program is free software; you can redistribute it and/or modify
563 * it under the terms of the GNU General Public License version 2, as
564 * published by the Free Software Foundation.
565 *
566 * This program is distributed in the hope that it will be useful,
567 * but WITHOUT ANY WARRANTY; without even the implied warranty of
568 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
569 * GNU General Public License for more details.
570 *
571 * You should have received a copy of the GNU General Public License
572 * along with this program; if not, write to the Free Software
573 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
574 *
575 * $Id: echo.h,v 1.9 2006/10/24 13:45:28 steveu Exp $
576 */
577
578 /*! \file */
579
580 /*! \page echo_can_page Line echo cancellation for voice
581
582 \section echo_can_page_sec_1 What does it do?
583 This module aims to provide G.168-2002 compliant echo cancellation, to remove
584 electrical echoes (e.g. from 2-4 wire hybrids) from voice calls.
585
586 \section echo_can_page_sec_2 How does it work?
587 The heart of the echo cancellor is FIR filter. This is adapted to match the echo
588 impulse response of the telephone line. It must be long enough to adequately cover
589 the duration of that impulse response. The signal transmitted to the telephone line
590 is passed through the FIR filter. Once the FIR is properly adapted, the resulting
591 output is an estimate of the echo signal received from the line. This is subtracted
592 from the received signal. The result is an estimate of the signal which originated
593 at the far end of the line, free from echos of our own transmitted signal.
594
595 The least mean squares (LMS) algorithm is attributed to Widrow and Hoff, and was
596 introduced in 1960. It is the commonest form of filter adaption used in things
597 like modem line equalisers and line echo cancellers. There it works very well.
598 However, it only works well for signals of constant amplitude. It works very poorly
599 for things like speech echo cancellation, where the signal level varies widely.
600 This is quite easy to fix. If the signal level is normalised - similar to applying
601 AGC - LMS can work as well for a signal of varying amplitude as it does for a modem
602 signal. This normalised least mean squares (NLMS) algorithm is the commonest one used
603 for speech echo cancellation. Many other algorithms exist - e.g. RLS (essentially
604 the same as Kalman filtering), FAP, etc. Some perform significantly better than NLMS.
605 However, factors such as computational complexity and patents favour the use of NLMS.
606
607 A simple refinement to NLMS can improve its performance with speech. NLMS tends
608 to adapt best to the strongest parts of a signal. If the signal is white noise,
609 the NLMS algorithm works very well. However, speech has more low frequency than
610 high frequency content. Pre-whitening (i.e. filtering the signal to flatten
611 its spectrum) the echo signal improves the adapt rate for speech, and ensures the
612 final residual signal is not heavily biased towards high frequencies. A very low
613 complexity filter is adequate for this, so pre-whitening adds little to the
614 compute requirements of the echo canceller.
615
616 An FIR filter adapted using pre-whitened NLMS performs well, provided certain
617 conditions are met:
618
619 - The transmitted signal has poor self-correlation.
620 - There is no signal being generated within the environment being cancelled.
621
622 The difficulty is that neither of these can be guaranteed.
623
624 If the adaption is performed while transmitting noise (or something fairly noise
625 like, such as voice) the adaption works very well. If the adaption is performed
626 while transmitting something highly correlative (typically narrow band energy
627 such as signalling tones or DTMF), the adaption can go seriously wrong. The reason
628 is there is only one solution for the adaption on a near random signal - the impulse
629 response of the line. For a repetitive signal, there are any number of solutions
630 which converge the adaption, and nothing guides the adaption to choose the generalised
631 one. Allowing an untrained canceller to converge on this kind of narrowband
632 energy probably a good thing, since at least it cancels the tones. Allowing a well
633 converged canceller to continue converging on such energy is just a way to ruin
634 its generalised adaption. A narrowband detector is needed, so adapation can be
635 suspended at appropriate times.
636
637 The adaption process is based on trying to eliminate the received signal. When
638 there is any signal from within the environment being cancelled it may upset the
639 adaption process. Similarly, if the signal we are transmitting is small, noise
640 may dominate and disturb the adaption process. If we can ensure that the
641 adaption is only performed when we are transmitting a significant signal level,
642 and the environment is not, things will be OK. Clearly, it is easy to tell when
643 we are sending a significant signal. Telling, if the environment is generating a
644 significant signal, and doing it with sufficient speed that the adaption will
645 not have diverged too much more we stop it, is a little harder.
646
647 The key problem in detecting when the environment is sourcing significant energy
648 is that we must do this very quickly. Given a reasonably long sample of the
649 received signal, there are a number of strategies which may be used to assess
650 whether that signal contains a strong far end component. However, by the time
651 that assessment is complete the far end signal will have already caused major
652 mis-convergence in the adaption process. An assessment algorithm is needed which
653 produces a fairly accurate result from a very short burst of far end energy.
654
655 \section echo_can_page_sec_3 How do I use it?
656 The echo cancellor processes both the transmit and receive streams sample by
657 sample. The processing function is not declared inline. Unfortunately,
658 cancellation requires many operations per sample, so the call overhead is only a
659 minor burden.
660 */
661
662 #define NONUPDATE_DWELL_TIME 600 /* 600 samples, or 75ms */
663
664 #if 0
665 /* Mask bits for the adaption mode */
666 #define ECHO_CAN_USE_NLP 0x01
667 #define ECHO_CAN_USE_SUPPRESSOR 0x02
668 #define ECHO_CAN_USE_CNG 0x04
669 #define ECHO_CAN_USE_ADAPTION 0x08
670
671 /*!
672 G.168 echo canceller descriptor. This defines the working state for a line
673 echo canceller.
674 */
675 typedef struct {
676 int tx_power[4];
677 int rx_power[3];
678 int clean_rx_power;
679
680 int rx_power_threshold;
681 int nonupdate_dwell;
682
683 fir16_state_t fir_state;
684 /*! Echo FIR taps (16 bit version) */
685 int16_t *fir_taps16[4];
686 /*! Echo FIR taps (32 bit version) */
687 int32_t *fir_taps32;
688
689 int curr_pos;
690
691 int taps;
692 int tap_mask;
693 int adaption_mode;
694
695 int32_t supp_test1;
696 int32_t supp_test2;
697 int32_t supp1;
698 int32_t supp2;
699 int vad;
700 int cng;
701 /* Parameters for the Hoth noise generator */
702 int cng_level;
703 int cng_rndnum;
704 int cng_filter;
705
706 int16_t geigel_max;
707 int geigel_lag;
708 int dtd_onset;
709 int tap_set;
710 int tap_rotate_counter;
711
712 int32_t latest_correction; /* Indication of the magnitude of the latest
713 adaption, or a code to indicate why adaption
714 was skipped, for test purposes */
715 int32_t last_acf[28];
716 int narrowband_count;
717 int narrowband_score;
718 } echo_can_state_t;
719
720 /*! Create a voice echo canceller context.
721 \param len The length of the canceller, in samples.
722 \return The new canceller context, or NULL if the canceller could not be created.
723 */
724 echo_can_state_t *echo_can_create(int len, int adaption_mode);
725
726 /*! Free a voice echo canceller context.
727 \param ec The echo canceller context.
728 */
729 void echo_can_free(echo_can_state_t * ec);
730
731 /*! Flush (reinitialise) a voice echo canceller context.
732 \param ec The echo canceller context.
733 */
734 void echo_can_flush(echo_can_state_t * ec);
735
736 /*! Set the adaption mode of a voice echo canceller context.
737 \param ec The echo canceller context.
738 \param adapt The mode.
739 */
740 void echo_can_adaption_mode(echo_can_state_t * ec, int adaption_mode);
741
742 /*! Process a sample through a voice echo canceller.
743 \param ec The echo canceller context.
744 \param tx The transmitted audio sample.
745 \param rx The received audio sample.
746 \return The clean (echo cancelled) received sample.
747 */
748 int16_t echo_can_update(echo_can_state_t * ec, int16_t tx, int16_t rx);
749
750 #endif
751 /*- End of file ------------------------------------------------------------*/
752
753 /*!
754 Floating point Goertzel filter descriptor.
755 */
756 typedef struct {
757 float fac;
758 int samples;
759 } goertzel_descriptor_t;
760
761 /*!
762 Floating point Goertzel filter state descriptor.
763 */
764 typedef struct {
765 float v2;
766 float v3;
767 float fac;
768 int samples;
769 int current_sample;
770 } goertzel_state_t;
771
772 /*! \brief Create a descriptor for use with either a Goertzel transform */
773 void make_goertzel_descriptor(goertzel_descriptor_t * t, float freq, int samples);
774
775 /*! \brief Initialise the state of a Goertzel transform.
776 \param s The Goertzel context. If NULL, a context is allocated with malloc.
777 \param t The Goertzel descriptor.
778 \return A pointer to the Goertzel state. */
779 goertzel_state_t *goertzel_init(goertzel_state_t * s, goertzel_descriptor_t * t);
780
781 /*! \brief Reset the state of a Goertzel transform.
782 \param s The Goertzel context.
783 \param t The Goertzel descriptor.
784 \return A pointer to the Goertzel state. */
785 void goertzel_reset(goertzel_state_t * s);
786
787 /*! \brief Update the state of a Goertzel transform.
788 \param s The Goertzel context
789 \param amp The samples to be transformed
790 \param samples The number of samples
791 \return The number of samples unprocessed */
792 int goertzel_update(goertzel_state_t * s, const int16_t amp[], int samples);
793
794 /*! \brief Evaluate the final result of a Goertzel transform.
795 \param s The Goertzel context
796 \return The result of the transform. */
797 float goertzel_result(goertzel_state_t * s);
798
799 /*! \brief Update the state of a Goertzel transform.
800 \param s The Goertzel context
801 \param amp The sample to be transformed. */
goertzel_sample(goertzel_state_t * s,int16_t amp)802 static __inline__ void goertzel_sample(goertzel_state_t * s, int16_t amp)
803 {
804 float v1;
805
806 v1 = s->v2;
807 s->v2 = s->v3;
808 s->v3 = s->fac * s->v2 - v1 + amp;
809 s->current_sample++;
810 }
811
812 /*- End of function --------------------------------------------------------*/
813
814 /*
815 * SpanDSP - a series of DSP components for telephony
816 *
817 * tone_detect.c - General telephony tone detection.
818 *
819 * Written by Steve Underwood <steveu@coppice.org>
820 *
821 * Copyright (C) 2001-2003, 2005 Steve Underwood
822 *
823 * All rights reserved.
824 *
825 * This program is free software; you can redistribute it and/or modify
826 * it under the terms of the GNU General Public License version 2, as
827 * published by the Free Software Foundation.
828 *
829 * This program is distributed in the hope that it will be useful,
830 * but WITHOUT ANY WARRANTY; without even the implied warranty of
831 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
832 * GNU General Public License for more details.
833 *
834 * You should have received a copy of the GNU General Public License
835 * along with this program; if not, write to the Free Software
836 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
837 *
838 * $Id: tone_detect.c,v 1.31 2007/03/03 10:40:33 steveu Exp $
839 */
840
841 /*! \file tone_detect.h */
842
843 #if !defined(M_PI)
844 /* C99 systems may not define M_PI */
845 #define M_PI 3.14159265358979323846264338327
846 #endif
847 /*! \page dtmf_rx_page DTMF receiver
848 \section dtmf_rx_page_sec_1 What does it do?
849 The DTMF receiver detects the standard DTMF digits. It is compliant with
850 ITU-T Q.23, ITU-T Q.24, and the local DTMF specifications of most administrations.
851 Its passes the test suites. It also scores *very* well on the standard
852 talk-off tests.
853
854 The current design uses floating point extensively. It is not tolerant of DC.
855 It is expected that a DC restore stage will be placed before the DTMF detector.
856 Unless the dial tone filter is switched on, the detector has poor tolerance
857 of dial tone. Whether this matter depends on your application. If you are using
858 the detector in an IVR application you will need proper echo cancellation to
859 get good performance in the presence of speech prompts, so dial tone will not
860 exist. If you do need good dial tone tolerance, a dial tone filter can be
861 enabled in the detector.
862
863 \section dtmf_rx_page_sec_2 How does it work?
864 Like most other DSP based DTMF detector's, this one uses the Goertzel algorithm
865 to look for the DTMF tones. What makes each detector design different is just how
866 that algorithm is used.
867
868 Basic DTMF specs:
869 - Minimum tone on = 40ms
870 - Minimum tone off = 50ms
871 - Maximum digit rate = 10 per second
872 - Normal twist <= 8dB accepted
873 - Reverse twist <= 4dB accepted
874 - S/N >= 15dB will detect OK
875 - Attenuation <= 26dB will detect OK
876 - Frequency tolerance +- 1.5% will detect, +-3.5% will reject
877
878 TODO:
879 */
880
881 /*! \page dtmf_tx_page DTMF tone generation
882 \section dtmf_tx_page_sec_1 What does it do?
883
884 The DTMF tone generation module provides for the generation of the
885 repertoire of 16 DTMF dual tones.
886
887 \section dtmf_tx_page_sec_2 How does it work?
888 */
889
890 #define MAX_DTMF_DIGITS 128
891
892 typedef void (*dtmf_rx_callback_t) (void *user_data, const char *digits, int len);
893
894 /*!
895 DTMF generator state descriptor. This defines the state of a single
896 working instance of a DTMF generator.
897 */
898 #if 0
899 typedef struct {
900 tone_gen_descriptor_t *tone_descriptors;
901 tone_gen_state_t tones;
902 char digits[MAX_DTMF_DIGITS + 1];
903 int current_sample;
904 size_t current_digits;
905 } dtmf_tx_state_t;
906
907 #endif
908
909 /*!
910 DTMF digit detector descriptor.
911 */
912 typedef struct {
913 /*! Optional callback funcion to deliver received digits. */
914 dtmf_rx_callback_t callback;
915 /*! An opaque pointer passed to the callback function. */
916 void *callback_data;
917 /*! Optional callback funcion to deliver real time digit state changes. */
918 //tone_report_func_t realtime_callback;
919 void *realtime_callback;
920 /*! An opaque pointer passed to the real time callback function. */
921 void *realtime_callback_data;
922 /*! TRUE if dialtone should be filtered before processing */
923 int filter_dialtone;
924 /*! Maximum acceptable "normal" (lower bigger than higher) twist ratio */
925 float normal_twist;
926 /*! Maximum acceptable "reverse" (higher bigger than lower) twist ratio */
927 float reverse_twist;
928
929 /*! 350Hz filter state for the optional dialtone filter */
930 float z350_1;
931 float z350_2;
932 /*! 440Hz filter state for the optional dialtone filter */
933 float z440_1;
934 float z440_2;
935
936 /*! Tone detector working states */
937 goertzel_state_t row_out[4];
938 goertzel_state_t col_out[4];
939 /*! The accumlating total energy on the same period over which the Goertzels work. */
940 float energy;
941 /*! The result of the last tone analysis. */
942 uint8_t last_hit;
943 /*! The confirmed digit we are currently receiving */
944 uint8_t in_digit;
945 /*! The current sample number within a processing block. */
946 int current_sample;
947
948 /*! The received digits buffer. This is a NULL terminated string. */
949 char digits[MAX_DTMF_DIGITS + 1];
950 /*! The number of digits currently in the digit buffer. */
951 int current_digits;
952 /*! The number of digits which have been lost due to buffer overflows. */
953 int lost_digits;
954 } dtmf_rx_state_t;
955
956 #if 0
957 /*! \brief Generate a buffer of DTMF tones.
958 \param s The DTMF generator context.
959 \param amp The buffer for the generated signal.
960 \param max_samples The required number of generated samples.
961 \return The number of samples actually generated. This may be less than
962 samples if the input buffer empties. */
963 int dtmf_tx(dtmf_tx_state_t * s, int16_t amp[], int max_samples);
964
965 /*! \brief Put a string of digits in a DTMF generator's input buffer.
966 \param s The DTMF generator context.
967 \param digits The string of digits to be added.
968 \return The number of digits actually added. This may be less than the
969 length of the digit string, if the buffer fills up. */
970 size_t dtmf_tx_put(dtmf_tx_state_t * s, const char *digits);
971
972 /*! \brief Initialise a DTMF tone generator context.
973 \param s The DTMF generator context.
974 \return A pointer to the DTMF generator context. */
975 dtmf_tx_state_t *dtmf_tx_init(dtmf_tx_state_t * s);
976 #endif
977
978 /*! Set a optional realtime callback for a DTMF receiver context. This function
979 is called immediately a confirmed state change occurs in the received DTMF. It
980 is called with the ASCII value for a DTMF tone pair, or zero to indicate no tone
981 is being received.
982 \brief Set a realtime callback for a DTMF receiver context.
983 \param s The DTMF receiver context.
984 \param callback Callback routine used to report the start and end of digits.
985 \param user_data An opaque pointer which is associated with the context,
986 and supplied in callbacks. */
987 void dtmf_rx_set_realtime_callback(dtmf_rx_state_t * s,
988 //tone_report_func_t callback,
989 void *callback, void *user_data);
990
991 /*! \brief Adjust a DTMF receiver context.
992 \param s The DTMF receiver context.
993 \param filter_dialtone TRUE to enable filtering of dialtone, FALSE
994 to disable, < 0 to leave unchanged.
995 \param twist Acceptable twist, in dB. < 0 to leave unchanged.
996 \param reverse_twist Acceptable reverse twist, in dB. < 0 to leave unchanged. */
997 void dtmf_rx_parms(dtmf_rx_state_t * s, int filter_dialtone, int twist,
998 int reverse_twist);
999
1000 /*! Process a block of received DTMF audio samples.
1001 \brief Process a block of received DTMF audio samples.
1002 \param s The DTMF receiver context.
1003 \param amp The audio sample buffer.
1004 \param samples The number of samples in the buffer.
1005 \return The number of samples unprocessed. */
1006 int dtmf_rx(dtmf_rx_state_t * s, const int16_t amp[], int samples);
1007
1008 /*! \brief Get a string of digits from a DTMF receiver's output buffer.
1009 \param s The DTMF receiver context.
1010 \param digits The buffer for the received digits.
1011 \param max The maximum number of digits to be returned,
1012 \return The number of digits actually returned. */
1013 size_t dtmf_rx_get(dtmf_rx_state_t * s, char *digits, int max);
1014
1015 /*! \brief Initialise a DTMF receiver context.
1016 \param s The DTMF receiver context.
1017 \param callback An optional callback routine, used to report received digits. If
1018 no callback routine is set, digits may be collected, using the dtmf_rx_get()
1019 function.
1020 \param user_data An opaque pointer which is associated with the context,
1021 and supplied in callbacks.
1022 \return A pointer to the DTMF receiver context. */
1023 dtmf_rx_state_t *dtmf_rx_init(dtmf_rx_state_t * s, dtmf_rx_callback_t callback,
1024 void *user_data);
1025
1026 /*- End of file ------------------------------------------------------------*/
1027
1028 #endif /* _CELLIAX_SPANDSP_H */
1029