spandsp 3.0.0
v34.h
Go to the documentation of this file.
1/*
2 * SpanDSP - a series of DSP components for telephony
3 *
4 * v34.h - ITU V.34 modem
5 *
6 * Written by Steve Underwood <steveu@coppice.org>
7 *
8 * Copyright (C) 2009 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 v34_page The V.34 modem
29\section v34_page_sec_1 What does it do?
30
31\section v34__page_sec_2 How does it work?
32*/
33
34#if !defined(_SPANDSP_V34_H_)
35#define _SPANDSP_V34_H_
36
37#if defined(SPANDSP_USE_FIXED_POINT)
38#define V34_CONSTELLATION_SCALING_FACTOR 512.0
39#else
40#define V34_CONSTELLATION_SCALING_FACTOR 1.0
41#endif
42
43enum v34_supported_bit_rates_e
44{
45 V34_SUPPORT_2400 = 0x0001,
46 V34_SUPPORT_4800 = 0x0002,
47 V34_SUPPORT_7200 = 0x0004,
48 V34_SUPPORT_9600 = 0x0008,
49 V34_SUPPORT_12000 = 0x0010,
50 V34_SUPPORT_14400 = 0x0020,
51 V34_SUPPORT_16800 = 0x0040,
52 V34_SUPPORT_19200 = 0x0080,
53 V34_SUPPORT_21600 = 0x0100,
54 V34_SUPPORT_24000 = 0x0200,
55 V34_SUPPORT_26400 = 0x0400,
56 V34_SUPPORT_28800 = 0x0800,
57 V34_SUPPORT_31200 = 0x1000,
58 V34_SUPPORT_33600 = 0x2000
59};
60
61enum v34_half_duplex_modes_e
62{
63 /* Make this the source side modem in the half-duplex exchange */
64 V34_HALF_DUPLEX_SOURCE,
65 /* Make this the recipient side modem in the half-duplex exchange */
66 V34_HALF_DUPLEX_RECIPIENT,
67 /* Start control channel operation */
68 V34_HALF_DUPLEX_CONTROL_CHANNEL,
69 /* Start primary channel operation in the current source/recipient mode */
70 V34_HALF_DUPLEX_PRIMARY_CHANNEL,
71 /* Stop transmission */
72 V34_HALF_DUPLEX_SILENCE
73};
74
75/*!
76 V.34 modem descriptor. This defines the working state for a single instance
77 of a V.34 modem.
78*/
79typedef struct v34_state_s v34_state_t;
80
81#if defined(__cplusplus)
82extern "C"
83{
84#endif
85
86/*! Process a block of received V.34 modem audio samples.
87 \brief Process a block of received V.34 modem audio samples.
88 \param s The modem context.
89 \param amp The audio sample buffer.
90 \param len The number of samples in the buffer.
91 \return The number of samples unprocessed. */
92SPAN_DECLARE(int) v34_rx(v34_state_t *s, const int16_t amp[], int len);
93
94/*! Fake processing of a missing block of received V.34 modem audio samples.
95 (e.g due to packet loss).
96 \brief Fake processing of a missing block of received V.34 modem audio samples.
97 \param s The modem context.
98 \param len The number of samples to fake.
99 \return The number of samples unprocessed. */
100SPAN_DECLARE(int) v34_rx_fillin(v34_state_t *s, int len);
101
102/*! Get a snapshot of the current equalizer coefficients.
103 \brief Get a snapshot of the current equalizer coefficients.
104 \param coeffs The vector of complex coefficients.
105 \return The number of coefficients in the vector. */
106#if defined(SPANDSP_USE_FIXED_POINT)
107SPAN_DECLARE(int) v34_equalizer_state(v34_state_t *s, complexi16_t **coeffs);
108#else
109SPAN_DECLARE(int) v34_equalizer_state(v34_state_t *s, complexf_t **coeffs);
110#endif
111
112/*! Get the current received carrier frequency.
113 \param s The modem context.
114 \return The frequency, in Hertz. */
115SPAN_DECLARE(float) v34_rx_carrier_frequency(v34_state_t *s);
116
117/*! Get the current symbol timing correction since startup.
118 \param s The modem context.
119 \return The correction. */
121
122/*! Get a current received signal power.
123 \param s The modem context.
124 \return The signal power, in dBm0. */
125SPAN_DECLARE(float) v34_rx_signal_power(v34_state_t *s);
126
127/*! Set the power level at which the carrier detection will cut in
128 \param s The modem context.
129 \param cutoff The signal cutoff power, in dBm0. */
130SPAN_DECLARE(void) v34_rx_set_signal_cutoff(v34_state_t *s, float cutoff);
131
132/*! Set a handler routine to process QAM status reports
133 \param s The modem context.
134 \param handler The handler routine.
135 \param user_data An opaque pointer passed to the handler routine. */
136SPAN_DECLARE(void) v34_set_qam_report_handler(v34_state_t *s, qam_report_handler_t handler, void *user_data);
137
138/*! Generate a block of V.34 modem audio samples.
139 \brief Generate a block of V.34 modem audio samples.
140 \param s The modem context.
141 \param amp The audio sample buffer.
142 \param len The number of samples to be generated.
143 \return The number of samples actually generated. */
144SPAN_DECLARE(int) v34_tx(v34_state_t *s, int16_t amp[], int len);
145
146/*! Adjust a V.34 modem transmit context's power output.
147 \brief Adjust a V.34 modem transmit context's output power.
148 \param s The modem context.
149 \param power The power level, in dBm0 */
150SPAN_DECLARE(void) v34_tx_power(v34_state_t *s, float power);
151
152/*! Report the current operating bit rate of a V.34 modem context.
153 \brief Report the current operating bit rate of a V.34 modem context
154 \param s The modem context.
155 \return ??? */
156SPAN_DECLARE(int) v34_get_current_bit_rate(v34_state_t *s);
157
158/*! Change the operating mode of a V.34 half-duplex modem.
159 \brief Change the operating mode of a V.34 half-duplex modem.
160 \param s The modem context.
161 \param mode The new mode to be selected.
162 \return ??? */
163SPAN_DECLARE(int) v34_half_duplex_change_mode(v34_state_t *s, int mode);
164
165/*! Reinitialise an existing V.34 modem context, so it may be reused.
166 \brief Reinitialise an existing V.34 modem context.
167 \param s The modem context.
168 \param baud_rate The baud rate of the modem. Valid values are 2400, 2743, 2800, 3000, 3200 and 3429
169 \param bit_rate The bit rate of the modem. Valid values are 4800, 7200, 9600, 12000 and 14400.
170 \param duplex True if this is a full duplex mode modem. Otherwise this is a half-duplex modem.
171 \return 0 for OK, -1 for bad parameter */
172SPAN_DECLARE(int) v34_restart(v34_state_t *s, int baud_rate, int bit_rate, bool duplex);
173
174/*! Initialise a V.34 modem context. This must be called before the first
175 use of the context, to initialise its contents.
176 \brief Initialise a V.34 modem context.
177 \param s The modem context.
178 \param baud_rate The baud rate of the modem. Valid values are 2400, 2743, 2800, 3000, 3200 and 3429
179 \param bit_rate The bit rate of the modem. Valid values are 4800, 7200, 9600, 12000 and 14400.
180 \param calling_party True if this is the calling modem.
181 \param duplex True if this is a full duplex mode modem. Otherwise this is a half-duplex modem.
182 \param get_bit The callback routine used to get the data to be transmitted.
183 \param get_bit_user_data An opaque pointer, passed in calls to the gett routine.
184 \param put_bit The callback routine used to get the data to be transmitted.
185 \param put_bit_user_data An opaque pointer, passed in calls to the put routine.
186 \return A pointer to the modem context, or NULL if there was a problem. */
187SPAN_DECLARE(v34_state_t *) v34_init(v34_state_t *s,
188 int baud_rate,
189 int bit_rate,
190 bool calling_party,
191 bool duplex,
192 span_get_bit_func_t get_bit,
193 void *get_bit_user_data,
194 span_put_bit_func_t put_bit,
195 void *put_bit_user_data);
196
197/*! Release a V.34 modem receive context.
198 \brief Release a V.34 modem receive context.
199 \param s The modem context.
200 \return 0 for OK */
201SPAN_DECLARE(int) v34_release(v34_state_t *s);
202
203/*! Free a V.34 modem receive context.
204 \brief Free a V.34 modem receive context.
205 \param s The modem context.
206 \return 0 for OK */
207SPAN_DECLARE(int) v34_free(v34_state_t *s);
208
209/*! Get the logging context associated with a V.34 modem context.
210 \brief Get the logging context associated with a V.34 modem context.
211 \param s The modem context.
212 \return A pointer to the logging context */
214
215/*! Change the get_bit function associated with a V.34 modem context.
216 \brief Change the get_bit function associated with a V.34 modem context.
217 \param s The modem context.
218 \param get_bit The callback routine used to get the data to be transmitted.
219 \param user_data An opaque pointer. */
220SPAN_DECLARE(void) v34_set_get_bit(v34_state_t *s, span_get_bit_func_t get_bit, void *user_data);
221
222/*! Change the get_aux_bit function associated with a V.34 modem context.
223 \brief Change the get_aux_bit function associated with a V.34 modem context.
224 \param s The modem context.
225 \param get_bit The callback routine used to get the aux. data to be transmitted.
226 \param user_data An opaque pointer. */
227SPAN_DECLARE(void) v34_set_get_aux_bit(v34_state_t *s, span_get_bit_func_t get_bit, void *user_data);
228
229/*! Change the put_bit function associated with a V.34 modem context.
230 \brief Change the put_bit function associated with a V.34 modem context.
231 \param s The modem context.
232 \param put_bit The callback routine used to process the data received.
233 \param user_data An opaque pointer. */
234SPAN_DECLARE(void) v34_set_put_bit(v34_state_t *s, span_put_bit_func_t put_bit, void *user_data);
235
236/*! Change the put_aux_bit function associated with a V.34 modem context.
237 \brief Change the put_aux_bit function associated with a V.34 modem context.
238 \param s The modem context.
239 \param put_bit The callback routine used to process the aux data received.
240 \param user_data An opaque pointer. */
241SPAN_DECLARE(void) v34_set_put_aux_bit(v34_state_t *s, span_put_bit_func_t put_bit, void *user_data);
242
243#if defined(__cplusplus)
244}
245#endif
246
247#endif
248/*- End of file ------------------------------------------------------------*/
int(* span_get_bit_func_t)(void *user_data)
Definition async.h:127
void(* span_put_bit_func_t)(void *user_data, int bit)
Definition async.h:123
struct logging_state_s logging_state_t
Definition logging.h:72
Definition complex.h:43
Definition complex.h:89
Definition private/v34.h:742
bool duplex
True if this is a full duplex modem.
Definition private/v34.h:746
void v34_rx_set_signal_cutoff(v34_state_t *s, float cutoff)
Definition v34rx.c:2668
int v34_rx(v34_state_t *s, const int16_t amp[], int len)
Process a block of received V.34 modem audio samples.
Definition v34rx.c:2632
void v34_set_qam_report_handler(v34_state_t *s, qam_report_handler_t handler, void *user_data)
Definition v34rx.c:2798
void v34_tx_power(v34_state_t *s, float power)
Adjust a V.34 modem transmit context's output power.
Definition v34tx.c:2894
int v34_tx(v34_state_t *s, int16_t amp[], int len)
Generate a block of V.34 modem audio samples.
Definition v34tx.c:2857
int v34_free(v34_state_t *s)
Free a V.34 modem receive context.
Definition v34tx.c:3230
void v34_set_put_bit(v34_state_t *s, span_put_bit_func_t put_bit, void *user_data)
Change the put_bit function associated with a V.34 modem context.
Definition v34rx.c:2676
v34_state_t * v34_init(v34_state_t *s, int baud_rate, int bit_rate, bool calling_party, bool duplex, 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.34 modem context.
Definition v34tx.c:3155
int v34_release(v34_state_t *s)
Release a V.34 modem receive context.
Definition v34tx.c:3224
int v34_half_duplex_change_mode(v34_state_t *s, int mode)
Change the operating mode of a V.34 half-duplex modem.
Definition v34tx.c:2990
int v34_restart(v34_state_t *s, int baud_rate, int bit_rate, bool duplex)
Reinitialise an existing V.34 modem context.
Definition v34tx.c:3121
void v34_set_put_aux_bit(v34_state_t *s, span_put_bit_func_t put_bit, void *user_data)
Change the put_aux_bit function associated with a V.34 modem context.
Definition v34rx.c:2683
float v34_rx_symbol_timing_correction(v34_state_t *s)
int v34_equalizer_state(v34_state_t *s, complexf_t **coeffs)
Get a snapshot of the current equalizer coefficients.
void v34_set_get_aux_bit(v34_state_t *s, span_get_bit_func_t get_bit, void *user_data)
Change the get_aux_bit function associated with a V.34 modem context.
Definition v34tx.c:2916
int v34_rx_fillin(v34_state_t *s, int len)
Fake processing of a missing block of received V.34 modem audio samples.
Definition v34rx.c:2612
float v34_rx_carrier_frequency(v34_state_t *s)
Definition v34rx.c:1612
logging_state_t * v34_get_logging_state(v34_state_t *s)
Get the logging context associated with a V.34 modem context.
Definition v34tx.c:2923
int v34_get_current_bit_rate(v34_state_t *s)
Report the current operating bit rate of a V.34 modem context.
Definition v34tx.c:2984
void v34_set_get_bit(v34_state_t *s, span_get_bit_func_t get_bit, void *user_data)
Change the get_bit function associated with a V.34 modem context.
Definition v34tx.c:2906
float v34_rx_signal_power(v34_state_t *s)
struct v34_state_s v34_state_t
Definition v34.h:79