Mercurial > hg > audiostuff

comparison spandsp-0.0.3/spandsp-0.0.3/src/spandsp/v22bis.h @ 5:f762bf195c4b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
import spandsp-0.0.3
author Peter Meerwald <pmeerw@cosy.sbg.ac.at>
date Fri, 25 Jun 2010 16:00:21 +0200
parents
children
comparison
equal deleted inserted replaced
4:26cd8f1ef0b1 5:f762bf195c4b
1 /*
2 * SpanDSP - a series of DSP components for telephony
3 *
4 * v22bis.h - ITU V.22bis modem receive part
5 *
6 * Written by Steve Underwood <steveu@coppice.org>
7 *
8 * Copyright (C) 2004 Steve Underwood
9 *
10 * All rights reserved.
11 *
12 * This program is free software; you can redistribute it and/or modify
13 * it under the terms of the GNU General Public License version 2, as
14 * published by the Free Software Foundation.
15 *
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, write to the Free Software
23 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24 *
25 * $Id: v22bis.h,v 1.19 2006/10/24 13:45:28 steveu Exp $
26 */
27
28 /*! \file */
29
30 /*! \page v22bis_page The V.22bis modem
31 \section v22bis_page_sec_1 What does it do?
32 The V.22bis modem is a duplex modem for general data use on the PSTN, at rates
33 of 1200 and 2400 bits/second. It is a compatible extension of the V.22 modem,
34 which is a 1200 bits/second only design. It is a band-split design, using carriers
35 of 1200Hz and 2400Hz. It is the fastest PSTN modem in general use which does not
36 use echo-cancellation.
37
38 \section v22bis__page_sec_2 How does it work?
39 V.22bis uses 4PSK modulation at 1200 bits/second or 16QAM modulation at 2400
40 bits/second. At 1200bps the symbols are so long that a fixed compromise equaliser
41 is sufficient to recover the 4PSK signal reliably. At 2400bps an adaptive
42 equaliser is necessary.
43
44 The V.22bis training sequence includes sections which allow the modems to determine
45 if the far modem can support (or is willing to support) 2400bps operation. The
46 modems will automatically use 2400bps if both ends are willing to use that speed,
47 or 1200bps if one or both ends to not acknowledge that 2400bps is OK.
48 */
49
50 #if !defined(_V22BIS_H_)
51 #define _V22BIS_H_
52
53 #define V22BIS_EQUALIZER_LEN 7 /* this much to the left and this much to the right */
54 #define V22BIS_EQUALIZER_MASK 15 /* one less than a power of 2 >= (2*V22BIS_EQUALIZER_LEN + 1) */
55
56 #define V22BIS_TX_FILTER_STEPS 9
57
58 #define V22BIS_RX_FILTER_STEPS 37
59
60 /*!
61 V.22bis modem receive side descriptor. This defines the working state for a
62 single instance of a V.22bis modem receiver.
63 */
64 typedef struct
65 {
66 /*! \brief The bit rate of the modem. Valid values are 1200 and 2400. */
67 int bit_rate;
68 /*! \brief TRUE is this is the calling side modem. */
69 int caller;
70 /*! \brief The callback function used to put each bit received. */
71 put_bit_func_t put_bit;
72 /*! \brief The callback function used to get the next bit to be transmitted. */
73 get_bit_func_t get_bit;
74 /*! \brief A user specified opaque pointer passed to the callback routines. */
75 void *user_data;
76
77 /* RECEIVE SECTION */
78
79 /*! \brief A callback function which may be enabled to report every symbol's
80 constellation position. */
81 qam_report_handler_t *qam_report;
82 /*! \brief A user specified opaque pointer passed to the qam_report callback
83 routine. */
84 void *qam_user_data;
85
86 /*! \brief The route raised cosine (RRC) pulse shaping filter buffer. */
87 float rx_rrc_filter[2*V22BIS_RX_FILTER_STEPS];
88 /*! \brief Current offset into the RRC pulse shaping filter buffer. */
89 int rx_rrc_filter_step;
90
91 /*! \brief The register for the data scrambler. */
92 unsigned int rx_scramble_reg;
93 /*! \brief A counter for the number of consecutive bits of repeating pattern through
94 the scrambler. */
95 int rx_scrambler_pattern_count;
96 /*! \brief 0 if receiving user data. A training stage value during training */
97 int rx_training;
98 int rx_training_count;
99 float training_error;
100 int carrier_present;
101
102 /*! \brief The current phase of the carrier (i.e. the DDS parameter). */
103 uint32_t rx_carrier_phase;
104 /*! \brief The update rate for the phase of the carrier (i.e. the DDS increment). */
105 int32_t rx_carrier_phase_rate;
106 float carrier_track_p;
107 float carrier_track_i;
108
109 power_meter_t rx_power;
110 int32_t carrier_on_power;
111 int32_t carrier_off_power;
112 float agc_scaling;
113
114 int rx_constellation_state;
115
116 float eq_delta;
117 /*! \brief The adaptive equalizer coefficients */
118 complexf_t eq_coeff[2*V22BIS_EQUALIZER_LEN + 1];
119 complexf_t eq_buf[V22BIS_EQUALIZER_MASK + 1];
120 /*! \brief Current offset into equalizer buffer. */
121 int eq_step;
122 int eq_put_step;
123
124 /*! \brief Integration variable for damping the Gardner algorithm tests. */
125 int gardner_integrate;
126 /*! \brief Current step size of Gardner algorithm integration. */
127 int gardner_step;
128 /*! \brief The total symbol timing correction since the carrier came up.
129 This is only for performance analysis purposes. */
130 int total_baud_timing_correction;
131 /*! \brief The current fractional phase of the baud timing. */
132 int rx_baud_phase;
133
134 int sixteen_way_decisions;
135
136 /* TRANSMIT SECTION */
137
138 /*! \brief The gain factor needed to achieve the specified output power. */
139 float tx_gain;
140
141 /*! \brief The route raised cosine (RRC) pulse shaping filter buffer. */
142 complexf_t tx_rrc_filter[2*V22BIS_TX_FILTER_STEPS];
143 /*! \brief Current offset into the RRC pulse shaping filter buffer. */
144 int tx_rrc_filter_step;
145
146 /*! \brief The register for the data scrambler. */
147 unsigned int tx_scramble_reg;
148 /*! \brief A counter for the number of consecutive bits of repeating pattern through
149 the scrambler. */
150 int tx_scrambler_pattern_count;
151 /*! \brief 0 if transmitting user data. A training stage value during training */
152 int tx_training;
153 /*! \brief A counter used to track progress through sending the training sequence. */
154 int tx_training_count;
155
156 /*! \brief The current phase of the carrier (i.e. the DDS parameter). */
157 uint32_t tx_carrier_phase;
158 /*! \brief The update rate for the phase of the carrier (i.e. the DDS increment). */
159 int32_t tx_carrier_phase_rate;
160 /*! \brief The current phase of the guard tone (i.e. the DDS parameter). */
161 uint32_t guard_phase;
162 /*! \brief The update rate for the phase of the guard tone (i.e. the DDS increment). */
163 int32_t guard_phase_rate;
164 float guard_level;
165 /*! \brief The current fractional phase of the baud timing. */
166 int tx_baud_phase;
167 /*! \brief The code number for the current position in the constellation. */
168 int tx_constellation_state;
169 /*! \brief An indicator to mark that we are tidying up to stop transmission. */
170 int shutdown;
171 /*! \brief The get_bit function in use at any instant. */
172 get_bit_func_t current_get_bit;
173
174 int detected_unscrambled_ones;
175 int detected_unscrambled_zeros;
176
177 int detected_unscrambled_ones_or_zeros;
178 int detected_unscrambled_0011_ending;
179 int detected_scrambled_ones_or_zeros_at_1200bps;
180 int detected_scrambled_ones_at_2400bps;
181
182 /*! \brief Error and flow logging control */
183 logging_state_t logging;
184 } v22bis_state_t;
185
186 extern const complexf_t v22bis_constellation[16];
187
188 #ifdef __cplusplus
189 extern "C" {
190 #endif
191
192 /*! Reinitialise an existing V.22bis modem receive context.
193 \brief Reinitialise an existing V.22bis modem receive context.
194 \param s The modem context.
195 \param rate The bit rate of the modem. Valid values are 1200 and 2400.
196 \return 0 for OK, -1 for bad parameter */
197 int v22bis_rx_restart(v22bis_state_t *s, int bit_rate);
198
199 /*! Process a block of received V.22bis modem audio samples.
200 \brief Process a block of received V.22bis modem audio samples.
201 \param s The modem context.
202 \param amp The audio sample buffer.
203 \param len The number of samples in the buffer.
204 \return The number of samples unprocessed. */
205 int v22bis_rx(v22bis_state_t *s, const int16_t amp[], int len);
206
207 /*! Get a snapshot of the current equalizer coefficients.
208 \brief Get a snapshot of the current equalizer coefficients.
209 \param coeffs The vector of complex coefficients.
210 \return The number of coefficients in the vector. */
211 int v22bis_rx_equalizer_state(v22bis_state_t *s, complexf_t **coeffs);
212
213 /*! Get the current received carrier frequency.
214 \param s The modem context.
215 \return The frequency, in Hertz. */
216 float v22bis_rx_carrier_frequency(v22bis_state_t *s);
217
218 /*! Get the current symbol timing correction since startup.
219 \param s The modem context.
220 \return The correction. */
221 float v22bis_rx_symbol_timing_correction(v22bis_state_t *s);
222
223 /*! Get a current received signal power.
224 \param s The modem context.
225 \return The signal power, in dBm0. */
226 float v22bis_rx_signal_power(v22bis_state_t *s);
227
228 /*! Set a handler routine to process QAM status reports
229 \param s The modem context.
230 \param handler The handler routine.
231 \param user_data An opaque pointer passed to the handler routine. */
232 void v22bis_rx_set_qam_report_handler(v22bis_state_t *s, qam_report_handler_t *handler, void *user_data);
233
234 /*! Generate a block of V.22bis modem audio samples.
235 \brief Generate a block of V.22bis modem audio samples.
236 \param s The modem context.
237 \param amp The audio sample buffer.
238 \param len The number of samples to be generated.
239 \return The number of samples actually generated. */
240 int v22bis_tx(v22bis_state_t *s, int16_t amp[], int len);
241
242 /*! Adjust a V.22bis modem transmit context's power output.
243 \brief Adjust a V.22bis modem transmit context's output power.
244 \param s The modem context.
245 \param power The power level, in dBm0 */
246 void v22bis_tx_power(v22bis_state_t *s, float power);
247
248 /*! Reinitialise an existing V.22bis modem context, so it may be reused.
249 \brief Reinitialise an existing V.22bis modem context.
250 \param s The modem context.
251 \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400.
252 \return 0 for OK, -1 for bad parameter. */
253 int v22bis_restart(v22bis_state_t *s, int bit_rate);
254
255 /*! Initialise a V.22bis modem context. This must be called before the first
256 use of the context, to initialise its contents.
257 \brief Initialise a V.22bis modem context.
258 \param s The modem context.
259 \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400.
260 \param guard The guard tone option. 0 = none, 1 = 550Hz, 2 = 1800Hz.
261 \param caller TRUE if this is the calling modem.
262 \param get_bit The callback routine used to get the data to be transmitted.
263 \param put_bit The callback routine used to get the data to be transmitted.
264 \param user_data An opaque pointer, passed in calls to the get and put routines.
265 \return A pointer to the modem context, or NULL if there was a problem. */
266 v22bis_state_t *v22bis_init(v22bis_state_t *s,
267 int bit_rate,
268 int guard,
269 int caller,
270 get_bit_func_t get_bit,
271 put_bit_func_t put_bit,
272 void *user_data);
273
274 /*! Change the get_bit function associated with a V.2bis modem context.
275 \brief Change the get_bit function associated with a V.22bis modem context.
276 \param s The modem context.
277 \param get_bit The callback routine used to get the data to be transmitted.
278 \param user_data An opaque pointer. */
279 void v22bis_set_get_bit(v22bis_state_t *s, get_bit_func_t get_bit, void *user_data);
280
281 /*! Change the get_bit function associated with a V.2bis modem context.
282 \brief Change the put_bit function associated with a V.22bis modem context.
283 \param s The modem context.
284 \param put_bit The callback routine used to process the data received.
285 \param user_data An opaque pointer. */
286 void v22bis_set_put_bit(v22bis_state_t *s, put_bit_func_t put_bit, void *user_data);
287
288 #ifdef __cplusplus
289 }
290 #endif
291
292 #endif
293 /*- End of file ------------------------------------------------------------*/

Repositories maintained by Peter Meerwald, pmeerw@pmeerw.net.