misc/echo/echo.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * SpanDSP - a series of DSP components for telephony
0004  *
0005  * echo.c - A line echo canceller.  This code is being developed
0006  *          against and partially complies with G168.
0007  *
0008  * Written by Steve Underwood <steveu@coppice.org>
0009  *         and David Rowe <david_at_rowetel_dot_com>
0010  *
0011  * Copyright (C) 2001 Steve Underwood and 2007 David Rowe
0012  *
0013  * All rights reserved.
0014  */
0015
0016 #ifndef __ECHO_H
0017 #define __ECHO_H
0018
0019 /*
0020 Line echo cancellation for voice
0021
0022 What does it do?
0023
0024 This module aims to provide G.168-2002 compliant echo cancellation, to remove
0025 electrical echoes (e.g. from 2-4 wire hybrids) from voice calls.
0026
0027 How does it work?
0028
0029 The heart of the echo cancellor is FIR filter. This is adapted to match the
0030 echo impulse response of the telephone line. It must be long enough to
0031 adequately cover the duration of that impulse response. The signal transmitted
0032 to the telephone line is passed through the FIR filter. Once the FIR is
0033 properly adapted, the resulting output is an estimate of the echo signal
0034 received from the line. This is subtracted from the received signal. The result
0035 is an estimate of the signal which originated at the far end of the line, free
0036 from echos of our own transmitted signal.
0037
0038 The least mean squares (LMS) algorithm is attributed to Widrow and Hoff, and
0039 was introduced in 1960. It is the commonest form of filter adaption used in
0040 things like modem line equalisers and line echo cancellers. There it works very
0041 well.  However, it only works well for signals of constant amplitude. It works
0042 very poorly for things like speech echo cancellation, where the signal level
0043 varies widely.  This is quite easy to fix. If the signal level is normalised -
0044 similar to applying AGC - LMS can work as well for a signal of varying
0045 amplitude as it does for a modem signal. This normalised least mean squares
0046 (NLMS) algorithm is the commonest one used for speech echo cancellation. Many
0047 other algorithms exist - e.g. RLS (essentially the same as Kalman filtering),
0048 FAP, etc. Some perform significantly better than NLMS.  However, factors such
0049 as computational complexity and patents favour the use of NLMS.
0050
0051 A simple refinement to NLMS can improve its performance with speech. NLMS tends
0052 to adapt best to the strongest parts of a signal. If the signal is white noise,
0053 the NLMS algorithm works very well. However, speech has more low frequency than
0054 high frequency content. Pre-whitening (i.e. filtering the signal to flatten its
0055 spectrum) the echo signal improves the adapt rate for speech, and ensures the
0056 final residual signal is not heavily biased towards high frequencies. A very
0057 low complexity filter is adequate for this, so pre-whitening adds little to the
0058 compute requirements of the echo canceller.
0059
0060 An FIR filter adapted using pre-whitened NLMS performs well, provided certain
0061 conditions are met:
0062
0063     - The transmitted signal has poor self-correlation.
0064     - There is no signal being generated within the environment being
0065       cancelled.
0066
0067 The difficulty is that neither of these can be guaranteed.
0068
0069 If the adaption is performed while transmitting noise (or something fairly
0070 noise like, such as voice) the adaption works very well. If the adaption is
0071 performed while transmitting something highly correlative (typically narrow
0072 band energy such as signalling tones or DTMF), the adaption can go seriously
0073 wrong. The reason is there is only one solution for the adaption on a near
0074 random signal - the impulse response of the line. For a repetitive signal,
0075 there are any number of solutions which converge the adaption, and nothing
0076 guides the adaption to choose the generalised one. Allowing an untrained
0077 canceller to converge on this kind of narrowband energy probably a good thing,
0078 since at least it cancels the tones. Allowing a well converged canceller to
0079 continue converging on such energy is just a way to ruin its generalised
0080 adaption. A narrowband detector is needed, so adapation can be suspended at
0081 appropriate times.
0082
0083 The adaption process is based on trying to eliminate the received signal. When
0084 there is any signal from within the environment being cancelled it may upset
0085 the adaption process. Similarly, if the signal we are transmitting is small,
0086 noise may dominate and disturb the adaption process. If we can ensure that the
0087 adaption is only performed when we are transmitting a significant signal level,
0088 and the environment is not, things will be OK. Clearly, it is easy to tell when
0089 we are sending a significant signal. Telling, if the environment is generating
0090 a significant signal, and doing it with sufficient speed that the adaption will
0091 not have diverged too much more we stop it, is a little harder.
0092
0093 The key problem in detecting when the environment is sourcing significant
0094 energy is that we must do this very quickly. Given a reasonably long sample of
0095 the received signal, there are a number of strategies which may be used to
0096 assess whether that signal contains a strong far end component. However, by the
0097 time that assessment is complete the far end signal will have already caused
0098 major mis-convergence in the adaption process. An assessment algorithm is
0099 needed which produces a fairly accurate result from a very short burst of far
0100 end energy.
0101
0102 How do I use it?
0103
0104 The echo cancellor processes both the transmit and receive streams sample by
0105 sample. The processing function is not declared inline. Unfortunately,
0106 cancellation requires many operations per sample, so the call overhead is only
0107 a minor burden.
0108 */
0109
0110 #include "fir.h"
0111 #include "oslec.h"
0112
0113 /*
0114     G.168 echo canceller descriptor. This defines the working state for a line
0115     echo canceller.
0116 */
0117 struct oslec_state {
0118     int16_t tx;
0119     int16_t rx;
0120     int16_t clean;
0121     int16_t clean_nlp;
0122
0123     int nonupdate_dwell;
0124     int curr_pos;
0125     int taps;
0126     int log2taps;
0127     int adaption_mode;
0128
0129     int cond_met;
0130     int32_t pstates;
0131     int16_t adapt;
0132     int32_t factor;
0133     int16_t shift;
0134
0135     /* Average levels and averaging filter states */
0136     int ltxacc;
0137     int lrxacc;
0138     int lcleanacc;
0139     int lclean_bgacc;
0140     int ltx;
0141     int lrx;
0142     int lclean;
0143     int lclean_bg;
0144     int lbgn;
0145     int lbgn_acc;
0146     int lbgn_upper;
0147     int lbgn_upper_acc;
0148
0149     /* foreground and background filter states */
0150     struct fir16_state_t fir_state;
0151     struct fir16_state_t fir_state_bg;
0152     int16_t *fir_taps16[2];
0153
0154     /* DC blocking filter states */
0155     int tx_1;
0156     int tx_2;
0157     int rx_1;
0158     int rx_2;
0159
0160     /* optional High Pass Filter states */
0161     int32_t xvtx[5];
0162     int32_t yvtx[5];
0163     int32_t xvrx[5];
0164     int32_t yvrx[5];
0165
0166     /* Parameters for the optional Hoth noise generator */
0167     int cng_level;
0168     int cng_rndnum;
0169     int cng_filter;
0170
0171     /* snapshot sample of coeffs used for development */
0172     int16_t *snapshot;
0173 };
0174
0175 #endif /* __ECHO_H */