spandsp  3.0.0
v22bis.h
Go to the documentation of this file.
1 /*
2  * SpanDSP - a series of DSP components for telephony
3  *
4  * v22bis.h - ITU V.22bis modem
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 Lesser General Public License version 2.1,
14  * as 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 Lesser General Public License for more details.
20  *
21  * You should have received a copy of the GNU Lesser General Public
22  * License along with this program; if not, write to the Free Software
23  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24  */
25 
26 /*! \file */
27 
28 /*! \page v22bis_page The V.22bis modem
29 \section v22bis_page_sec_1 What does it do?
30 The V.22bis modem is a duplex modem for general data use on the PSTN, at rates
31 of 1200 and 2400 bits/second. It is a compatible extension of the V.22 modem,
32 which is a 1200 bits/second only design. It is a band-split design, using carriers
33 of 1200Hz and 2400Hz. It is the fastest PSTN modem in general use which does not
34 use echo-cancellation.
35 
36 \section v22bis__page_sec_2 How does it work?
37 V.22bis uses 4PSK modulation at 1200 bits/second or 16QAM modulation at 2400
38 bits/second. At 1200bps the symbols are so long that a fixed compromise equaliser
39 is sufficient to recover the 4PSK signal reliably. At 2400bps an adaptive
40 equaliser is necessary.
41 
42 The V.22bis training sequence includes sections which allow the modems to determine
43 if the far modem can support (or is willing to support) 2400bps operation. The
44 modems will automatically use 2400bps if both ends are willing to use that speed,
45 or 1200bps if one or both ends to not acknowledge that 2400bps is OK.
46 */
47 
48 #if !defined(_SPANDSP_V22BIS_H_)
49 #define _SPANDSP_V22BIS_H_
50 
51 #if defined(SPANDSP_USE_FIXED_POINT)
52 #define V22BIS_CONSTELLATION_SCALING_FACTOR 1024.0
53 #else
54 #define V22BIS_CONSTELLATION_SCALING_FACTOR 1.0
55 #endif
56 
57 /* The bottom bits of the option field define which guard tone to use. Guard tones were a compatibility
58  mechanism to prevent a high band modem signal from interferring with billing systems. Only the
59  answering modem sends them.
60 
61  Other options can be OR'ed with the guard tone option. */
62 typedef enum
63 {
64  /* No guard tone is the norm is some areas, such a North America */
65  V22BIS_GUARD_TONE_NONE = 0,
66  /* 550Hz guard tone is the norm is some areas, such as Scandinavia */
67  V22BIS_GUARD_TONE_550HZ = 1,
68  /* 1800Hz guard tone is the norm is some areas, such as the UK and much of the Commonwealth */
69  V22BIS_GUARD_TONE_1800HZ = 2,
70  /* Change the operation of the modem to follow the original Bell212A spec, from which V.22bis was
71  developed. This is basically for old systems in North America. */
72  V22BIS_BELL212A_COMPATIBILITY_MODE = 0x100,
73  /* Use unscrambled 00 instead of unscrambled 11 during the handshake. This is not something you
74  should use day to day. Its here to allow testing that receivers will function correctly with
75  either 11 or 00, as V.22bis says they should. */
76  V22BIS_USE_U00 = 0x200
77 } v22bis_options_t;
78 
79 /*!
80  V.22bis modem descriptor. This defines the working state for a single instance
81  of a V.22bis modem.
82 */
84 
85 #if defined(__cplusplus)
86 extern "C"
87 {
88 #endif
89 
90 /*! Process a block of received V.22bis modem audio samples.
91  \brief Process a block of received V.22bis modem audio samples.
92  \param s The modem context.
93  \param amp The audio sample buffer.
94  \param len The number of samples in the buffer.
95  \return The number of samples unprocessed. */
96 SPAN_DECLARE(int) v22bis_rx(v22bis_state_t *s, const int16_t amp[], int len);
97 
98 /*! Fake processing of a missing block of received V.22bis modem audio samples.
99  (e.g due to packet loss).
100  \brief Fake processing of a missing block of received V.22bis modem audio samples.
101  \param s The modem context.
102  \param len The number of samples to fake.
103  \return The number of samples unprocessed. */
104 SPAN_DECLARE(int) v22bis_rx_fillin(v22bis_state_t *s, int len);
105 
106 /*! Get a snapshot of the current equalizer coefficients.
107  \brief Get a snapshot of the current equalizer coefficients.
108  \param coeffs The vector of complex coefficients.
109  \return The number of coefficients in the vector. */
110 #if defined(SPANDSP_USE_FIXED_POINT)
111 SPAN_DECLARE(int) v22bis_rx_equalizer_state(v22bis_state_t *s, complexi16_t **coeffs);
112 #else
113 SPAN_DECLARE(int) v22bis_rx_equalizer_state(v22bis_state_t *s, complexf_t **coeffs);
114 #endif
115 
116 /*! Get the current received carrier frequency.
117  \param s The modem context.
118  \return The frequency, in Hertz. */
119 SPAN_DECLARE(float) v22bis_rx_carrier_frequency(v22bis_state_t *s);
120 
121 /*! Get the current symbol timing correction since startup.
122  \param s The modem context.
123  \return The correction. */
124 SPAN_DECLARE(float) v22bis_rx_symbol_timing_correction(v22bis_state_t *s);
125 
126 /*! Get a current received signal power.
127  \param s The modem context.
128  \return The signal power, in dBm0. */
129 SPAN_DECLARE(float) v22bis_rx_signal_power(v22bis_state_t *s);
130 
131 /*! Set the power level at which the carrier detection will cut in
132  \param s The modem context.
133  \param cutoff The signal cutoff power, in dBm0. */
134 SPAN_DECLARE(void) v22bis_rx_set_signal_cutoff(v22bis_state_t *s, float cutoff);
135 
136 /*! Set a handler routine to process QAM status reports
137  \param s The modem context.
138  \param handler The handler routine.
139  \param user_data An opaque pointer passed to the handler routine. */
140 SPAN_DECLARE(void) v22bis_rx_set_qam_report_handler(v22bis_state_t *s, qam_report_handler_t handler, void *user_data);
141 
142 /*! Generate a block of V.22bis modem audio samples.
143  \brief Generate a block of V.22bis modem audio samples.
144  \param s The modem context.
145  \param amp The audio sample buffer.
146  \param len The number of samples to be generated.
147  \return The number of samples actually generated. */
148 SPAN_DECLARE(int) v22bis_tx(v22bis_state_t *s, int16_t amp[], int len);
149 
150 /*! Adjust a V.22bis modem transmit context's power output.
151  \brief Adjust a V.22bis modem transmit context's output power.
152  \param s The modem context.
153  \param power The power level, in dBm0 */
154 SPAN_DECLARE(void) v22bis_tx_power(v22bis_state_t *s, float power);
155 
156 /*! Reinitialise an existing V.22bis modem context, so it may be reused.
157  \brief Reinitialise an existing V.22bis modem context.
158  \param s The modem context.
159  \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400.
160  \return 0 for OK, -1 for bad parameter. */
161 SPAN_DECLARE(int) v22bis_restart(v22bis_state_t *s, int bit_rate);
162 
163 /*! Request a retrain for a V.22bis modem context. A rate change may also be requested.
164  \brief Request a retrain for a V.22bis modem context.
165  \param s The modem context.
166  \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400.
167  \return 0 for OK, -1 for request rejected. */
168 SPAN_DECLARE(int) v22bis_request_retrain(v22bis_state_t *s, int bit_rate);
169 
170 /*! Request a loopback 2 for a V.22bis modem context.
171  \brief Request a loopback 2 for a V.22bis modem context.
172  \param s The modem context.
173  \param enable True to enable loopback, or false to disable it.
174  \return 0 for OK, -1 for request reject. */
175 SPAN_DECLARE(int) v22bis_remote_loopback(v22bis_state_t *s, bool enable);
176 
177 /*! Report the current operating bit rate of a V.22bis modem context.
178  \brief Report the current operating bit rate of a V.22bis modem context
179  \param s The modem context. */
180 SPAN_DECLARE(int) v22bis_get_current_bit_rate(v22bis_state_t *s);
181 
182 /*! Initialise a V.22bis modem context. This must be called before the first
183  use of the context, to initialise its contents.
184  \brief Initialise a V.22bis modem context.
185  \param s The modem context.
186  \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400.
187  \param options Guard tone and other options.
188  \param calling_party True if this is the calling modem.
189  \param get_bit The callback routine used to get the data to be transmitted.
190  \param get_bit_user_data An opaque pointer, passed in calls to the get_bit routine.
191  \param put_bit The callback routine used to put the data received.
192  \param put_bit_user_data An opaque pointer, passed in calls to the put_bit routine.
193  \return A pointer to the modem context, or NULL if there was a problem. */
194 SPAN_DECLARE(v22bis_state_t *) v22bis_init(v22bis_state_t *s,
195  int bit_rate,
196  int options,
197  bool calling_party,
199  void *get_bit_user_data,
201  void *put_bit_user_data);
202 
203 /*! Release a V.22bis modem receive context.
204  \brief Release a V.22bis modem receive context.
205  \param s The modem context.
206  \return 0 for OK */
207 SPAN_DECLARE(int) v22bis_release(v22bis_state_t *s);
208 
209 /*! Free a V.22bis modem receive context.
210  \brief Free a V.22bis modem receive context.
211  \param s The modem context.
212  \return 0 for OK */
213 SPAN_DECLARE(int) v22bis_free(v22bis_state_t *s);
214 
215 /*! Get the logging context associated with a V.22bis modem context.
216  \brief Get the logging context associated with a V.22bis modem context.
217  \param s The modem context.
218  \return A pointer to the logging context */
220 
221 /*! Change the get_bit function associated with a V.22bis modem context.
222  \brief Change the get_bit function associated with a V.22bis modem context.
223  \param s The modem context.
224  \param get_bit The callback routine used to get the data to be transmitted.
225  \param user_data An opaque pointer. */
226 SPAN_DECLARE(void) v22bis_set_get_bit(v22bis_state_t *s, span_get_bit_func_t get_bit, void *user_data);
227 
228 /*! Change the get_bit function associated with a V.22bis modem context.
229  \brief Change the put_bit function associated with a V.22bis modem context.
230  \param s The modem context.
231  \param put_bit The callback routine used to process the data received.
232  \param user_data An opaque pointer. */
233 SPAN_DECLARE(void) v22bis_set_put_bit(v22bis_state_t *s, span_put_bit_func_t put_bit, void *user_data);
234 
235 /*! Change the modem status report function associated with a V.22bis modem receive context.
236  \brief Change the modem status report function associated with a V.22bis modem receive context.
237  \param s The modem context.
238  \param handler The callback routine used to report modem status changes.
239  \param user_data An opaque pointer. */
240 SPAN_DECLARE(void) v22bis_set_modem_status_handler(v22bis_state_t *s, span_modem_status_func_t handler, void *user_data);
241 
242 #if defined(__cplusplus)
243 }
244 #endif
245 
246 #endif
247 /*- End of file ------------------------------------------------------------*/
void v22bis_rx_set_signal_cutoff(v22bis_state_t *s, float cutoff)
Definition: v22bis_rx.c:160
Definition: complex.h:88
int v22bis_rx(v22bis_state_t *s, const int16_t amp[], int len)
Process a block of received V.22bis modem audio samples.
Definition: v22bis_rx.c:827
int v22bis_request_retrain(v22bis_state_t *s, int bit_rate)
Request a retrain for a V.22bis modem context.
Definition: v22bis_tx.c:807
int v22bis_release(v22bis_state_t *s)
Release a V.22bis modem receive context.
Definition: v22bis_tx.c:922
void v22bis_set_put_bit(v22bis_state_t *s, span_put_bit_func_t put_bit, void *user_data)
Change the put_bit function associated with a V.22bis modem context.
Definition: v22bis_tx.c:767
void v22bis_set_get_bit(v22bis_state_t *s, span_get_bit_func_t get_bit, void *user_data)
Change the get_bit function associated with a V.22bis modem context.
Definition: v22bis_tx.c:760
float v22bis_rx_carrier_frequency(v22bis_state_t *s)
Definition: v22bis_rx.c:142
int(* span_get_bit_func_t)(void *user_data)
Definition: async.h:127
int bit_rate
The maximum permitted bit rate of the modem. Valid values are 1200 and 2400.
Definition: private/v22bis.h:82
float v22bis_rx_signal_power(v22bis_state_t *s)
Definition: v22bis_rx.c:154
void(* span_modem_status_func_t)(void *user_data, int status)
Definition: async.h:131
void(* span_put_bit_func_t)(void *user_data, int bit)
Definition: async.h:123
int v22bis_tx(v22bis_state_t *s, int16_t amp[], int len)
Generate a block of V.22bis modem audio samples.
Definition: v22bis_tx.c:626
span_put_bit_func_t put_bit
The callback function used to put each bit received.
Definition: private/v22bis.h:92
int v22bis_restart(v22bis_state_t *s, int bit_rate)
Reinitialise an existing V.22bis modem context.
Definition: v22bis_tx.c:787
int v22bis_remote_loopback(v22bis_state_t *s, bool enable)
Request a loopback 2 for a V.22bis modem context.
Definition: v22bis_tx.c:844
void * get_bit_user_data
A user specified opaque pointer passed to the get_bit callback routine.
Definition: private/v22bis.h:90
v22bis_state_t * v22bis_init(v22bis_state_t *s, int bit_rate, int options, bool calling_party, span_get_bit_func_t get_bit, void *get_bit_user_data, span_put_bit_func_t put_bit, void *put_bit_user_data)
Initialise a V.22bis modem context.
Definition: v22bis_tx.c:857
void * put_bit_user_data
A user specified opaque pointer passed to the put_bit callback routine.
Definition: private/v22bis.h:94
Definition: complex.h:42
int v22bis_free(v22bis_state_t *s)
Free a V.22bis modem receive context.
Definition: v22bis_tx.c:928
Definition: private/logging.h:33
Definition: private/v22bis.h:79
int options
Guard tone and sundry flags.
Definition: private/v22bis.h:84
span_get_bit_func_t get_bit
The callback function used to get the next bit to be transmitted.
Definition: private/v22bis.h:88
logging_state_t * v22bis_get_logging_state(v22bis_state_t *s)
Get the logging context associated with a V.22bis modem context.
Definition: v22bis_tx.c:781
int v22bis_rx_fillin(v22bis_state_t *s, int len)
Fake processing of a missing block of received V.22bis modem audio samples.
Definition: v22bis_rx.c:982
void v22bis_tx_power(v22bis_state_t *s, float power)
Adjust a V.22bis modem transmit context&#39;s output power.
Definition: v22bis_tx.c:695
bool calling_party
True if this is the calling side modem.
Definition: private/v22bis.h:86
void v22bis_rx_set_qam_report_handler(v22bis_state_t *s, qam_report_handler_t handler, void *user_data)
Definition: v22bis_rx.c:1058
float v22bis_rx_symbol_timing_correction(v22bis_state_t *s)
Definition: v22bis_rx.c:148
void v22bis_set_modem_status_handler(v22bis_state_t *s, span_modem_status_func_t handler, void *user_data)
Change the modem status report function associated with a V.22bis modem receive context.
Definition: v22bis_tx.c:774
int v22bis_rx_equalizer_state(v22bis_state_t *s, complexf_t **coeffs)
Get a snapshot of the current equalizer coefficients.
Definition: v22bis_rx.c:180
int v22bis_get_current_bit_rate(v22bis_state_t *s)
Report the current operating bit rate of a V.22bis modem context.
Definition: v22bis_tx.c:851