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 00026 /*! \file */ 00027 00028 /*! \page v22bis_page The V.22bis modem 00029 \section v22bis_page_sec_1 What does it do? 00030 The V.22bis modem is a duplex modem for general data use on the PSTN, at rates 00031 of 1200 and 2400 bits/second. It is a compatible extension of the V.22 modem, 00032 which is a 1200 bits/second only design. It is a band-split design, using carriers 00033 of 1200Hz and 2400Hz. It is the fastest PSTN modem in general use which does not 00034 use echo-cancellation. 00035 00036 \section v22bis__page_sec_2 How does it work? 00037 V.22bis uses 4PSK modulation at 1200 bits/second or 16QAM modulation at 2400 00038 bits/second. At 1200bps the symbols are so long that a fixed compromise equaliser 00039 is sufficient to recover the 4PSK signal reliably. At 2400bps an adaptive 00040 equaliser is necessary. 00041 00042 The V.22bis training sequence includes sections which allow the modems to determine 00043 if the far modem can support (or is willing to support) 2400bps operation. The 00044 modems will automatically use 2400bps if both ends are willing to use that speed, 00045 or 1200bps if one or both ends to not acknowledge that 2400bps is OK. 00046 */ 00047 00048 #if !defined(_SPANDSP_V22BIS_H_) 00049 #define _SPANDSP_V22BIS_H_ 00050 00051 #if defined(SPANDSP_USE_FIXED_POINT) 00052 #define V22BIS_CONSTELLATION_SCALING_FACTOR 1024.0 00053 #else 00054 #define V22BIS_CONSTELLATION_SCALING_FACTOR 1.0 00055 #endif 00056 00057 enum 00058 { 00059 V22BIS_GUARD_TONE_NONE, 00060 V22BIS_GUARD_TONE_550HZ, 00061 V22BIS_GUARD_TONE_1800HZ 00062 }; 00063 00064 /*! 00065 V.22bis modem descriptor. This defines the working state for a single instance 00066 of a V.22bis modem. 00067 */ 00068 typedef struct v22bis_state_s v22bis_state_t; 00069 00070 #if defined(__cplusplus) 00071 extern "C" 00072 { 00073 #endif 00074 00075 /*! Process a block of received V.22bis modem audio samples. 00076 \brief Process a block of received V.22bis modem audio samples. 00077 \param s The modem context. 00078 \param amp The audio sample buffer. 00079 \param len The number of samples in the buffer. 00080 \return The number of samples unprocessed. */ 00081 SPAN_DECLARE_NONSTD(int) v22bis_rx(v22bis_state_t *s, const int16_t amp[], int len); 00082 00083 /*! Fake processing of a missing block of received V.22bis modem audio samples. 00084 (e.g due to packet loss). 00085 \brief Fake processing of a missing block of received V.22bis modem audio samples. 00086 \param s The modem context. 00087 \param len The number of samples to fake. 00088 \return The number of samples unprocessed. */ 00089 SPAN_DECLARE_NONSTD(int) v22bis_rx_fillin(v22bis_state_t *s, int len); 00090 00091 /*! Get a snapshot of the current equalizer coefficients. 00092 \brief Get a snapshot of the current equalizer coefficients. 00093 \param coeffs The vector of complex coefficients. 00094 \return The number of coefficients in the vector. */ 00095 #if defined(SPANDSP_USE_FIXED_POINT) 00096 SPAN_DECLARE(int) v22bis_rx_equalizer_state(v22bis_state_t *s, complexi16_t **coeffs); 00097 #else 00098 SPAN_DECLARE(int) v22bis_rx_equalizer_state(v22bis_state_t *s, complexf_t **coeffs); 00099 #endif 00100 00101 /*! Get the current received carrier frequency. 00102 \param s The modem context. 00103 \return The frequency, in Hertz. */ 00104 SPAN_DECLARE(float) v22bis_rx_carrier_frequency(v22bis_state_t *s); 00105 00106 /*! Get the current symbol timing correction since startup. 00107 \param s The modem context. 00108 \return The correction. */ 00109 SPAN_DECLARE(float) v22bis_rx_symbol_timing_correction(v22bis_state_t *s); 00110 00111 /*! Get a current received signal power. 00112 \param s The modem context. 00113 \return The signal power, in dBm0. */ 00114 SPAN_DECLARE(float) v22bis_rx_signal_power(v22bis_state_t *s); 00115 00116 /*! Set the power level at which the carrier detection will cut in 00117 \param s The modem context. 00118 \param cutoff The signal cutoff power, in dBm0. */ 00119 SPAN_DECLARE(void) v22bis_rx_signal_cutoff(v22bis_state_t *s, float cutoff); 00120 00121 /*! Set a handler routine to process QAM status reports 00122 \param s The modem context. 00123 \param handler The handler routine. 00124 \param user_data An opaque pointer passed to the handler routine. */ 00125 SPAN_DECLARE(void) v22bis_rx_set_qam_report_handler(v22bis_state_t *s, qam_report_handler_t handler, void *user_data); 00126 00127 /*! Generate a block of V.22bis modem audio samples. 00128 \brief Generate a block of V.22bis modem audio samples. 00129 \param s The modem context. 00130 \param amp The audio sample buffer. 00131 \param len The number of samples to be generated. 00132 \return The number of samples actually generated. */ 00133 SPAN_DECLARE_NONSTD(int) v22bis_tx(v22bis_state_t *s, int16_t amp[], int len); 00134 00135 /*! Adjust a V.22bis modem transmit context's power output. 00136 \brief Adjust a V.22bis modem transmit context's output power. 00137 \param s The modem context. 00138 \param power The power level, in dBm0 */ 00139 SPAN_DECLARE(void) v22bis_tx_power(v22bis_state_t *s, float power); 00140 00141 /*! Reinitialise an existing V.22bis modem context, so it may be reused. 00142 \brief Reinitialise an existing V.22bis modem context. 00143 \param s The modem context. 00144 \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400. 00145 \return 0 for OK, -1 for bad parameter. */ 00146 SPAN_DECLARE(int) v22bis_restart(v22bis_state_t *s, int bit_rate); 00147 00148 /*! Request a retrain for a V.22bis modem context. A rate change may also be requested. 00149 \brief Request a retrain for a V.22bis modem context. 00150 \param s The modem context. 00151 \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400. 00152 \return 0 for OK, -1 for request rejected. */ 00153 SPAN_DECLARE(int) v22bis_request_retrain(v22bis_state_t *s, int bit_rate); 00154 00155 /*! Request a loopback 2 for a V.22bis modem context. 00156 \brief Request a loopback 2 for a V.22bis modem context. 00157 \param s The modem context. 00158 \param enable TRUE to enable loopback, or FALSE to disable it. 00159 \return 0 for OK, -1 for request reject. */ 00160 SPAN_DECLARE(int) v22bis_remote_loopback(v22bis_state_t *s, int enable); 00161 00162 /*! Report the current operating bit rate of a V.22bis modem context. 00163 \brief Report the current operating bit rate of a V.22bis modem context 00164 \param s The modem context. */ 00165 SPAN_DECLARE(int) v22bis_get_current_bit_rate(v22bis_state_t *s); 00166 00167 /*! Initialise a V.22bis modem context. This must be called before the first 00168 use of the context, to initialise its contents. 00169 \brief Initialise a V.22bis modem context. 00170 \param s The modem context. 00171 \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400. 00172 \param guard The guard tone option. 0 = none, 1 = 550Hz, 2 = 1800Hz. 00173 \param calling_party TRUE if this is the calling modem. 00174 \param get_bit The callback routine used to get the data to be transmitted. 00175 \param put_bit The callback routine used to get the data to be transmitted. 00176 \param user_data An opaque pointer, passed in calls to the get and put routines. 00177 \return A pointer to the modem context, or NULL if there was a problem. */ 00178 SPAN_DECLARE(v22bis_state_t *) v22bis_init(v22bis_state_t *s, 00179 int bit_rate, 00180 int guard, 00181 int calling_party, 00182 get_bit_func_t get_bit, 00183 void *get_bit_user_data, 00184 put_bit_func_t put_bit, 00185 void *put_bit_user_data); 00186 00187 /*! Release a V.22bis modem receive context. 00188 \brief Release a V.22bis modem receive context. 00189 \param s The modem context. 00190 \return 0 for OK */ 00191 SPAN_DECLARE(int) v22bis_release(v22bis_state_t *s); 00192 00193 /*! Free a V.22bis modem receive context. 00194 \brief Free a V.22bis modem receive context. 00195 \param s The modem context. 00196 \return 0 for OK */ 00197 SPAN_DECLARE(int) v22bis_free(v22bis_state_t *s); 00198 00199 /*! Get the logging context associated with a V.22bis modem context. 00200 \brief Get the logging context associated with a V.22bis modem context. 00201 \param s The modem context. 00202 \return A pointer to the logging context */ 00203 SPAN_DECLARE(logging_state_t *) v22bis_get_logging_state(v22bis_state_t *s); 00204 00205 /*! Change the get_bit function associated with a V.22bis modem context. 00206 \brief Change the get_bit function associated with a V.22bis modem context. 00207 \param s The modem context. 00208 \param get_bit The callback routine used to get the data to be transmitted. 00209 \param user_data An opaque pointer. */ 00210 SPAN_DECLARE(void) v22bis_set_get_bit(v22bis_state_t *s, get_bit_func_t get_bit, void *user_data); 00211 00212 /*! Change the get_bit function associated with a V.22bis modem context. 00213 \brief Change the put_bit function associated with a V.22bis modem context. 00214 \param s The modem context. 00215 \param put_bit The callback routine used to process the data received. 00216 \param user_data An opaque pointer. */ 00217 SPAN_DECLARE(void) v22bis_set_put_bit(v22bis_state_t *s, put_bit_func_t put_bit, void *user_data); 00218 00219 /*! Change the modem status report function associated with a V.22bis modem receive context. 00220 \brief Change the modem status report function associated with a V.22bis modem receive context. 00221 \param s The modem context. 00222 \param handler The callback routine used to report modem status changes. 00223 \param user_data An opaque pointer. */ 00224 SPAN_DECLARE(void) v22bis_set_modem_status_handler(v22bis_state_t *s, modem_status_func_t handler, void *user_data); 00225 00226 #if defined(__cplusplus) 00227 } 00228 #endif 00229 00230 #endif 00231 /*- End of file ------------------------------------------------------------*/
1.6.1