spandsp  3.0.0
async.h
Go to the documentation of this file.
1 /*
2  * SpanDSP - a series of DSP components for telephony
3  *
4  * async.h - Asynchronous serial bit stream encoding and decoding
5  *
6  * Written by Steve Underwood <steveu@coppice.org>
7  *
8  * Copyright (C) 2003 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 async_page Asynchronous bit stream processing
29 \section async_page_sec_1 What does it do?
30 The asynchronous processing module converts between hard bit streams, containing
31 start-stop framed asynchronous characters, and actual characters.
32 
33 It supports:
34  - 5, 6, 7, 8 or 9 bit characters.
35  - Odd, even, mark, space or no parity.
36  - 1 or 2 stop bits.
37  - V.14 rate adaption.
38 
39 V.14 rate adaption is a mechanism where some stop bits may be omitted within a
40 data burst. This is needed to make inherently synchronous modems, like V.22 up to
41 V.34, behave like an asynchronous modem, and interface to the "RS232C" world.
42 Currently it only supports this for bit stream to character conversion.
43 
44 Soft bit processing is outside the scope of this module. For truly asynchronous
45 modems, such as V.21, soft bit processing can produce more robust results, and
46 may be preferrable.
47 
48 \section async_page_sec_2 The transmitter
49 ???.
50 
51 \section async_page_sec_3 The receiver
52 ???.
53 
54 Because the input to this module is a hard bit stream, any symbol synchronisation
55 and decoding must occur before this module, to provide the hard bit stream it
56 requires.
57 */
58 
59 #if !defined(_SPANDSP_ASYNC_H_)
60 #define _SPANDSP_ASYNC_H_
61 
62 /*! Special "bit" values for the bitstream put and get functions, and the signal status functions. */
63 enum
64 {
65  /*! \brief The carrier signal has dropped. */
67  /*! \brief The carrier signal is up. This merely indicates that carrier
68  energy has been seen. It is not an indication that the carrier is either
69  valid, or of the expected type. */
71  /*! \brief The modem is training. This is an early indication that the
72  signal seems to be of the right type. This may be needed in time critical
73  applications, like T.38, to forward an early indication of what is happening
74  on the wire. */
76  /*! \brief The modem has trained, and is ready for data exchange. */
78  /*! \brief The modem has failed to train. */
80  /*! \brief Packet framing (e.g. HDLC framing) is OK. */
82  /*! \brief The data stream has ended. */
84  /*! \brief An abort signal (e.g. an HDLC abort) has been received. */
86  /*! \brief A break signal (e.g. an async break) has been received. */
88  /*! \brief A modem has completed its task, and shut down. */
90  /*! \brief Regular octet report for things like HDLC to the MTP standards. */
92  /*! \brief Notification that a modem has detected signal quality degradation. */
94  /*! \brief Notification that a modem retrain has occurred. */
96  /*! \brief The link protocol (e.g. V.42) has connected. */
98  /*! \brief The link protocol (e.g. V.42) has disconnected. */
100  /*! \brief An error has occurred in the link protocol (e.g. V.42). */
102  /*! \brief Keep the link in an idle state, as there is nothing to send. */
104 };
105 
106 /*! Message put function for data pumps */
107 typedef void (*span_put_msg_func_t)(void *user_data, const uint8_t *msg, int len);
108 typedef void (*put_msg_func_t)(void *user_data, const uint8_t *msg, int len); /* For backward compatibility */
109 
110 /*! Message get function for data pumps */
111 typedef int (*span_get_msg_func_t)(void *user_data, uint8_t *msg, int max_len);
112 typedef int (*get_msg_func_t)(void *user_data, uint8_t *msg, int max_len); /* For backward compatibility */
113 
114 /*! Byte put function for data pumps */
115 typedef void (*span_put_byte_func_t)(void *user_data, int byte);
116 typedef void (*put_byte_func_t)(void *user_data, int byte); /* For backward compatibility */
117 
118 /*! Byte get function for data pumps */
119 typedef int (*span_get_byte_func_t)(void *user_data);
120 typedef int (*get_byte_func_t)(void *user_data); /* For backward compatibility */
121 
122 /*! Bit put function for data pumps */
123 typedef void (*span_put_bit_func_t)(void *user_data, int bit);
124 typedef void (*put_bit_func_t)(void *user_data, int bit); /* For backward compatibility */
125 
126 /*! Bit get function for data pumps */
127 typedef int (*span_get_bit_func_t)(void *user_data);
128 typedef int (*get_bit_func_t)(void *user_data); /* For backward compatibility */
129 
130 /*! Status change callback function for data pumps */
131 typedef void (*span_modem_status_func_t)(void *user_data, int status);
132 typedef void (*modem_status_func_t)(void *user_data, int status); /* For backward compatibility */
133 
134 /*!
135  Asynchronous data transmit descriptor. This defines the state of a single
136  working instance of a byte to asynchronous serial converter, for use
137  in FSK modems.
138 */
140 
141 /*!
142  Asynchronous data receive descriptor. This defines the state of a single
143  working instance of an asynchronous serial to byte converter, for use
144  in FSK modems.
145 */
147 
148 enum
149 {
150  /*! No parity bit should be used */
152  /*! An even parity bit will exist, after the data bits */
154  /*! An odd parity bit will exist, after the data bits */
156  ASYNC_PARITY_MARK,
157  ASYNC_PARITY_SPACE
158 };
159 
160 #if defined(__cplusplus)
161 extern "C"
162 {
163 #endif
164 
165 /*! Convert a signal status to a short text description.
166  \brief Convert a signal status to a short text description.
167  \param status The modem signal status.
168  \return A pointer to the description. */
169 SPAN_DECLARE(const char *) signal_status_to_str(int status);
170 
171 /*! Accept a bit from a received serial bit stream
172  \brief Accept a bit from a received serial bit stream
173  \param user_data An opaque point which must point to a receiver context.
174  \param bit The new bit. Some special values are supported for this field.
175  - SIG_STATUS_CARRIER_UP
176  - SIG_STATUS_CARRIER_DOWN
177  - SIG_STATUS_TRAINING_SUCCEEDED
178  - SIG_STATUS_TRAINING_FAILED
179  - SIG_STATUS_END_OF_DATA */
180 SPAN_DECLARE(void) async_rx_put_bit(void *user_data, int bit);
181 
182 SPAN_DECLARE(int) async_rx_get_parity_errors(async_rx_state_t *s, bool reset);
183 
184 SPAN_DECLARE(int) async_rx_get_framing_errors(async_rx_state_t *s, bool reset);
185 
186 /*! Initialise an asynchronous data receiver context.
187  \brief Initialise an asynchronous data receiver context.
188  \param s The receiver context.
189  \param data_bits The number of data bits.
190  \param parity The type of parity.
191  \param stop_bits The number of stop bits.
192  \param use_v14 True if V.14 rate adaption processing should be used.
193  \param put_byte The callback routine used to put the received data.
194  \param user_data An opaque pointer.
195  \return A pointer to the initialised context, or NULL if there was a problem. */
197  int data_bits,
198  int parity,
199  int stop_bits,
200  bool use_v14,
202  void *user_data);
203 
204 SPAN_DECLARE(int) async_rx_release(async_rx_state_t *s);
205 
206 SPAN_DECLARE(int) async_rx_free(async_rx_state_t *s);
207 
208 /*! Set a minimum number of bit times of stop bit state before character transmission commences.
209  \brief Set a minimum number of bit times of stop bit state before character transmission commences.
210  \param user_data An opaque point which must point to a transmitter context.
211  \param the number of bits. */
212 SPAN_DECLARE(void) async_tx_presend_bits(async_tx_state_t *s, int bits);
213 
214 /*! Get the next bit of a transmitted serial bit stream.
215  \brief Get the next bit of a transmitted serial bit stream.
216  \param user_data An opaque point which must point to a transmitter context.
217  \return the next bit, or a status value passed through from the routine which
218  gets the data bytes. */
219 SPAN_DECLARE(int) async_tx_get_bit(void *user_data);
220 
221 /*! Initialise an asynchronous data transmit context.
222  \brief Initialise an asynchronous data transmit context.
223  \param s The transmitter context.
224  \param data_bits The number of data bit.
225  \param parity The type of parity.
226  \param stop_bits The number of stop bits.
227  \param use_v14 True if V.14 rate adaption processing should be used.
228  \param get_byte The callback routine used to get the data to be transmitted.
229  \param user_data An opaque pointer.
230  \return A pointer to the initialised context, or NULL if there was a problem. */
232  int data_bits,
233  int parity,
234  int stop_bits,
235  bool use_v14,
236  span_get_byte_func_t get_byte,
237  void *user_data);
238 
239 SPAN_DECLARE(int) async_tx_release(async_tx_state_t *s);
240 
241 SPAN_DECLARE(int) async_tx_free(async_tx_state_t *s);
242 
243 #if defined(__cplusplus)
244 }
245 #endif
246 
247 #endif
248 /*- End of file ------------------------------------------------------------*/
The data stream has ended.
Definition: async.h:83
The carrier signal is up. This merely indicates that carrier energy has been seen. It is not an indication that the carrier is either valid, or of the expected type.
Definition: async.h:70
int16_t data_bits
The number of data bits per character.
Definition: private/async.h:65
Notification that a modem retrain has occurred.
Definition: async.h:95
An abort signal (e.g. an HDLC abort) has been received.
Definition: async.h:85
void * user_data
An opaque pointer passed when calling put_byte.
Definition: private/async.h:75
const char * signal_status_to_str(int status)
Convert a signal status to a short text description.
Definition: async.c:49
int async_tx_get_bit(void *user_data)
Get the next bit of a transmitted serial bit stream.
Definition: async.c:277
int(* span_get_bit_func_t)(void *user_data)
Definition: async.h:127
span_put_byte_func_t put_byte
A pointer to the callback routine used to handle received characters.
Definition: private/async.h:73
Regular octet report for things like HDLC to the MTP standards.
Definition: async.h:91
The link protocol (e.g. V.42) has disconnected.
Definition: async.h:99
Definition: async.h:151
int(* span_get_msg_func_t)(void *user_data, uint8_t *msg, int max_len)
Definition: async.h:111
void(* span_modem_status_func_t)(void *user_data, int status)
Definition: async.h:131
void(* span_put_bit_func_t)(void *user_data, int bit)
Definition: async.h:123
Notification that a modem has detected signal quality degradation.
Definition: async.h:93
void(* span_put_msg_func_t)(void *user_data, const uint8_t *msg, int len)
Definition: async.h:107
Definition: async.h:155
void async_rx_put_bit(void *user_data, int bit)
Accept a bit from a received serial bit stream.
Definition: async.c:93
Packet framing (e.g. HDLC framing) is OK.
Definition: async.h:81
The modem has trained, and is ready for data exchange.
Definition: async.h:77
int(* span_get_byte_func_t)(void *user_data)
Definition: async.h:119
The modem has failed to train.
Definition: async.h:79
Definition: private/async.h:62
The carrier signal has dropped.
Definition: async.h:66
An error has occurred in the link protocol (e.g. V.42).
Definition: async.h:101
async_tx_state_t * async_tx_init(async_tx_state_t *s, int data_bits, int parity, int stop_bits, bool use_v14, span_get_byte_func_t get_byte, void *user_data)
Initialise an asynchronous data transmit context.
Definition: async.c:347
Keep the link in an idle state, as there is nothing to send.
Definition: async.h:103
The link protocol (e.g. V.42) has connected.
Definition: async.h:97
bool use_v14
True if V.14 rate adaption processing should be performed.
Definition: private/async.h:71
async_rx_state_t * async_rx_init(async_rx_state_t *s, int data_bits, int parity, int stop_bits, bool use_v14, span_put_byte_func_t put_byte, void *user_data)
Initialise an asynchronous data receiver context.
Definition: async.c:227
Definition: private/async.h:34
The modem is training. This is an early indication that the signal seems to be of the right type...
Definition: async.h:75
Definition: async.h:153
int16_t parity
The type of parity.
Definition: private/async.h:67
void async_tx_presend_bits(async_tx_state_t *s, int bits)
Set a minimum number of bit times of stop bit state before character transmission commences...
Definition: async.c:341
void(* span_put_byte_func_t)(void *user_data, int byte)
Definition: async.h:115
A break signal (e.g. an async break) has been received.
Definition: async.h:87
A modem has completed its task, and shut down.
Definition: async.h:89