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 
43 enum 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 
61 enum 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 */
79 typedef struct v34_state_s v34_state_t;
80 
81 #if defined(__cplusplus)
82 extern "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. */
92 SPAN_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. */
100 SPAN_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)
107 SPAN_DECLARE(int) v34_equalizer_state(v34_state_t *s, complexi16_t **coeffs);
108 #else
109 SPAN_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. */
115 SPAN_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. */
120 SPAN_DECLARE(float) v34_rx_symbol_timing_correction(v34_state_t *s);
121 
122 /*! Get a current received signal power.
123  \param s The modem context.
124  \return The signal power, in dBm0. */
125 SPAN_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. */
130 SPAN_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. */
136 SPAN_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. */
144 SPAN_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 */
150 SPAN_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 ??? */
156 SPAN_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 ??? */
163 SPAN_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 */
172 SPAN_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. */
187 SPAN_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 */
201 SPAN_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 */
207 SPAN_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. */
220 SPAN_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. */
227 SPAN_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. */
234 SPAN_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. */
241 SPAN_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 v34_tx(v34_state_t *s, int16_t amp[], int len)
Generate a block of V.34 modem audio samples.
Definition: v34tx.c:2857
float v34_rx_carrier_frequency(v34_state_t *s)
Definition: v34rx.c:1612
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
Definition: complex.h:88
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
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
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_equalizer_state(v34_state_t *s, complexf_t **coeffs)
Get a snapshot of the current equalizer coefficients.
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
int v34_free(v34_state_t *s)
Free a V.34 modem receive context.
Definition: v34tx.c:3230
int(* span_get_bit_func_t)(void *user_data)
Definition: async.h:127
float v34_rx_signal_power(v34_state_t *s)
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
bool duplex
True if this is a full duplex modem.
Definition: private/v34.h:746
float v34_rx_symbol_timing_correction(v34_state_t *s)
void v34_set_qam_report_handler(v34_state_t *s, qam_report_handler_t handler, void *user_data)
Definition: v34rx.c:2798
void(* span_put_bit_func_t)(void *user_data, int bit)
Definition: async.h:123
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
void v34_rx_set_signal_cutoff(v34_state_t *s, float cutoff)
Definition: v34rx.c:2668
Definition: private/v34.h:741
Definition: complex.h:42
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
Definition: private/logging.h:33
int bit_rate
The bit rate of the modem.
Definition: private/v34.h:752
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
bool calling_party
True if this is the calling side modem.
Definition: private/v34.h:744
int v34_release(v34_state_t *s)
Release a V.34 modem receive context.
Definition: v34tx.c:3224
void v34_tx_power(v34_state_t *s, float power)
Adjust a V.34 modem transmit context&#39;s output power.
Definition: v34tx.c:2894
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
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