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
45enum
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)
61extern "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 */
70SPAN_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. */
78SPAN_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. */
86SPAN_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)
93SPAN_DECLARE(int) v32bis_equalizer_state(v32bis_state_t *s, complexi16_t **coeffs);
94#else
95SPAN_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. */
101SPAN_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. */
107
108/*! Get a current received signal power.
109 \param s The modem context.
110 \return The signal power, in dBm0. */
111SPAN_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. */
116SPAN_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. */
122SPAN_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. */
130SPAN_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 */
136SPAN_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. */
143SPAN_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. */
148SPAN_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. */
155SPAN_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. */
169SPAN_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 */
181SPAN_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 */
187SPAN_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. */
200SPAN_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. */
207SPAN_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 ------------------------------------------------------------*/
struct logging_state_s logging_state_t
Definition logging.h:72
Definition complex.h:43
Definition complex.h:89
Definition private/v32bis.h:38
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
void v32bis_tx_power(v32bis_state_t *s, float power)
Adjust a V.32bis modem transmit context's output power.
Definition v32bis.c:136
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
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
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
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
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
int v32bis_rx_restart(v32bis_state_t *s, int bit_rate)
Reinitialise an existing V.32bis modem receive context.
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_restart(v32bis_state_t *s, int bit_rate)
Reinitialise an existing V.32bis modem context.
Definition v32bis.c:175
int v32bis_release(v32bis_state_t *s)
Release a V.32bis modem receive context.
Definition v32bis.c:230
struct v32bis_state_s v32bis_state_t
Definition v32bis.h:58
int v32bis_free(v32bis_state_t *s)
Free a V.32bis modem receive context.
Definition v32bis.c:238
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 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
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
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
void v32bis_set_qam_report_handler(v32bis_state_t *s, qam_report_handler_t handler, void *user_data)
Definition v32bis.c:245