|
5
|
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 General Public License version 2, as
|
|
|
14 * 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 General Public License for more details.
|
|
|
20 *
|
|
|
21 * You should have received a copy of the GNU General Public License
|
|
|
22 * along with this program; if not, write to the Free Software
|
|
|
23 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
|
|
|
24 *
|
|
|
25 * $Id: async.h,v 1.6 2006/10/24 13:22:01 steveu Exp $
|
|
|
26 */
|
|
|
27
|
|
|
28 /*! \file */
|
|
|
29
|
|
|
30 /*! \page async_page Asynchronous bit stream processing
|
|
|
31 \section async_page_sec_1 What does it do?
|
|
|
32 The asynchronous serial bit stream processing module provides
|
|
|
33 generation and decoding facilities for most asynchronous data
|
|
|
34 formats. It supports:
|
|
|
35 - 1 or 2 stop bits.
|
|
|
36 - Odd, even or no parity.
|
|
|
37 - 5, 6, 7, or 8 bit characters.
|
|
|
38 - V.14 rate adaption.
|
|
|
39 The input to this module is a bit stream. This means any symbol synchronisation
|
|
|
40 and decoding must occur before data is fed to this module.
|
|
|
41
|
|
|
42 \section async_page_sec_2 The transmitter
|
|
|
43 ???.
|
|
|
44
|
|
|
45 \section async_page_sec_3 The receiver
|
|
|
46 ???.
|
|
|
47 */
|
|
|
48
|
|
|
49 #if !defined(_ASYNC_H_)
|
|
|
50 #define _ASYNC_H_
|
|
|
51
|
|
|
52 /* Special "bit" values for the put and get bit functions */
|
|
|
53 enum
|
|
|
54 {
|
|
|
55 /*! \brief The carrier signal has dropped. */
|
|
|
56 PUTBIT_CARRIER_DOWN = -1,
|
|
|
57 /*! \brief The carrier signal is up. This merely indicates that carrier
|
|
|
58 energy has been seen. It is not an indication that the carrier is either
|
|
|
59 valid, or of the expected type. */
|
|
|
60 PUTBIT_CARRIER_UP = -2,
|
|
|
61 /*! \brief The modem is training. This is an early indication that the
|
|
|
62 signal seems to be of the right type. This may be needed in time critical
|
|
|
63 applications, like T.38, to forward an early indication of what is happening
|
|
|
64 on the wire. */
|
|
|
65 PUTBIT_TRAINING_IN_PROGRESS = -3,
|
|
|
66 /*! \brief The modem has trained, and is ready for data exchange. */
|
|
|
67 PUTBIT_TRAINING_SUCCEEDED = -4,
|
|
|
68 /*! \brief The modem has failed to train. */
|
|
|
69 PUTBIT_TRAINING_FAILED = -5,
|
|
|
70 /*! \brief Packet framing (e.g. HDLC framing) is OK. */
|
|
|
71 PUTBIT_FRAMING_OK = -6,
|
|
|
72 /*! \brief The data stream has ended. */
|
|
|
73 PUTBIT_END_OF_DATA = -7,
|
|
|
74 /*! \brief An abort signal (e.g. an HDLC abort) has been received. */
|
|
|
75 PUTBIT_ABORT = -8,
|
|
|
76 /*! \brief A break signal (e.g. an async break) has been received. */
|
|
|
77 PUTBIT_BREAK = -9
|
|
|
78 };
|
|
|
79
|
|
|
80 /*! Message put function for data pumps */
|
|
|
81 typedef void (*put_msg_func_t)(void *user_data, const uint8_t *msg, int len);
|
|
|
82
|
|
|
83 /*! Message get function for data pumps */
|
|
|
84 typedef int (*get_msg_func_t)(void *user_data, uint8_t *msg, int max_len);
|
|
|
85
|
|
|
86 /*! Byte put function for data pumps */
|
|
|
87 typedef void (*put_byte_func_t)(void *user_data, int byte);
|
|
|
88
|
|
|
89 /*! Byte get function for data pumps */
|
|
|
90 typedef int (*get_byte_func_t)(void *user_data);
|
|
|
91
|
|
|
92 /*! Bit put function for data pumps */
|
|
|
93 typedef void (*put_bit_func_t)(void *user_data, int bit);
|
|
|
94
|
|
|
95 /*! Bit get function for data pumps */
|
|
|
96 typedef int (*get_bit_func_t)(void *user_data);
|
|
|
97
|
|
|
98 /*! No parity bit should be used */
|
|
|
99 #define ASYNC_PARITY_NONE 0
|
|
|
100 /*! An even parity bit will exist, after the data bits */
|
|
|
101 #define ASYNC_PARITY_EVEN 1
|
|
|
102 /*! An odd parity bit will exist, after the data bits */
|
|
|
103 #define ASYNC_PARITY_ODD 2
|
|
|
104
|
|
|
105 /*!
|
|
|
106 Asynchronous data transmit descriptor. This defines the state of a single
|
|
|
107 working instance of a byte to asynchronous serial converter, for use
|
|
|
108 in FSK modems.
|
|
|
109 */
|
|
|
110 typedef struct
|
|
|
111 {
|
|
|
112 /*! \brief The number of data bits per character. */
|
|
|
113 int data_bits;
|
|
|
114 /*! \brief The type of parity. */
|
|
|
115 int parity;
|
|
|
116 /*! \brief The number of stop bits per character. */
|
|
|
117 int stop_bits;
|
|
|
118 /*! \brief A pointer to the callback routine used to get characters to be transmitted. */
|
|
|
119 get_byte_func_t get_byte;
|
|
|
120 /*! \brief An opaque pointer passed when calling get_byte. */
|
|
|
121 void *user_data;
|
|
|
122
|
|
|
123 /*! \brief A current, partially transmitted, character. */
|
|
|
124 int byte_in_progress;
|
|
|
125 /*! \brief The current bit position within a partially transmitted character. */
|
|
|
126 int bitpos;
|
|
|
127 int parity_bit;
|
|
|
128 } async_tx_state_t;
|
|
|
129
|
|
|
130 /*!
|
|
|
131 Asynchronous data receive descriptor. This defines the state of a single
|
|
|
132 working instance of an asynchronous serial to byte converter, for use
|
|
|
133 in FSK modems.
|
|
|
134 */
|
|
|
135 typedef struct
|
|
|
136 {
|
|
|
137 /*! \brief The number of data bits per character. */
|
|
|
138 int data_bits;
|
|
|
139 /*! \brief The type of parity. */
|
|
|
140 int parity;
|
|
|
141 /*! \brief The number of stop bits per character. */
|
|
|
142 int stop_bits;
|
|
|
143 /*! \brief TRUE if V.14 rate adaption processing should be performed. */
|
|
|
144 int use_v14;
|
|
|
145 /*! \brief A pointer to the callback routine used to handle received characters. */
|
|
|
146 put_byte_func_t put_byte;
|
|
|
147 /*! \brief An opaque pointer passed when calling put_byte. */
|
|
|
148 void *user_data;
|
|
|
149
|
|
|
150 /*! \brief A current, partially complete, character. */
|
|
|
151 int byte_in_progress;
|
|
|
152 /*! \brief The current bit position within a partially complete character. */
|
|
|
153 int bitpos;
|
|
|
154 int parity_bit;
|
|
|
155
|
|
|
156 int parity_errors;
|
|
|
157 int framing_errors;
|
|
|
158 } async_rx_state_t;
|
|
|
159
|
|
|
160 #ifdef __cplusplus
|
|
|
161 extern "C" {
|
|
|
162 #endif
|
|
|
163
|
|
|
164 /*! Initialise an asynchronous data transmit context.
|
|
|
165 \brief Initialise an asynchronous data transmit context.
|
|
|
166 \param s The transmitter context.
|
|
|
167 \param data_bits The number of data bit.
|
|
|
168 \param parity_bits The type of parity.
|
|
|
169 \param stop_bits The number of stop bits.
|
|
|
170 \param use_v14 TRUE if V.14 rate adaption processing should be used.
|
|
|
171 \param get_byte The callback routine used to get the data to be transmitted.
|
|
|
172 \param user_data An opaque pointer. */
|
|
|
173 void async_tx_init(async_tx_state_t *s,
|
|
|
174 int data_bits,
|
|
|
175 int parity_bits,
|
|
|
176 int stop_bits,
|
|
|
177 int use_v14,
|
|
|
178 get_byte_func_t get_byte,
|
|
|
179 void *user_data);
|
|
|
180
|
|
|
181 /*! Get the next bit of a transmitted serial bit stream.
|
|
|
182 \brief Get the next bit of a transmitted serial bit stream.
|
|
|
183 \param user_data An opaque point which must point to a transmitter context.
|
|
|
184 \return the next bit, or PUTBIT_END_OF_DATA to indicate the data stream has ended. */
|
|
|
185 int async_tx_get_bit(void *user_data);
|
|
|
186
|
|
|
187 /*! Initialise an asynchronous data receiver context.
|
|
|
188 \brief Initialise an asynchronous data receiver context.
|
|
|
189 \param s The receiver context.
|
|
|
190 \param data_bits The number of data bits.
|
|
|
191 \param parity_bits The type of parity.
|
|
|
192 \param stop_bits The number of stop bits.
|
|
|
193 \param use_v14 TRUE if V.14 rate adaption processing should be used.
|
|
|
194 \param put_byte The callback routine used to put the received data.
|
|
|
195 \param user_data An opaque pointer. */
|
|
|
196 void async_rx_init(async_rx_state_t *s,
|
|
|
197 int data_bits,
|
|
|
198 int parity_bits,
|
|
|
199 int stop_bits,
|
|
|
200 int use_v14,
|
|
|
201 put_byte_func_t put_byte,
|
|
|
202 void *user_data);
|
|
|
203
|
|
|
204 /*! Accept a bit from a received serial bit stream
|
|
|
205 \brief Accept a bit from a received serial bit stream
|
|
|
206 \param user_data An opaque point which must point to a receiver context.
|
|
|
207 \param bit The new bit. Some special values are supported for this field.
|
|
|
208 - PUTBIT_CARRIER_UP
|
|
|
209 - PUTBIT_CARRIER_DOWN
|
|
|
210 - PUTBIT_TRAINING_SUCCEEDED
|
|
|
211 - PUTBIT_TRAINING_FAILED
|
|
|
212 - PUTBIT_END_OF_DATA */
|
|
|
213 void async_rx_put_bit(void *user_data, int bit);
|
|
|
214
|
|
|
215 #ifdef __cplusplus
|
|
|
216 }
|
|
|
217 #endif
|
|
|
218
|
|
|
219 #endif
|
|
|
220 /*- End of file ------------------------------------------------------------*/
|
