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.32 2008/11/30 03:40:12 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 #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 descriptor. This defines the working state for a single instance 00062 of a V.22bis modem. 00063 */ 00064 typedef struct v22bis_state_s v22bis_state_t; 00065 00066 extern const complexf_t v22bis_constellation[16]; 00067 00068 #if defined(__cplusplus) 00069 extern "C" 00070 { 00071 #endif 00072 00073 /*! Reinitialise an existing V.22bis modem receive context. 00074 \brief Reinitialise an existing V.22bis modem receive context. 00075 \param s The modem context. 00076 \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400. 00077 \return 0 for OK, -1 for bad parameter */ 00078 int v22bis_rx_restart(v22bis_state_t *s, int bit_rate); 00079 00080 /*! Process a block of received V.22bis modem audio samples. 00081 \brief Process a block of received V.22bis modem audio samples. 00082 \param s The modem context. 00083 \param amp The audio sample buffer. 00084 \param len The number of samples in the buffer. 00085 \return The number of samples unprocessed. */ 00086 int v22bis_rx(v22bis_state_t *s, const int16_t amp[], int len); 00087 00088 /*! Get a snapshot of the current equalizer coefficients. 00089 \brief Get a snapshot of the current equalizer coefficients. 00090 \param coeffs The vector of complex coefficients. 00091 \return The number of coefficients in the vector. */ 00092 int v22bis_equalizer_state(v22bis_state_t *s, complexf_t **coeffs); 00093 00094 /*! Get the current received carrier frequency. 00095 \param s The modem context. 00096 \return The frequency, in Hertz. */ 00097 float v22bis_rx_carrier_frequency(v22bis_state_t *s); 00098 00099 /*! Get the current symbol timing correction since startup. 00100 \param s The modem context. 00101 \return The correction. */ 00102 float v22bis_symbol_timing_correction(v22bis_state_t *s); 00103 00104 /*! Get a current received signal power. 00105 \param s The modem context. 00106 \return The signal power, in dBm0. */ 00107 float v22bis_rx_signal_power(v22bis_state_t *s); 00108 00109 /*! Set a handler routine to process QAM status reports 00110 \param s The modem context. 00111 \param handler The handler routine. 00112 \param user_data An opaque pointer passed to the handler routine. */ 00113 void v22bis_set_qam_report_handler(v22bis_state_t *s, qam_report_handler_t handler, void *user_data); 00114 00115 /*! Generate a block of V.22bis modem audio samples. 00116 \brief Generate a block of V.22bis modem audio samples. 00117 \param s The modem context. 00118 \param amp The audio sample buffer. 00119 \param len The number of samples to be generated. 00120 \return The number of samples actually generated. */ 00121 int v22bis_tx(v22bis_state_t *s, int16_t amp[], int len); 00122 00123 /*! Adjust a V.22bis modem transmit context's power output. 00124 \brief Adjust a V.22bis modem transmit context's output power. 00125 \param s The modem context. 00126 \param power The power level, in dBm0 */ 00127 void v22bis_tx_power(v22bis_state_t *s, float power); 00128 00129 /*! Reinitialise an existing V.22bis modem context, so it may be reused. 00130 \brief Reinitialise an existing V.22bis modem context. 00131 \param s The modem context. 00132 \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400. 00133 \return 0 for OK, -1 for bad parameter. */ 00134 int v22bis_restart(v22bis_state_t *s, int bit_rate); 00135 00136 /*! Initialise a V.22bis modem context. This must be called before the first 00137 use of the context, to initialise its contents. 00138 \brief Initialise a V.22bis modem context. 00139 \param s The modem context. 00140 \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400. 00141 \param guard The guard tone option. 0 = none, 1 = 550Hz, 2 = 1800Hz. 00142 \param caller TRUE if this is the calling modem. 00143 \param get_bit The callback routine used to get the data to be transmitted. 00144 \param put_bit The callback routine used to get the data to be transmitted. 00145 \param user_data An opaque pointer, passed in calls to the get and put routines. 00146 \return A pointer to the modem context, or NULL if there was a problem. */ 00147 v22bis_state_t *v22bis_init(v22bis_state_t *s, 00148 int bit_rate, 00149 int guard, 00150 int caller, 00151 get_bit_func_t get_bit, 00152 put_bit_func_t put_bit, 00153 void *user_data); 00154 00155 /*! Free a V.22bis modem receive context. 00156 \brief Free a V.22bis modem receive context. 00157 \param s The modem context. 00158 \return 0 for OK */ 00159 int v22bis_free(v22bis_state_t *s); 00160 00161 logging_state_t *v22bis_get_logging_state(v22bis_state_t *s); 00162 00163 /*! Change the get_bit function associated with a V.22bis modem context. 00164 \brief Change the get_bit function associated with a V.22bis modem context. 00165 \param s The modem context. 00166 \param get_bit The callback routine used to get the data to be transmitted. 00167 \param user_data An opaque pointer. */ 00168 void v22bis_set_get_bit(v22bis_state_t *s, get_bit_func_t get_bit, void *user_data); 00169 00170 /*! Change the get_bit function associated with a V.22bis modem context. 00171 \brief Change the put_bit function associated with a V.22bis modem context. 00172 \param s The modem context. 00173 \param put_bit The callback routine used to process the data received. 00174 \param user_data An opaque pointer. */ 00175 void v22bis_set_put_bit(v22bis_state_t *s, put_bit_func_t put_bit, void *user_data); 00176 00177 #if defined(__cplusplus) 00178 } 00179 #endif 00180 00181 #endif 00182 /*- End of file ------------------------------------------------------------*/