spandsp 0.0.6

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 enum
52{
53 V22BIS_GUARD_TONE_NONE,
54 V22BIS_GUARD_TONE_550HZ,
55 V22BIS_GUARD_TONE_1800HZ
56};
57
58/*!
59 V.22bis modem descriptor. This defines the working state for a single instance
60 of a V.22bis modem.
61*/
62 typedef struct v22bis_state_s v22bis_state_t;
63
64 extern const complexf_t v22bis_constellation[16];
65
66#if defined(__cplusplus)
67 extern "C"
68{
69#endif
70
71/*! Process a block of received V.22bis modem audio samples.
72 \brief Process a block of received V.22bis modem audio samples.
73 \param s The modem context.
74 \param amp The audio sample buffer.
75 \param len The number of samples in the buffer.
76 \return The number of samples unprocessed. */
77 SPAN_DECLARE_NONSTD(int) v22bis_rx(v22bis_state_t *s, const int16_t amp[], int len);
78
79/*! Fake processing of a missing block of received V.22bis modem audio samples.
80 (e.g due to packet loss).
81 \brief Fake processing of a missing block of received V.22bis modem audio samples.
82 \param s The modem context.
83 \param len The number of samples to fake.
84 \return The number of samples unprocessed. */
85 SPAN_DECLARE_NONSTD(int) v22bis_rx_fillin(v22bis_state_t *s, int len);
86
87/*! Get a snapshot of the current equalizer coefficients.
88 \brief Get a snapshot of the current equalizer coefficients.
89 \param coeffs The vector of complex coefficients.
90 \return The number of coefficients in the vector. */
91SPAN_DECLARE(int) v22bis_rx_equalizer_state(v22bis_state_t *s, complexf_t **coeffs);
92
93/*! Get the current received carrier frequency.
94 \param s The modem context.
95 \return The frequency, in Hertz. */
96SPAN_DECLARE(float) v22bis_rx_carrier_frequency(v22bis_state_t *s);
97
98/*! Get the current symbol timing correction since startup.
99 \param s The modem context.
100 \return The correction. */
101SPAN_DECLARE(float) v22bis_rx_symbol_timing_correction(v22bis_state_t *s);
102
103/*! Get a current received signal power.
104 \param s The modem context.
105 \return The signal power, in dBm0. */
106SPAN_DECLARE(float) v22bis_rx_signal_power(v22bis_state_t *s);
107
108/*! Set the power level at which the carrier detection will cut in
109 \param s The modem context.
110 \param cutoff The signal cutoff power, in dBm0. */
111SPAN_DECLARE(void) v22bis_rx_signal_cutoff(v22bis_state_t *s, float cutoff);
112
113/*! Set a handler routine to process QAM status reports
114 \param s The modem context.
115 \param handler The handler routine.
116 \param user_data An opaque pointer passed to the handler routine. */
117SPAN_DECLARE(void) v22bis_rx_set_qam_report_handler(v22bis_state_t *s, qam_report_handler_t handler, void *user_data);
118
119/*! Generate a block of V.22bis modem audio samples.
120 \brief Generate a block of V.22bis modem audio samples.
121 \param s The modem context.
122 \param amp The audio sample buffer.
123 \param len The number of samples to be generated.
124 \return The number of samples actually generated. */
125 SPAN_DECLARE_NONSTD(int) v22bis_tx(v22bis_state_t *s, int16_t amp[], int len);
126
127/*! Adjust a V.22bis modem transmit context's power output.
128 \brief Adjust a V.22bis modem transmit context's output power.
129 \param s The modem context.
130 \param power The power level, in dBm0 */
131SPAN_DECLARE(void) v22bis_tx_power(v22bis_state_t *s, float power);
132
133/*! Reinitialise an existing V.22bis modem context, so it may be reused.
134 \brief Reinitialise an existing V.22bis modem context.
135 \param s The modem context.
136 \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400.
137 \return 0 for OK, -1 for bad parameter. */
138SPAN_DECLARE(int) v22bis_restart(v22bis_state_t *s, int bit_rate);
139
140/*! Request a retrain for a V.22bis modem context. A rate change may also be requested.
141 \brief Request a retrain for a V.22bis modem context.
142 \param s The modem context.
143 \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400.
144 \return 0 for OK, -1 for request rejected. */
145SPAN_DECLARE(int) v22bis_request_retrain(v22bis_state_t *s, int bit_rate);
146
147/*! Request a loopback 2 for a V.22bis modem context.
148 \brief Request a loopback 2 for a V.22bis modem context.
149 \param s The modem context.
150 \param enable TRUE to enable loopback, or FALSE to disable it.
151 \return 0 for OK, -1 for request reject. */
152SPAN_DECLARE(int) v22bis_remote_loopback(v22bis_state_t *s, int enable);
153
154/*! Report the current operating bit rate of a V.22bis modem context.
155 \brief Report the current operating bit rate of a V.22bis modem context
156 \param s The modem context. */
157SPAN_DECLARE(int) v22bis_get_current_bit_rate(v22bis_state_t *s);
158
159/*! Initialise a V.22bis modem context. This must be called before the first
160 use of the context, to initialise its contents.
161 \brief Initialise a V.22bis modem context.
162 \param s The modem context.
163 \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400.
164 \param guard The guard tone option. 0 = none, 1 = 550Hz, 2 = 1800Hz.
165 \param calling_party TRUE if this is the calling modem.
166 \param get_bit The callback routine used to get the data to be transmitted.
167 \param put_bit The callback routine used to get the data to be transmitted.
168 \param user_data An opaque pointer, passed in calls to the get and put routines.
169 \return A pointer to the modem context, or NULL if there was a problem. */
170SPAN_DECLARE(v22bis_state_t *) v22bis_init(v22bis_state_t *s,
171 int bit_rate,
172 int guard,
173 int calling_party,
174 get_bit_func_t get_bit,
175 void *get_bit_user_data,
176 put_bit_func_t put_bit,
177 void *put_bit_user_data);
178
179/*! Release a V.22bis modem receive context.
180 \brief Release a V.22bis modem receive context.
181 \param s The modem context.
182 \return 0 for OK */
183SPAN_DECLARE(int) v22bis_release(v22bis_state_t *s);
184
185/*! Free a V.22bis modem receive context.
186 \brief Free a V.22bis modem receive context.
187 \param s The modem context.
188 \return 0 for OK */
189SPAN_DECLARE(int) v22bis_free(v22bis_state_t *s);
190
191/*! Get the logging context associated with a V.22bis modem context.
192 \brief Get the logging context associated with a V.22bis modem context.
193 \param s The modem context.
194 \return A pointer to the logging context */
195SPAN_DECLARE(logging_state_t *) v22bis_get_logging_state(v22bis_state_t *s);
196
197/*! Change the get_bit function associated with a V.22bis modem context.
198 \brief Change the get_bit function associated with a V.22bis modem context.
199 \param s The modem context.
200 \param get_bit The callback routine used to get the data to be transmitted.
201 \param user_data An opaque pointer. */
202SPAN_DECLARE(void) v22bis_set_get_bit(v22bis_state_t *s, get_bit_func_t get_bit, void *user_data);
203
204/*! Change the get_bit function associated with a V.22bis modem context.
205 \brief Change the put_bit function associated with a V.22bis modem context.
206 \param s The modem context.
207 \param put_bit The callback routine used to process the data received.
208 \param user_data An opaque pointer. */
209SPAN_DECLARE(void) v22bis_set_put_bit(v22bis_state_t *s, put_bit_func_t put_bit, void *user_data);
210
211/*! Change the modem status report function associated with a V.22bis modem receive context.
212 \brief Change the modem status report function associated with a V.22bis modem receive context.
213 \param s The modem context.
214 \param handler The callback routine used to report modem status changes.
215 \param user_data An opaque pointer. */
216SPAN_DECLARE(void) v22bis_set_modem_status_handler(v22bis_state_t *s, modem_status_func_t handler, void *user_data);
217
218#if defined(__cplusplus)
219}
220#endif
221
222#endif
223/*- End of file ------------------------------------------------------------*/
modem_status_func_t
void(* modem_status_func_t)(void *user_data, int status)
Definition async.h:114
put_bit_func_t
void(* put_bit_func_t)(void *user_data, int bit)
Definition async.h:105
SPAN_DECLARE_NONSTD
SPAN_DECLARE_NONSTD(void) async_rx_put_bit(void *user_data
Accept a bit from a received serial bit stream.
get_bit_func_t
int(* get_bit_func_t)(void *user_data)
Definition async.h:108
logging_state_t
struct logging_state_s logging_state_t
Definition logging.h:75
complexf_t
Definition complex.h:43
v22bis_state_s
Definition private/v22bis.h:73
v22bis_state_s::put_bit_user_data
void * put_bit_user_data
A user specified opaque pointer passed to the put_bit callback routine.
Definition private/v22bis.h:85
v22bis_state_s::calling_party
int calling_party
TRUE is this is the calling side modem.
Definition private/v22bis.h:77
v22bis_state_s::get_bit_user_data
void * get_bit_user_data
A user specified opaque pointer passed to the get_bit callback routine.
Definition private/v22bis.h:81
v22bis_rx_signal_cutoff
void v22bis_rx_signal_cutoff(v22bis_state_t *s, float cutoff)
Definition v22bis_rx.c:157
v22bis_tx_power
void v22bis_tx_power(v22bis_state_t *s, float power)
Adjust a V.22bis modem transmit context's output power.
Definition v22bis_tx.c:493
v22bis_get_current_bit_rate
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:628
v22bis_set_put_bit
void v22bis_set_put_bit(v22bis_state_t *s, 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:548
v22bis_state_t
struct v22bis_state_s v22bis_state_t
Definition v22bis.h:62
v22bis_remote_loopback
int v22bis_remote_loopback(v22bis_state_t *s, int enable)
Request a loopback 2 for a V.22bis modem context.
Definition v22bis_tx.c:621
v22bis_set_modem_status_handler
void v22bis_set_modem_status_handler(v22bis_state_t *s, 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:555
v22bis_rx_carrier_frequency
float v22bis_rx_carrier_frequency(v22bis_state_t *s)
Definition v22bis_rx.c:139
v22bis_restart
int v22bis_restart(v22bis_state_t *s, int bit_rate)
Reinitialise an existing V.22bis modem context.
Definition v22bis_tx.c:568
v22bis_free
int v22bis_free(v22bis_state_t *s)
Free a V.22bis modem receive context.
Definition v22bis_tx.c:699
v22bis_set_get_bit
void v22bis_set_get_bit(v22bis_state_t *s, 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:541
v22bis_release
int v22bis_release(v22bis_state_t *s)
Release a V.22bis modem receive context.
Definition v22bis_tx.c:693
v22bis_rx_signal_power
float v22bis_rx_signal_power(v22bis_state_t *s)
Definition v22bis_rx.c:151
v22bis_request_retrain
int v22bis_request_retrain(v22bis_state_t *s, int bit_rate)
Request a retrain for a V.22bis modem context.
Definition v22bis_tx.c:586
v22bis_init
v22bis_state_t * v22bis_init(v22bis_state_t *s, int bit_rate, int guard, int calling_party, get_bit_func_t get_bit, void *get_bit_user_data, put_bit_func_t put_bit, void *put_bit_user_data)
Initialise a V.22bis modem context.
Definition v22bis_tx.c:634
v22bis_rx_set_qam_report_handler
void v22bis_rx_set_qam_report_handler(v22bis_state_t *s, qam_report_handler_t handler, void *user_data)
Definition v22bis_rx.c:877
v22bis_rx_symbol_timing_correction
float v22bis_rx_symbol_timing_correction(v22bis_state_t *s)
Definition v22bis_rx.c:145
v22bis_rx_equalizer_state
int v22bis_rx_equalizer_state(v22bis_state_t *s, complexf_t **coeffs)
Get a snapshot of the current equalizer coefficients.
Definition v22bis_rx.c:173
v22bis_get_logging_state
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:562