spandsp 0.0.6
private/v22bis.h
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * private/v22bis.h - ITU V.22bis modem
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 Lesser General Public License version 2.1,
00014  * as 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 Lesser General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU Lesser General Public
00022  * License along with this program; if not, write to the Free Software
00023  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00024  */
00025 
00026 #if !defined(_SPANDSP_PRIVATE_V22BIS_H_)
00027 #define _SPANDSP_PRIVATE_V22BIS_H_
00028 
00029 /*! The number of steps to the left and to the right of the target position in the equalizer buffer. */
00030 #define V22BIS_EQUALIZER_LEN    7
00031 /*! One less than a power of 2 >= (2*V22BIS_EQUALIZER_LEN + 1) */
00032 #define V22BIS_EQUALIZER_MASK   15
00033 
00034 /*! The number of taps in the transmit pulse shaping filter */
00035 #define V22BIS_TX_FILTER_STEPS  9
00036 
00037 /*! The number of taps in the receive pulse shaping/bandpass filter */
00038 #define V22BIS_RX_FILTER_STEPS  27
00039 
00040 /*! Segments of the training sequence on the receive side */
00041 enum
00042 {
00043     V22BIS_RX_TRAINING_STAGE_NORMAL_OPERATION,
00044     V22BIS_RX_TRAINING_STAGE_SYMBOL_ACQUISITION,
00045     V22BIS_RX_TRAINING_STAGE_LOG_PHASE,
00046     V22BIS_RX_TRAINING_STAGE_UNSCRAMBLED_ONES,
00047     V22BIS_RX_TRAINING_STAGE_UNSCRAMBLED_ONES_SUSTAINING,
00048     V22BIS_RX_TRAINING_STAGE_SCRAMBLED_ONES_AT_1200,
00049     V22BIS_RX_TRAINING_STAGE_SCRAMBLED_ONES_AT_1200_SUSTAINING,
00050     V22BIS_RX_TRAINING_STAGE_WAIT_FOR_SCRAMBLED_ONES_AT_2400,
00051     V22BIS_RX_TRAINING_STAGE_PARKED
00052 };
00053 
00054 /*! Segments of the training sequence on the transmit side */
00055 enum
00056 {
00057     V22BIS_TX_TRAINING_STAGE_NORMAL_OPERATION = 0,
00058     V22BIS_TX_TRAINING_STAGE_INITIAL_TIMED_SILENCE,
00059     V22BIS_TX_TRAINING_STAGE_INITIAL_SILENCE,
00060     V22BIS_TX_TRAINING_STAGE_U11,
00061     V22BIS_TX_TRAINING_STAGE_U0011,
00062     V22BIS_TX_TRAINING_STAGE_S11,
00063     V22BIS_TX_TRAINING_STAGE_TIMED_S11,
00064     V22BIS_TX_TRAINING_STAGE_S1111,
00065     V22BIS_TX_TRAINING_STAGE_PARKED
00066 };
00067 
00068 /*!
00069     V.22bis modem descriptor. This defines the working state for a single instance
00070     of a V.22bis modem.
00071 */
00072 struct v22bis_state_s
00073 {
00074     /*! \brief The maximum permitted bit rate of the modem. Valid values are 1200 and 2400. */
00075     int bit_rate;
00076     /*! \brief TRUE is this is the calling side modem. */
00077     int calling_party;
00078     /*! \brief The callback function used to get the next bit to be transmitted. */
00079     get_bit_func_t get_bit;
00080     /*! \brief A user specified opaque pointer passed to the get_bit callback routine. */
00081     void *get_bit_user_data;
00082     /*! \brief The callback function used to put each bit received. */
00083     put_bit_func_t put_bit;
00084     /*! \brief A user specified opaque pointer passed to the put_bit callback routine. */
00085     void *put_bit_user_data;
00086     /*! \brief The callback function used to report modem status changes. */
00087     modem_rx_status_func_t status_handler;
00088     /*! \brief A user specified opaque pointer passed to the status function. */
00089     void *status_user_data;
00090 
00091     int negotiated_bit_rate;
00092 
00093     /* Receive section */
00094     struct
00095     {
00096         /*! \brief The route raised cosine (RRC) pulse shaping filter buffer. */
00097 #if defined(SPANDSP_USE_FIXED_POINTx)
00098         int16_t rrc_filter[V22BIS_RX_FILTER_STEPS];
00099 #else
00100         float rrc_filter[V22BIS_RX_FILTER_STEPS];
00101 #endif
00102         /*! \brief Current offset into the RRC pulse shaping filter buffer. */
00103         int rrc_filter_step;
00104 
00105         /*! \brief The register for the data scrambler. */
00106         uint32_t scramble_reg;
00107         /*! \brief A counter for the number of consecutive bits of repeating pattern through
00108                    the scrambler. */
00109         int scrambler_pattern_count;
00110 
00111         /*! \brief 0 if receiving user data. A training stage value during training */
00112         int training;
00113         /*! \brief A count of how far through the current training step we are. */
00114         int training_count;
00115 
00116         /*! \brief >0 if a signal above the minimum is present. It may or may not be a V.22bis signal. */
00117         int signal_present;
00118 
00119         /*! \brief A measure of how much mismatch there is between the real constellation,
00120             and the decoded symbol positions. */
00121         float training_error;
00122 
00123         /*! \brief The current phase of the carrier (i.e. the DDS parameter). */
00124         uint32_t carrier_phase;
00125         /*! \brief The update rate for the phase of the carrier (i.e. the DDS increment). */
00126         int32_t carrier_phase_rate;
00127         /*! \brief The proportional part of the carrier tracking filter. */
00128         float carrier_track_p;
00129         /*! \brief The integral part of the carrier tracking filter. */
00130         float carrier_track_i;
00131         
00132         /*! \brief A callback function which may be enabled to report every symbol's
00133                    constellation position. */
00134         qam_report_handler_t qam_report;
00135         /*! \brief A user specified opaque pointer passed to the qam_report callback
00136                    routine. */
00137         void *qam_user_data;
00138 
00139         /*! \brief A power meter, to measure the HPF'ed signal power in the channel. */    
00140         power_meter_t rx_power;
00141         /*! \brief The power meter level at which carrier on is declared. */
00142         int32_t carrier_on_power;
00143         /*! \brief The power meter level at which carrier off is declared. */
00144         int32_t carrier_off_power;
00145         /*! \brief The scaling factor accessed by the AGC algorithm. */
00146         float agc_scaling;
00147     
00148         int constellation_state;
00149 
00150         /*! \brief The current delta factor for updating the equalizer coefficients. */
00151         float eq_delta;
00152 #if defined(SPANDSP_USE_FIXED_POINTx)
00153         /*! \brief The adaptive equalizer coefficients. */
00154         complexi_t eq_coeff[2*V22BIS_EQUALIZER_LEN + 1];
00155         /*! \brief The equalizer signal buffer. */
00156         complexi_t eq_buf[V22BIS_EQUALIZER_MASK + 1];
00157 #else
00158         complexf_t eq_coeff[2*V22BIS_EQUALIZER_LEN + 1];
00159         complexf_t eq_buf[V22BIS_EQUALIZER_MASK + 1];
00160 #endif
00161         /*! \brief Current offset into the equalizer buffer. */
00162         int eq_step;
00163         /*! \brief Current write offset into the equalizer buffer. */
00164         int eq_put_step;
00165 
00166         /*! \brief Integration variable for damping the Gardner algorithm tests. */
00167         int gardner_integrate;
00168         /*! \brief Current step size of Gardner algorithm integration. */
00169         int gardner_step;
00170         /*! \brief The total symbol timing correction since the carrier came up.
00171                    This is only for performance analysis purposes. */
00172         int total_baud_timing_correction;
00173         /*! \brief The current fractional phase of the baud timing. */
00174         int baud_phase;
00175     
00176         int sixteen_way_decisions;
00177 
00178         int pattern_repeats;
00179         int last_raw_bits;
00180     } rx;
00181 
00182     /* Transmit section */
00183     struct
00184     {
00185         /*! \brief The gain factor needed to achieve the specified output power. */
00186         float gain;
00187 
00188         /*! \brief The route raised cosine (RRC) pulse shaping filter buffer. */
00189         complexf_t rrc_filter[2*V22BIS_TX_FILTER_STEPS];
00190         /*! \brief Current offset into the RRC pulse shaping filter buffer. */
00191         int rrc_filter_step;
00192 
00193         /*! \brief The register for the data scrambler. */
00194         unsigned int scramble_reg;
00195         /*! \brief A counter for the number of consecutive bits of repeating pattern through
00196                    the scrambler. */
00197         int scrambler_pattern_count;
00198 
00199         /*! \brief 0 if transmitting user data. A training stage value during training */
00200         int training;
00201         /*! \brief A counter used to track progress through sending the training sequence. */
00202         int training_count;
00203         /*! \brief The current phase of the carrier (i.e. the DDS parameter). */
00204         uint32_t carrier_phase;
00205         /*! \brief The update rate for the phase of the carrier (i.e. the DDS increment). */
00206         int32_t carrier_phase_rate;
00207         /*! \brief The current phase of the guard tone (i.e. the DDS parameter). */
00208         uint32_t guard_phase;
00209         /*! \brief The update rate for the phase of the guard tone (i.e. the DDS increment). */
00210         int32_t guard_phase_rate;
00211         float guard_level;
00212         /*! \brief The current fractional phase of the baud timing. */
00213         int baud_phase;
00214         /*! \brief The code number for the current position in the constellation. */
00215         int constellation_state;
00216         /*! \brief An indicator to mark that we are tidying up to stop transmission. */
00217         int shutdown;
00218         /*! \brief The get_bit function in use at any instant. */
00219         get_bit_func_t current_get_bit;
00220     } tx;
00221 
00222     /*! \brief Error and flow logging control */
00223     logging_state_t logging;
00224 };
00225 
00226 #if defined(__cplusplus)
00227 extern "C"
00228 {
00229 #endif
00230 
00231 /*! Reinitialise an existing V.22bis modem receive context.
00232     \brief Reinitialise an existing V.22bis modem receive context.
00233     \param s The modem context.
00234     \return 0 for OK, -1 for bad parameter */
00235 int v22bis_rx_restart(v22bis_state_t *s);
00236 
00237 void v22bis_report_status_change(v22bis_state_t *s, int status);
00238 
00239 void v22bis_equalizer_coefficient_reset(v22bis_state_t *s);
00240 
00241 #if defined(__cplusplus)
00242 }
00243 #endif
00244 
00245 #endif
00246 /*- End of file ------------------------------------------------------------*/