v22bis.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * v22bis.h - ITU V.22bis modem receive part
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2004 Steve Underwood
00009  *
00010  * All rights reserved.
00011  *
00012  * This program is free software; you can redistribute it and/or modify
00013  * it under the terms of the GNU General Public License version 2, as
00014  * published by the Free Software Foundation.
00015  *
00016  * This program is distributed in the hope that it will be useful,
00017  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  * GNU General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU General Public License
00022  * along with this program; if not, write to the Free Software
00023  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00024  *
00025  * $Id: v22bis.h,v 1.25 2007/12/13 11:31:33 steveu Exp $
00026  */
00027 
00028 /*! \file */
00029 
00030 /*! \page v22bis_page The V.22bis modem
00031 \section v22bis_page_sec_1 What does it do?
00032 The V.22bis modem is a duplex modem for general data use on the PSTN, at rates
00033 of 1200 and 2400 bits/second. It is a compatible extension of the V.22 modem,
00034 which is a 1200 bits/second only design. It is a band-split design, using carriers
00035 of 1200Hz and 2400Hz. It is the fastest PSTN modem in general use which does not
00036 use echo-cancellation.
00037 
00038 \section v22bis__page_sec_2 How does it work?
00039 V.22bis uses 4PSK modulation at 1200 bits/second or 16QAM modulation at 2400
00040 bits/second. At 1200bps the symbols are so long that a fixed compromise equaliser
00041 is sufficient to recover the 4PSK signal reliably. At 2400bps an adaptive
00042 equaliser is necessary.
00043 
00044 The V.22bis training sequence includes sections which allow the modems to determine
00045 if the far modem can support (or is willing to support) 2400bps operation. The
00046 modems will automatically use 2400bps if both ends are willing to use that speed,
00047 or 1200bps if one or both ends to not acknowledge that 2400bps is OK.
00048 */
00049 
00050 #if !defined(_V22BIS_H_)
00051 #define _V22BIS_H_
00052 
00053 #define V22BIS_EQUALIZER_LEN    7  /* this much to the left and this much to the right */
00054 #define V22BIS_EQUALIZER_MASK   15 /* one less than a power of 2 >= (2*V22BIS_EQUALIZER_LEN + 1) */
00055 
00056 #define V22BIS_TX_FILTER_STEPS  9
00057 
00058 #define V22BIS_RX_FILTER_STEPS  37
00059 
00060 /*!
00061     V.22bis modem receive side descriptor. This defines the working state for a
00062     single instance of a V.22bis modem receiver.
00063 */
00064 typedef struct
00065 {
00066     /*! \brief The bit rate of the modem. Valid values are 1200 and 2400. */
00067     int bit_rate;
00068     /*! \brief TRUE is this is the calling side modem. */
00069     int caller;
00070     /*! \brief The callback function used to put each bit received. */
00071     put_bit_func_t put_bit;
00072     /*! \brief The callback function used to get the next bit to be transmitted. */
00073     get_bit_func_t get_bit;
00074     /*! \brief A user specified opaque pointer passed to the callback routines. */
00075     void *user_data;
00076 
00077     /* RECEIVE SECTION */
00078 
00079     /*! \brief A callback function which may be enabled to report every symbol's
00080                constellation position. */
00081     qam_report_handler_t *qam_report;
00082     /*! \brief A user specified opaque pointer passed to the qam_report callback
00083                routine. */
00084     void *qam_user_data;
00085 
00086     /*! \brief The route raised cosine (RRC) pulse shaping filter buffer. */
00087     float rx_rrc_filter[2*V22BIS_RX_FILTER_STEPS];
00088     /*! \brief Current offset into the RRC pulse shaping filter buffer. */
00089     int rx_rrc_filter_step;
00090 
00091     /*! \brief The register for the data scrambler. */
00092     unsigned int rx_scramble_reg;
00093     /*! \brief A counter for the number of consecutive bits of repeating pattern through
00094                the scrambler. */
00095     int rx_scrambler_pattern_count;
00096     /*! \brief 0 if receiving user data. A training stage value during training */
00097     int rx_training;
00098     /*! \brief A count of how far through the current training step we are. */
00099     int rx_training_count;
00100     /*! \brief A measure of how much mismatch there is between the real constellation,
00101         and the decoded symbol positions. */
00102     float training_error;
00103     /*! \brief >0 if a signal above the minimum is present. It may or may not be a V.22bis signal. */
00104     int signal_present;
00105 
00106     /*! \brief The current phase of the carrier (i.e. the DDS parameter). */
00107     uint32_t rx_carrier_phase;
00108     /*! \brief The update rate for the phase of the carrier (i.e. the DDS increment). */
00109     int32_t rx_carrier_phase_rate;
00110     /*! \brief The proportional part of the carrier tracking filter. */
00111     float carrier_track_p;
00112     /*! \brief The integral part of the carrier tracking filter. */
00113     float carrier_track_i;
00114 
00115     /*! \brief A power meter, to measure the HPF'ed signal power in the channel. */    
00116     power_meter_t rx_power;
00117     /*! \brief The power meter level at which carrier on is declared. */
00118     int32_t carrier_on_power;
00119     /*! \brief The power meter level at which carrier off is declared. */
00120     int32_t carrier_off_power;
00121     /*! \brief The scaling factor accessed by the AGC algorithm. */
00122     float agc_scaling;
00123     
00124     int rx_constellation_state;
00125 
00126     /*! \brief The current delta factor for updating the equalizer coefficients. */
00127     float eq_delta;
00128 #if defined(SPANDSP_USE_FIXED_POINTx)
00129     /*! \brief The adaptive equalizer coefficients. */
00130     complexi_t eq_coeff[2*V22BIS_EQUALIZER_LEN + 1];
00131     /*! \brief The equalizer signal buffer. */
00132     complexi_t eq_buf[V22BIS_EQUALIZER_MASK + 1];
00133 #else
00134     complexf_t eq_coeff[2*V22BIS_EQUALIZER_LEN + 1];
00135     complexf_t eq_buf[V22BIS_EQUALIZER_MASK + 1];
00136 #endif
00137     /*! \brief Current offset into the equalizer buffer. */
00138     int eq_step;
00139     /*! \brief Current write offset into the equalizer buffer. */
00140     int eq_put_step;
00141 
00142     /*! \brief Integration variable for damping the Gardner algorithm tests. */
00143     int gardner_integrate;
00144     /*! \brief Current step size of Gardner algorithm integration. */
00145     int gardner_step;
00146     /*! \brief The total symbol timing correction since the carrier came up.
00147                This is only for performance analysis purposes. */
00148     int total_baud_timing_correction;
00149     /*! \brief The current fractional phase of the baud timing. */
00150     int rx_baud_phase;
00151     
00152     int sixteen_way_decisions;
00153 
00154     /* TRANSMIT SECTION */
00155 
00156     /*! \brief The gain factor needed to achieve the specified output power. */
00157     float tx_gain;
00158 
00159     /*! \brief The route raised cosine (RRC) pulse shaping filter buffer. */
00160     complexf_t tx_rrc_filter[2*V22BIS_TX_FILTER_STEPS];
00161     /*! \brief Current offset into the RRC pulse shaping filter buffer. */
00162     int tx_rrc_filter_step;
00163 
00164     /*! \brief The register for the data scrambler. */
00165     unsigned int tx_scramble_reg;
00166     /*! \brief A counter for the number of consecutive bits of repeating pattern through
00167                the scrambler. */
00168     int tx_scrambler_pattern_count;
00169     /*! \brief 0 if transmitting user data. A training stage value during training */
00170     int tx_training;
00171     /*! \brief A counter used to track progress through sending the training sequence. */
00172     int tx_training_count;
00173 
00174     /*! \brief The current phase of the carrier (i.e. the DDS parameter). */
00175     uint32_t tx_carrier_phase;
00176     /*! \brief The update rate for the phase of the carrier (i.e. the DDS increment). */
00177     int32_t tx_carrier_phase_rate;
00178     /*! \brief The current phase of the guard tone (i.e. the DDS parameter). */
00179     uint32_t guard_phase;
00180     /*! \brief The update rate for the phase of the guard tone (i.e. the DDS increment). */
00181     int32_t guard_phase_rate;
00182     float guard_level;
00183     /*! \brief The current fractional phase of the baud timing. */
00184     int tx_baud_phase;
00185     /*! \brief The code number for the current position in the constellation. */
00186     int tx_constellation_state;
00187     /*! \brief An indicator to mark that we are tidying up to stop transmission. */
00188     int shutdown;
00189     /*! \brief The get_bit function in use at any instant. */
00190     get_bit_func_t current_get_bit;
00191     
00192     int detected_unscrambled_ones;
00193     int detected_unscrambled_zeros;
00194 
00195     int detected_unscrambled_ones_or_zeros;
00196     int detected_unscrambled_0011_ending;
00197     int detected_scrambled_ones_or_zeros_at_1200bps;
00198     int detected_scrambled_ones_at_2400bps;
00199 
00200     /*! \brief Error and flow logging control */
00201     logging_state_t logging;
00202 } v22bis_state_t;
00203 
00204 extern const complexf_t v22bis_constellation[16];
00205 
00206 #if defined(__cplusplus)
00207 extern "C"
00208 {
00209 #endif
00210 
00211 /*! Reinitialise an existing V.22bis modem receive context.
00212     \brief Reinitialise an existing V.22bis modem receive context.
00213     \param s The modem context.
00214     \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400.
00215     \return 0 for OK, -1 for bad parameter */
00216 int v22bis_rx_restart(v22bis_state_t *s, int bit_rate);
00217 
00218 /*! Process a block of received V.22bis modem audio samples.
00219     \brief Process a block of received V.22bis modem audio samples.
00220     \param s The modem context.
00221     \param amp The audio sample buffer.
00222     \param len The number of samples in the buffer.
00223     \return The number of samples unprocessed. */
00224 int v22bis_rx(v22bis_state_t *s, const int16_t amp[], int len);
00225 
00226 /*! Get a snapshot of the current equalizer coefficients.
00227     \brief Get a snapshot of the current equalizer coefficients.
00228     \param coeffs The vector of complex coefficients.
00229     \return The number of coefficients in the vector. */
00230 int v22bis_rx_equalizer_state(v22bis_state_t *s, complexf_t **coeffs);
00231 
00232 /*! Get the current received carrier frequency.
00233     \param s The modem context.
00234     \return The frequency, in Hertz. */
00235 float v22bis_rx_carrier_frequency(v22bis_state_t *s);
00236 
00237 /*! Get the current symbol timing correction since startup.
00238     \param s The modem context.
00239     \return The correction. */
00240 float v22bis_rx_symbol_timing_correction(v22bis_state_t *s);
00241 
00242 /*! Get a current received signal power.
00243     \param s The modem context.
00244     \return The signal power, in dBm0. */
00245 float v22bis_rx_signal_power(v22bis_state_t *s);
00246 
00247 /*! Set a handler routine to process QAM status reports
00248     \param s The modem context.
00249     \param handler The handler routine.
00250     \param user_data An opaque pointer passed to the handler routine. */
00251 void v22bis_rx_set_qam_report_handler(v22bis_state_t *s, qam_report_handler_t *handler, void *user_data);
00252 
00253 /*! Generate a block of V.22bis modem audio samples.
00254     \brief Generate a block of V.22bis modem audio samples.
00255     \param s The modem context.
00256     \param amp The audio sample buffer.
00257     \param len The number of samples to be generated.
00258     \return The number of samples actually generated. */
00259 int v22bis_tx(v22bis_state_t *s, int16_t amp[], int len);
00260 
00261 /*! Adjust a V.22bis modem transmit context's power output.
00262     \brief Adjust a V.22bis modem transmit context's output power.
00263     \param s The modem context.
00264     \param power The power level, in dBm0 */
00265 void v22bis_tx_power(v22bis_state_t *s, float power);
00266 
00267 /*! Reinitialise an existing V.22bis modem context, so it may be reused.
00268     \brief Reinitialise an existing V.22bis modem context.
00269     \param s The modem context.
00270     \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400.
00271     \return 0 for OK, -1 for bad parameter. */
00272 int v22bis_restart(v22bis_state_t *s, int bit_rate);
00273 
00274 /*! Initialise a V.22bis modem context. This must be called before the first
00275     use of the context, to initialise its contents.
00276     \brief Initialise a V.22bis modem context.
00277     \param s The modem context.
00278     \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400.
00279     \param guard The guard tone option. 0 = none, 1 = 550Hz, 2 = 1800Hz.
00280     \param caller TRUE if this is the calling modem.
00281     \param get_bit The callback routine used to get the data to be transmitted.
00282     \param put_bit The callback routine used to get the data to be transmitted.
00283     \param user_data An opaque pointer, passed in calls to the get and put routines.
00284     \return A pointer to the modem context, or NULL if there was a problem. */
00285 v22bis_state_t *v22bis_init(v22bis_state_t *s,
00286                             int bit_rate,
00287                             int guard,
00288                             int caller,
00289                             get_bit_func_t get_bit,
00290                             put_bit_func_t put_bit,
00291                             void *user_data);
00292 
00293 /*! Change the get_bit function associated with a V.2bis modem context.
00294     \brief Change the get_bit function associated with a V.22bis modem context.
00295     \param s The modem context.
00296     \param get_bit The callback routine used to get the data to be transmitted.
00297     \param user_data An opaque pointer. */
00298 void v22bis_set_get_bit(v22bis_state_t *s, get_bit_func_t get_bit, void *user_data);
00299 
00300 /*! Change the get_bit function associated with a V.2bis modem context.
00301     \brief Change the put_bit function associated with a V.22bis modem context.
00302     \param s The modem context.
00303     \param put_bit The callback routine used to process the data received.
00304     \param user_data An opaque pointer. */
00305 void v22bis_set_put_bit(v22bis_state_t *s, put_bit_func_t put_bit, void *user_data);
00306 
00307 #if defined(__cplusplus)
00308 }
00309 #endif
00310 
00311 #endif
00312 /*- End of file ------------------------------------------------------------*/

Generated on Wed Apr 16 02:37:06 2008 for libspandsp by  doxygen 1.5.1