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
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  * $Id: v22bis.h,v 1.42 2009/04/29 12:37:45 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(_SPANDSP_V22BIS_H_)
00051 #define _SPANDSP_V22BIS_H_
00052 
00053 enum
00054 {
00055     V22BIS_GUARD_TONE_NONE,
00056     V22BIS_GUARD_TONE_550HZ,
00057     V22BIS_GUARD_TONE_1800HZ
00058 };
00059 
00060 /*! The number of steps to the left and to the right of the target position in the equalizer buffer. */
00061 #define V22BIS_EQUALIZER_LEN    7
00062 /*! One less than a power of 2 >= (2*V22BIS_EQUALIZER_LEN + 1) */
00063 #define V22BIS_EQUALIZER_MASK   15
00064 
00065 /*! The number of taps in the transmit pulse shaping filter */
00066 #define V22BIS_TX_FILTER_STEPS  9
00067 
00068 /*! The number of taps in the receive pulse shaping/bandpass filter */
00069 #define V22BIS_RX_FILTER_STEPS  37
00070 
00071 /*!
00072     V.22bis modem descriptor. This defines the working state for a single instance
00073     of a V.22bis modem.
00074 */
00075 typedef struct v22bis_state_s v22bis_state_t;
00076 
00077 extern const complexf_t v22bis_constellation[16];
00078 
00079 #if defined(__cplusplus)
00080 extern "C"
00081 {
00082 #endif
00083 
00084 /*! Process a block of received V.22bis modem audio samples.
00085     \brief Process a block of received V.22bis modem audio samples.
00086     \param s The modem context.
00087     \param amp The audio sample buffer.
00088     \param len The number of samples in the buffer.
00089     \return The number of samples unprocessed. */
00090 SPAN_DECLARE(int) v22bis_rx(v22bis_state_t *s, const int16_t amp[], int len);
00091 
00092 /*! Fake processing of a missing block of received V.22bis modem audio samples.
00093     (e.g due to packet loss).
00094     \brief Fake processing of a missing block of received V.22bis modem audio samples.
00095     \param s The modem context.
00096     \param len The number of samples to fake.
00097     \return The number of samples unprocessed. */
00098 SPAN_DECLARE(int) v22bis_rx_fillin(v22bis_state_t *s, int len);
00099 
00100 /*! Get a snapshot of the current equalizer coefficients.
00101     \brief Get a snapshot of the current equalizer coefficients.
00102     \param coeffs The vector of complex coefficients.
00103     \return The number of coefficients in the vector. */
00104 SPAN_DECLARE(int) v22bis_rx_equalizer_state(v22bis_state_t *s, complexf_t **coeffs);
00105 
00106 /*! Get the current received carrier frequency.
00107     \param s The modem context.
00108     \return The frequency, in Hertz. */
00109 SPAN_DECLARE(float) v22bis_rx_carrier_frequency(v22bis_state_t *s);
00110 
00111 /*! Get the current symbol timing correction since startup.
00112     \param s The modem context.
00113     \return The correction. */
00114 SPAN_DECLARE(float) v22bis_rx_symbol_timing_correction(v22bis_state_t *s);
00115 
00116 /*! Get a current received signal power.
00117     \param s The modem context.
00118     \return The signal power, in dBm0. */
00119 SPAN_DECLARE(float) v22bis_rx_signal_power(v22bis_state_t *s);
00120 
00121 /*! Set the power level at which the carrier detection will cut in
00122     \param s The modem context.
00123     \param cutoff The signal cutoff power, in dBm0. */
00124 SPAN_DECLARE(void) v22bis_rx_signal_cutoff(v22bis_state_t *s, float cutoff);
00125 
00126 /*! Set a handler routine to process QAM status reports
00127     \param s The modem context.
00128     \param handler The handler routine.
00129     \param user_data An opaque pointer passed to the handler routine. */
00130 SPAN_DECLARE(void) v22bis_rx_set_qam_report_handler(v22bis_state_t *s, qam_report_handler_t handler, void *user_data);
00131 
00132 /*! Generate a block of V.22bis modem audio samples.
00133     \brief Generate a block of V.22bis modem audio samples.
00134     \param s The modem context.
00135     \param amp The audio sample buffer.
00136     \param len The number of samples to be generated.
00137     \return The number of samples actually generated. */
00138 SPAN_DECLARE(int) v22bis_tx(v22bis_state_t *s, int16_t amp[], int len);
00139 
00140 /*! Adjust a V.22bis modem transmit context's power output.
00141     \brief Adjust a V.22bis modem transmit context's output power.
00142     \param s The modem context.
00143     \param power The power level, in dBm0 */
00144 SPAN_DECLARE(void) v22bis_tx_power(v22bis_state_t *s, float power);
00145 
00146 /*! Reinitialise an existing V.22bis modem context, so it may be reused.
00147     \brief Reinitialise an existing V.22bis modem context.
00148     \param s The modem context.
00149     \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400.
00150     \return 0 for OK, -1 for bad parameter. */
00151 SPAN_DECLARE(int) v22bis_restart(v22bis_state_t *s, int bit_rate);
00152 
00153 /*! Request a retrain for a V.22bis modem context. A rate change may also be requested.
00154     \brief Request a retrain for a V.22bis modem context.
00155     \param s The modem context.
00156     \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400.
00157     \return 0 for OK, -1 for request rejected. */
00158 SPAN_DECLARE(int) v22bis_request_retrain(v22bis_state_t *s, int bit_rate);
00159 
00160 /*! Request a loopback 2 for a V.22bis modem context.
00161     \brief Request a loopback 2 for a V.22bis modem context.
00162     \param s The modem context.
00163     \param enable TRUE to enable loopback, or FALSE to disable it.
00164     \return 0 for OK, -1 for request reject. */
00165 SPAN_DECLARE(int) v22bis_remote_loopback(v22bis_state_t *s, int enable);
00166 
00167 /*! Report the current operating bit rate of a V.22bis modem context.
00168     \brief Report the current operating bit rate of a V.22bis modem context
00169     \param s The modem context. */
00170 SPAN_DECLARE(int) v22bis_current_bit_rate(v22bis_state_t *s);
00171 
00172 /*! Initialise a V.22bis modem context. This must be called before the first
00173     use of the context, to initialise its contents.
00174     \brief Initialise a V.22bis modem context.
00175     \param s The modem context.
00176     \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400.
00177     \param guard The guard tone option. 0 = none, 1 = 550Hz, 2 = 1800Hz.
00178     \param caller TRUE if this is the calling modem.
00179     \param get_bit The callback routine used to get the data to be transmitted.
00180     \param put_bit The callback routine used to get the data to be transmitted.
00181     \param user_data An opaque pointer, passed in calls to the get and put routines.
00182     \return A pointer to the modem context, or NULL if there was a problem. */
00183 SPAN_DECLARE(v22bis_state_t *) v22bis_init(v22bis_state_t *s,
00184                                            int bit_rate,
00185                                            int guard,
00186                                            int caller,
00187                                            get_bit_func_t get_bit,
00188                                            void *get_bit_user_data,
00189                                            put_bit_func_t put_bit,
00190                                            void *put_bit_user_data);
00191 
00192 /*! Release a V.22bis modem receive context.
00193     \brief Release a V.22bis modem receive context.
00194     \param s The modem context.
00195     \return 0 for OK */
00196 SPAN_DECLARE(int) v22bis_release(v22bis_state_t *s);
00197 
00198 /*! Free a V.22bis modem receive context.
00199     \brief Free a V.22bis modem receive context.
00200     \param s The modem context.
00201     \return 0 for OK */
00202 SPAN_DECLARE(int) v22bis_free(v22bis_state_t *s);
00203 
00204 /*! Get the logging context associated with a V.22bis modem context.
00205     \brief Get the logging context associated with a V.22bis modem context.
00206     \param s The modem context.
00207     \return A pointer to the logging context */
00208 SPAN_DECLARE(logging_state_t *) v22bis_get_logging_state(v22bis_state_t *s);
00209 
00210 /*! Change the get_bit function associated with a V.22bis modem context.
00211     \brief Change the get_bit function associated with a V.22bis modem context.
00212     \param s The modem context.
00213     \param get_bit The callback routine used to get the data to be transmitted.
00214     \param user_data An opaque pointer. */
00215 SPAN_DECLARE(void) v22bis_set_get_bit(v22bis_state_t *s, get_bit_func_t get_bit, void *user_data);
00216 
00217 /*! Change the get_bit function associated with a V.22bis modem context.
00218     \brief Change the put_bit function associated with a V.22bis modem context.
00219     \param s The modem context.
00220     \param put_bit The callback routine used to process the data received.
00221     \param user_data An opaque pointer. */
00222 SPAN_DECLARE(void) v22bis_set_put_bit(v22bis_state_t *s, put_bit_func_t put_bit, void *user_data);
00223 
00224 /*! Change the modem status report function associated with a V.22bis modem receive context.
00225     \brief Change the modem status report function associated with a V.22bis modem receive context.
00226     \param s The modem context.
00227     \param handler The callback routine used to report modem status changes.
00228     \param user_data An opaque pointer. */
00229 SPAN_DECLARE(void) v22bis_set_modem_status_handler(v22bis_state_t *s, modem_rx_status_func_t handler, void *user_data);
00230 
00231 #if defined(__cplusplus)
00232 }
00233 #endif
00234 
00235 #endif
00236 /*- End of file ------------------------------------------------------------*/

Generated on Tue Aug 4 03:36:14 2009 for spandsp by  doxygen 1.5.9