drivers/staging/echo/echo.h

   1 /*
   2  * SpanDSP - a series of DSP components for telephony
   3  *
   4  * echo.c - A line echo canceller.  This code is being developed
   5  *          against and partially complies with G168.
   6  *
   7  * Written by Steve Underwood <steveu@coppice.org>
   8  *         and David Rowe <david_at_rowetel_dot_com>
   9  *
  10  * Copyright (C) 2001 Steve Underwood and 2007 David Rowe
  11  *
  12  * All rights reserved.
  13  *
  14  * This program is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU General Public License version 2, as
  16  * published by the Free Software Foundation.
  17  *
  18  * This program is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * along with this program; if not, write to the Free Software
  25  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  26  *
  27  * $Id: echo.h,v 1.9 2006/10/24 13:45:28 steveu Exp $
  28  */
  29
  30 #ifndef __ECHO_H
  31 #define __ECHO_H
  32
  33 /*! \page echo_can_page Line echo cancellation for voice
  34
  35 \section echo_can_page_sec_1 What does it do?
  36 This module aims to provide G.168-2002 compliant echo cancellation, to remove
  37 electrical echoes (e.g. from 2-4 wire hybrids) from voice calls.
  38
  39 \section echo_can_page_sec_2 How does it work?
  40 The heart of the echo cancellor is FIR filter. This is adapted to match the
  41 echo impulse response of the telephone line. It must be long enough to
  42 adequately cover the duration of that impulse response. The signal transmitted
  43 to the telephone line is passed through the FIR filter. Once the FIR is
  44 properly adapted, the resulting output is an estimate of the echo signal
  45 received from the line. This is subtracted from the received signal. The result
  46 is an estimate of the signal which originated at the far end of the line, free
  47 from echos of our own transmitted signal.
  48
  49 The least mean squares (LMS) algorithm is attributed to Widrow and Hoff, and
  50 was introduced in 1960. It is the commonest form of filter adaption used in
  51 things like modem line equalisers and line echo cancellers. There it works very
  52 well.  However, it only works well for signals of constant amplitude. It works
  53 very poorly for things like speech echo cancellation, where the signal level
  54 varies widely.  This is quite easy to fix. If the signal level is normalised -
  55 similar to applying AGC - LMS can work as well for a signal of varying
  56 amplitude as it does for a modem signal. This normalised least mean squares
  57 (NLMS) algorithm is the commonest one used for speech echo cancellation. Many
  58 other algorithms exist - e.g. RLS (essentially the same as Kalman filtering),
  59 FAP, etc. Some perform significantly better than NLMS.  However, factors such
  60 as computational complexity and patents favour the use of NLMS.
  61
  62 A simple refinement to NLMS can improve its performance with speech. NLMS tends
  63 to adapt best to the strongest parts of a signal. If the signal is white noise,
  64 the NLMS algorithm works very well. However, speech has more low frequency than
  65 high frequency content. Pre-whitening (i.e. filtering the signal to flatten its
  66 spectrum) the echo signal improves the adapt rate for speech, and ensures the
  67 final residual signal is not heavily biased towards high frequencies. A very
  68 low complexity filter is adequate for this, so pre-whitening adds little to the
  69 compute requirements of the echo canceller.
  70
  71 An FIR filter adapted using pre-whitened NLMS performs well, provided certain
  72 conditions are met:
  73
  74     - The transmitted signal has poor self-correlation.
  75     - There is no signal being generated within the environment being
  76       cancelled.
  77
  78 The difficulty is that neither of these can be guaranteed.
  79
  80 If the adaption is performed while transmitting noise (or something fairly
  81 noise like, such as voice) the adaption works very well. If the adaption is
  82 performed while transmitting something highly correlative (typically narrow
  83 band energy such as signalling tones or DTMF), the adaption can go seriously
  84 wrong. The reason is there is only one solution for the adaption on a near
  85 random signal - the impulse response of the line. For a repetitive signal,
  86 there are any number of solutions which converge the adaption, and nothing
  87 guides the adaption to choose the generalised one. Allowing an untrained
  88 canceller to converge on this kind of narrowband energy probably a good thing,
  89 since at least it cancels the tones. Allowing a well converged canceller to
  90 continue converging on such energy is just a way to ruin its generalised
  91 adaption. A narrowband detector is needed, so adapation can be suspended at
  92 appropriate times.
  93
  94 The adaption process is based on trying to eliminate the received signal. When
  95 there is any signal from within the environment being cancelled it may upset
  96 the adaption process. Similarly, if the signal we are transmitting is small,
  97 noise may dominate and disturb the adaption process. If we can ensure that the
  98 adaption is only performed when we are transmitting a significant signal level,
  99 and the environment is not, things will be OK. Clearly, it is easy to tell when
 100 we are sending a significant signal. Telling, if the environment is generating
 101 a significant signal, and doing it with sufficient speed that the adaption will
 102 not have diverged too much more we stop it, is a little harder.
 103
 104 The key problem in detecting when the environment is sourcing significant
 105 energy is that we must do this very quickly. Given a reasonably long sample of
 106 the received signal, there are a number of strategies which may be used to
 107 assess whether that signal contains a strong far end component. However, by the
 108 time that assessment is complete the far end signal will have already caused
 109 major mis-convergence in the adaption process. An assessment algorithm is
 110 needed which produces a fairly accurate result from a very short burst of far
 111 end energy.
 112
 113 \section echo_can_page_sec_3 How do I use it?
 114 The echo cancellor processes both the transmit and receive streams sample by
 115 sample. The processing function is not declared inline. Unfortunately,
 116 cancellation requires many operations per sample, so the call overhead is only
 117 a minor burden.
 118 */
 119
 120 #include "fir.h"
 121 #include "oslec.h"
 122
 123 /*!
 124     G.168 echo canceller descriptor. This defines the working state for a line
 125     echo canceller.
 126 */
 127 struct oslec_state {
 128         int16_t tx, rx;
 129         int16_t clean;
 130         int16_t clean_nlp;
 131
 132         int nonupdate_dwell;
 133         int curr_pos;
 134         int taps;
 135         int log2taps;
 136         int adaption_mode;
 137
 138         int cond_met;
 139         int32_t Pstates;
 140         int16_t adapt;
 141         int32_t factor;
 142         int16_t shift;
 143
 144         /* Average levels and averaging filter states */
 145         int Ltxacc, Lrxacc, Lcleanacc, Lclean_bgacc;
 146         int Ltx, Lrx;
 147         int Lclean;
 148         int Lclean_bg;
 149         int Lbgn, Lbgn_acc, Lbgn_upper, Lbgn_upper_acc;
 150
 151         /* foreground and background filter states */
 152         fir16_state_t fir_state;
 153         fir16_state_t fir_state_bg;
 154         int16_t *fir_taps16[2];
 155
 156         /* DC blocking filter states */
 157         int tx_1, tx_2, rx_1, rx_2;
 158
 159         /* optional High Pass Filter states */
 160         int32_t xvtx[5], yvtx[5];
 161         int32_t xvrx[5], yvrx[5];
 162
 163         /* Parameters for the optional Hoth noise generator */
 164         int cng_level;
 165         int cng_rndnum;
 166         int cng_filter;
 167
 168         /* snapshot sample of coeffs used for development */
 169         int16_t *snapshot;
 170 };
 171
 172 #endif /* __ECHO_H */