spandsp  3.0.0
v32bis.h
Go to the documentation of this file.
1 /*
2  * SpanDSP - a series of DSP components for telephony
3  *
4  * v32bis.h - ITU V.32bis modem
5  *
6  * Written by Steve Underwood <steveu@coppice.org>
7  *
8  * Copyright (C) 2008 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 /* V.32bis SUPPORT IS A WORK IN PROGRESS - NOT YET FUNCTIONAL! */
27 
28 /*! \file */
29 
30 /*! \page v32bis_page The V.32bis modem
31 \section v32bis_page_sec_1 What does it do?
32 
33 \section v32bis__page_sec_2 How does it work?
34 */
35 
36 #if !defined(_SPANDSP_V32BIS_H_)
37 #define _SPANDSP_V32BIS_H_
38 
39 #if defined(SPANDSP_USE_FIXED_POINT)
40 #define V32BIS_CONSTELLATION_SCALING_FACTOR 4096.0
41 #else
42 #define V32BIS_CONSTELLATION_SCALING_FACTOR 1.0
43 #endif
44 
45 enum
46 {
47  V32BIS_RATE_14400 = 0x1000,
48  V32BIS_RATE_12000 = 0x0400,
49  V32BIS_RATE_9600 = 0x0200,
50  V32BIS_RATE_7200 = 0x0040,
51  V32BIS_RATE_4800 = 0x0020
52 };
53 
54 /*!
55  V.32bis modem descriptor. This defines the working state for a single instance
56  of a V.32bis modem.
57 */
59 
60 #if defined(__cplusplus)
61 extern "C"
62 {
63 #endif
64 
65 /*! Reinitialise an existing V.32bis modem receive context.
66  \brief Reinitialise an existing V.32bis modem receive context.
67  \param s The modem context.
68  \param bit_rate The bit rate of the modem. Valid values are 1200 and 2400.
69  \return 0 for OK, -1 for bad parameter */
70 SPAN_DECLARE(int) v32bis_rx_restart(v32bis_state_t *s, int bit_rate);
71 
72 /*! Process a block of received V.32bis modem audio samples.
73  \brief Process a block of received V.32bis modem audio samples.
74  \param s The modem context.
75  \param amp The audio sample buffer.
76  \param len The number of samples in the buffer.
77  \return The number of samples unprocessed. */
78 SPAN_DECLARE(int) v32bis_rx(v32bis_state_t *s, const int16_t amp[], int len);
79 
80 /*! Fake processing of a missing block of received V.32bis modem audio samples.
81  (e.g due to packet loss).
82  \brief Fake processing of a missing block of received V.32bis modem audio samples.
83  \param s The modem context.
84  \param len The number of samples to fake.
85  \return The number of samples unprocessed. */
86 SPAN_DECLARE(int) v32bis_rx_fillin(v32bis_state_t *s, int len);
87 
88 /*! Get a snapshot of the current equalizer coefficients.
89  \brief Get a snapshot of the current equalizer coefficients.
90  \param coeffs The vector of complex coefficients.
91  \return The number of coefficients in the vector. */
92 #if defined(SPANDSP_USE_FIXED_POINT)
93 SPAN_DECLARE(int) v32bis_equalizer_state(v32bis_state_t *s, complexi16_t **coeffs);
94 #else
95 SPAN_DECLARE(int) v32bis_equalizer_state(v32bis_state_t *s, complexf_t **coeffs);
96 #endif
97 
98 /*! Get the current received carrier frequency.
99  \param s The modem context.
100  \return The frequency, in Hertz. */
101 SPAN_DECLARE(float) v32bis_rx_carrier_frequency(v32bis_state_t *s);
102 
103 /*! Get the current symbol timing correction since startup.
104  \param s The modem context.
105  \return The correction. */
106 SPAN_DECLARE(float) v32bis_rx_symbol_timing_correction(v32bis_state_t *s);
107 
108 /*! Get a current received signal power.
109  \param s The modem context.
110  \return The signal power, in dBm0. */
111 SPAN_DECLARE(float) v32bis_rx_signal_power(v32bis_state_t *s);
112 
113 /*! Set the power level at which the carrier detection will cut in
114  \param s The modem context.
115  \param cutoff The signal cutoff power, in dBm0. */
116 SPAN_DECLARE(void) v32bis_rx_set_signal_cutoff(v32bis_state_t *s, float cutoff);
117 
118 /*! Set a handler routine to process QAM status reports
119  \param s The modem context.
120  \param handler The handler routine.
121  \param user_data An opaque pointer passed to the handler routine. */
122 SPAN_DECLARE(void) v32bis_set_qam_report_handler(v32bis_state_t *s, qam_report_handler_t handler, void *user_data);
123 
124 /*! Generate a block of V.32bis modem audio samples.
125  \brief Generate a block of V.32bis modem audio samples.
126  \param s The modem context.
127  \param amp The audio sample buffer.
128  \param len The number of samples to be generated.
129  \return The number of samples actually generated. */
130 SPAN_DECLARE(int) v32bis_tx(v32bis_state_t *s, int16_t amp[], int len);
131 
132 /*! Adjust a V.32bis modem transmit context's power output.
133  \brief Adjust a V.32bis modem transmit context's output power.
134  \param s The modem context.
135  \param power The power level, in dBm0 */
136 SPAN_DECLARE(void) v32bis_tx_power(v32bis_state_t *s, float power);
137 
138 /*! Set the supported bit rates for a V.32bis modem context.
139  \brief Set the supported bit rates for a V.32bis modem context.
140  \param s The modem context.
141  \param rates The bit rate mask
142  \return 0 for OK, -1 for bad parameter. */
143 SPAN_DECLARE(int) v32bis_set_supported_bit_rates(v32bis_state_t *s, int rates);
144 
145 /*! Report the current operating bit rate of a V.32bis modem context.
146  \brief Report the current operating bit rate of a V.22bis modem context
147  \param s The modem context. */
148 SPAN_DECLARE(int) v32bis_current_bit_rate(v32bis_state_t *s);
149 
150 /*! Reinitialise an existing V.32bis modem context, so it may be reused.
151  \brief Reinitialise an existing V.32bis modem context.
152  \param s The modem context.
153  \param bit_rate The bit rate of the modem. Valid values are 4800, 7200, 9600, 12000 and 14400.
154  \return 0 for OK, -1 for bad parameter. */
155 SPAN_DECLARE(int) v32bis_restart(v32bis_state_t *s, int bit_rate);
156 
157 /*! Initialise a V.32bis modem context. This must be called before the first
158  use of the context, to initialise its contents.
159  \brief Initialise a V.32bis modem context.
160  \param s The modem context.
161  \param bit_rate The bit rate of the modem. Valid values are 4800, 7200, 9600, 12000 and 14400.
162  \param calling_party True if this is the calling modem.
163  \param get_bit The callback routine used to get the data to be transmitted.
164  \param get_bit_user_data An opaque pointer, passed in calls to the get routine.
165  \param put_bit The callback routine used to get the data to be transmitted.
166  \param put_bit_user_data An opaque pointer, passed in calls to the put routine.
167  \return A pointer to the modem context, or NULL if there was a problem.
168  \param get_bit_user_data An opaque pointer, passed in calls to the put routine. */
169 SPAN_DECLARE(v32bis_state_t *) v32bis_init(v32bis_state_t *s,
170  int bit_rate,
171  bool calling_party,
172  get_bit_func_t get_bit,
173  void *get_bit_user_data,
174  put_bit_func_t put_bit,
175  void *put_bit_user_data);
176 
177 /*! Release a V.32bis modem receive context.
178  \brief Release a V.32bis modem receive context.
179  \param s The modem context.
180  \return 0 for OK */
181 SPAN_DECLARE(int) v32bis_release(v32bis_state_t *s);
182 
183 /*! Free a V.32bis modem receive context.
184  \brief Free a V.32bis modem receive context.
185  \param s The modem context.
186  \return 0 for OK */
187 SPAN_DECLARE(int) v32bis_free(v32bis_state_t *s);
188 
189 /*! Get the logging context associated with a V.32bis modem context.
190  \brief Get the logging context associated with a V.32bis modem context.
191  \param s The modem context.
192  \return A pointer to the logging context */
194 
195 /*! Change the get_bit function associated with a V.32bis modem context.
196  \brief Change the get_bit function associated with a V.32bis modem context.
197  \param s The modem context.
198  \param get_bit The callback routine used to get the data to be transmitted.
199  \param user_data An opaque pointer. */
200 SPAN_DECLARE(void) v32bis_set_get_bit(v32bis_state_t *s, get_bit_func_t get_bit, void *user_data);
201 
202 /*! Change the get_bit function associated with a V.32bis modem context.
203  \brief Change the put_bit function associated with a V.32bis modem context.
204  \param s The modem context.
205  \param put_bit The callback routine used to process the data received.
206  \param user_data An opaque pointer. */
207 SPAN_DECLARE(void) v32bis_set_put_bit(v32bis_state_t *s, put_bit_func_t put_bit, void *user_data);
208 
209 #if defined(__cplusplus)
210 }
211 #endif
212 
213 #endif
214 /*- End of file ------------------------------------------------------------*/
int v32bis_rx_fillin(v32bis_state_t *s, int len)
Fake processing of a missing block of received V.32bis modem audio samples.
Definition: v32bis.c:130
Definition: complex.h:88
v32bis_state_t * v32bis_init(v32bis_state_t *s, int bit_rate, bool 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.32bis modem context.
Definition: v32bis.c:184
float v32bis_rx_carrier_frequency(v32bis_state_t *s)
Definition: v32bis.c:100
float v32bis_rx_signal_power(v32bis_state_t *s)
Definition: v32bis.c:112
void v32bis_set_put_bit(v32bis_state_t *s, put_bit_func_t put_bit, void *user_data)
Change the put_bit function associated with a V.32bis modem context.
Definition: v32bis.c:148
int v32bis_rx_restart(v32bis_state_t *s, int bit_rate)
Reinitialise an existing V.32bis modem receive context.
int v32bis_equalizer_state(v32bis_state_t *s, complexf_t **coeffs)
Get a snapshot of the current equalizer coefficients.
Definition: v32bis.c:93
float v32bis_rx_symbol_timing_correction(v32bis_state_t *s)
Definition: v32bis.c:106
int v32bis_set_supported_bit_rates(v32bis_state_t *s, int rates)
Set the supported bit rates for a V.32bis modem context.
Definition: v32bis.c:154
void v32bis_rx_set_signal_cutoff(v32bis_state_t *s, float cutoff)
int bit_rate
The bit rate of the modem. Valid values are 1200 and 2400.
Definition: private/v32bis.h:40
int v32bis_restart(v32bis_state_t *s, int bit_rate)
Reinitialise an existing V.32bis modem context.
Definition: v32bis.c:175
Definition: complex.h:42
int v32bis_tx(v32bis_state_t *s, int16_t amp[], int len)
Generate a block of V.32bis modem audio samples.
Definition: v32bis.c:118
Definition: private/logging.h:33
void v32bis_tx_power(v32bis_state_t *s, float power)
Adjust a V.32bis modem transmit context&#39;s output power.
Definition: v32bis.c:136
int v32bis_release(v32bis_state_t *s)
Release a V.32bis modem receive context.
Definition: v32bis.c:230
void v32bis_set_get_bit(v32bis_state_t *s, get_bit_func_t get_bit, void *user_data)
Change the get_bit function associated with a V.32bis modem context.
Definition: v32bis.c:142
Definition: private/v32bis.h:37
int v32bis_rx(v32bis_state_t *s, const int16_t amp[], int len)
Process a block of received V.32bis modem audio samples.
Definition: v32bis.c:124
int v32bis_current_bit_rate(v32bis_state_t *s)
Report the current operating bit rate of a V.22bis modem context.
Definition: v32bis.c:163
int v32bis_free(v32bis_state_t *s)
Free a V.32bis modem receive context.
Definition: v32bis.c:238
bool calling_party
True is this is the calling side modem.
Definition: private/v32bis.h:42
void v32bis_set_qam_report_handler(v32bis_state_t *s, qam_report_handler_t handler, void *user_data)
Definition: v32bis.c:245
logging_state_t * v32bis_get_logging_state(v32bis_state_t *s)
Get the logging context associated with a V.32bis modem context.
Definition: v32bis.c:169