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
 122 /* Mask bits for the adaption mode */
 123 #define ECHO_CAN_USE_ADAPTION   0x01
 124 #define ECHO_CAN_USE_NLP        0x02
 125 #define ECHO_CAN_USE_CNG        0x04
 126 #define ECHO_CAN_USE_CLIP       0x08
 127 #define ECHO_CAN_USE_TX_HPF     0x10
 128 #define ECHO_CAN_USE_RX_HPF     0x20
 129 #define ECHO_CAN_DISABLE        0x40
 130
 131 /*!
 132     G.168 echo canceller descriptor. This defines the working state for a line
 133     echo canceller.
 134 */
 135 typedef struct
 136 {
 137         int16_t tx,rx;
 138         int16_t clean;
 139         int16_t clean_nlp;
 140
 141         int nonupdate_dwell;
 142         int curr_pos;
 143         int taps;
 144         int log2taps;
 145         int adaption_mode;
 146
 147         int cond_met;
 148         int32_t Pstates;
 149         int16_t adapt;
 150         int32_t factor;
 151         int16_t shift;
 152
 153         /* Average levels and averaging filter states */
 154         int Ltxacc, Lrxacc, Lcleanacc, Lclean_bgacc;
 155         int Ltx, Lrx;
 156         int Lclean;
 157         int Lclean_bg;
 158         int Lbgn, Lbgn_acc, Lbgn_upper, Lbgn_upper_acc;
 159
 160         /* foreground and background filter states */
 161         fir16_state_t fir_state;
 162         fir16_state_t fir_state_bg;
 163         int16_t *fir_taps16[2];
 164
 165         /* DC blocking filter states */
 166         int tx_1, tx_2, rx_1, rx_2;
 167
 168         /* optional High Pass Filter states */
 169         int32_t xvtx[5], yvtx[5];
 170         int32_t xvrx[5], yvrx[5];
 171
 172         /* Parameters for the optional Hoth noise generator */
 173         int cng_level;
 174         int cng_rndnum;
 175         int cng_filter;
 176
 177         /* snapshot sample of coeffs used for development */
 178         int16_t *snapshot;
 179 } echo_can_state_t;
 180
 181 /*! Create a voice echo canceller context.
 182     \param len The length of the canceller, in samples.
 183     \return The new canceller context, or NULL if the canceller could not be created.
 184 */
 185 echo_can_state_t *echo_can_create(int len, int adaption_mode);
 186
 187 /*! Free a voice echo canceller context.
 188     \param ec The echo canceller context.
 189 */
 190 void echo_can_free(echo_can_state_t *ec);
 191
 192 /*! Flush (reinitialise) a voice echo canceller context.
 193     \param ec The echo canceller context.
 194 */
 195 void echo_can_flush(echo_can_state_t *ec);
 196
 197 /*! Set the adaption mode of a voice echo canceller context.
 198     \param ec The echo canceller context.
 199     \param adapt The mode.
 200 */
 201 void echo_can_adaption_mode(echo_can_state_t *ec, int adaption_mode);
 202
 203 void echo_can_snapshot(echo_can_state_t *ec);
 204
 205 /*! Process a sample through a voice echo canceller.
 206     \param ec The echo canceller context.
 207     \param tx The transmitted audio sample.
 208     \param rx The received audio sample.
 209     \return The clean (echo cancelled) received sample.
 210 */
 211 int16_t echo_can_update(echo_can_state_t *ec, int16_t tx, int16_t rx);
 212
 213 /*! Process to high pass filter the tx signal.
 214     \param ec The echo canceller context.
 215     \param tx The transmitted auio sample.
 216     \return The HP filtered transmit sample, send this to your D/A.
 217 */
 218 int16_t echo_can_hpf_tx(echo_can_state_t *ec, int16_t tx);
 219
 220 #endif  /* __ECHO_H */