Mercurial > hg > audiostuff

comparison spandsp-0.0.3/spandsp-0.0.3/src/spandsp/hdlc.h @ 5:f762bf195c4b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
import spandsp-0.0.3
author Peter Meerwald <pmeerw@cosy.sbg.ac.at>
date Fri, 25 Jun 2010 16:00:21 +0200
parents
children
comparison
equal deleted inserted replaced
4:26cd8f1ef0b1 5:f762bf195c4b
1 /*
2 * SpanDSP - a series of DSP components for telephony
3 *
4 * hdlc.h
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: hdlc.h,v 1.27 2006/10/24 13:45:28 steveu Exp $
26 */
27
28 /*! \file */
29
30 /*! \page hdlc_page HDLC
31
32 \section hdlc_page_sec_1 What does it do?
33 The HDLC module provides bit stuffing, destuffing, framing and deframing,
34 according to the HDLC protocol. It also provides 16 and 32 bit CRC generation
35 and checking services for HDLC frames.
36
37 HDLC may not be a DSP function, but is needed to accompany several DSP components.
38
39 \section hdlc_page_sec_2 How does it work?
40 */
41
42
43 #if !defined(_HDLC_H_)
44 #define _HDLC_H_
45
46 /*!
47 HDLC_MAXFRAME_LEN is the maximum length of a stuffed HDLC frame, excluding the CRC.
48 */
49 #define HDLC_MAXFRAME_LEN 400
50
51 typedef void (*hdlc_frame_handler_t)(void *user_data, int ok, const uint8_t *pkt, int len);
52 typedef void (*hdlc_underflow_handler_t)(void *user_data);
53
54 /*!
55 HDLC receive descriptor. This contains all the state information for an HDLC receiver.
56 */
57 typedef struct
58 {
59 /*! 2 for CRC-16, 4 for CRC-32 */
60 int crc_bytes;
61 /*! \brief The callback routine called to process each good received frame. */
62 hdlc_frame_handler_t frame_handler;
63 /*! \brief An opaque parameter passed to the callback routine. */
64 void *user_data;
65 /*! \brief TRUE if bad frames are to be reported. */
66 int report_bad_frames;
67 /*! \brief The number of consecutive flags which must be seen before framing is
68 declared OK. */
69 int framing_ok_threshold;
70 /*! \brief TRUE if framing OK has been announced. */
71 int framing_ok_announced;
72 /*! \brief Number of consecutive flags seen so far. */
73 int flags_seen;
74
75 /*! \brief The raw (stuffed) bit stream buffer. */
76 unsigned int raw_bit_stream;
77 /*! \brief The destuffed bit stream buffer. */
78 unsigned int byte_in_progress;
79 /*! \brief The current number of bits in byte_in_progress. */
80 int num_bits;
81
82 /*! \brief Buffer for a frame in progress. */
83 uint8_t buffer[HDLC_MAXFRAME_LEN + 4];
84 /*! \brief Length of a frame in progress. */
85 int len;
86
87 /*! \brief The number of bytes of good frames received (CRC not included). */
88 unsigned long int rx_bytes;
89 /*! \brief The number of good frames received. */
90 unsigned long int rx_frames;
91 /*! \brief The number of frames with CRC errors received. */
92 unsigned long int rx_crc_errors;
93 /*! \brief The number of too short and too long frames received. */
94 unsigned long int rx_length_errors;
95 /*! \brief The number of HDLC aborts received. */
96 unsigned long int rx_aborts;
97 } hdlc_rx_state_t;
98
99 /*!
100 HDLC received data statistics.
101 */
102 typedef struct
103 {
104 /*! \brief The number of bytes of good frames received (CRC not included). */
105 unsigned long int bytes;
106 /*! \brief The number of good frames received. */
107 unsigned long int good_frames;
108 /*! \brief The number of frames with CRC errors received. */
109 unsigned long int crc_errors;
110 /*! \brief The number of too short and too long frames received. */
111 unsigned long int length_errors;
112 /*! \brief The number of HDLC aborts received. */
113 unsigned long int aborts;
114 } hdlc_rx_stats_t;
115
116 /*!
117 HDLC transmit descriptor. This contains all the state information for an
118 HDLC transmitter.
119 */
120 typedef struct
121 {
122 /*! 2 for CRC-16, 4 for CRC-32 */
123 int crc_bytes;
124 /*! \brief The callback routine called to indicate transmit underflow. */
125 hdlc_underflow_handler_t underflow_handler;
126 /*! \brief An opaque parameter passed to the callback routine. */
127 void *user_data;
128 /*! \brief The minimum flag octets to insert between frames. */
129 int inter_frame_flags;
130 /*! \brief TRUE if frame creation works in progressive mode. */
131 int progressive;
132 /*! \brief Maximum permitted frame length. */
133 int max_frame_len;
134
135 /*! \brief The stuffed bit stream being created. */
136 uint32_t octets_in_progress;
137 /*! \brief The number of bits currently in octets_in_progress. */
138 int num_bits;
139 /*! \brief The currently rotated state of the flag octet. */
140 int idle_octet;
141 /*! \brief The number of flag octets to send for a timed burst of flags. */
142 int flag_octets;
143 /*! \brief TRUE if the next underflow of timed flag octets should be reported */
144 int report_flag_underflow;
145
146 /*! \brief The current message being transmitted, with its CRC attached. */
147 uint8_t buffer[HDLC_MAXFRAME_LEN + 4];
148 /*! \brief The length of the message in the buffer. */
149 int len;
150 /*! \brief The current send position within the buffer. */
151 int pos;
152 /*! \brief The running CRC, as data fills the frame buffer. */
153 uint32_t crc;
154
155 /*! \brief The current byte being broken into bits for transmission. */
156 int byte;
157 /*! \brief The number of bits remaining in byte. */
158 int bits;
159
160 /*! \brief TRUE if transmission should end on buffer underflow .*/
161 int tx_end;
162 } hdlc_tx_state_t;
163
164 #ifdef __cplusplus
165 extern "C" {
166 #endif
167
168 /*! \brief Calculate the ITU/CCITT CRC-32 value in buffer.
169 \param buf The buffer containing the data.
170 \param len The length of the frame.
171 \param crc The initial CRC value. This is usually 0xFFFFFFFF, or 0 for a new block (it depends on
172 the application). It is previous returned CRC value for the continuation of a block.
173 \return The CRC value.
174 */
175 uint32_t crc_itu32_calc(const uint8_t *buf, int len, uint32_t crc);
176
177 /*! \brief Append an ITU/CCITT CRC-32 value to a frame.
178 \param buf The buffer containing the frame. This must be at least 2 bytes longer than
179 the frame it contains, to allow room for the CRC value.
180 \param len The length of the frame.
181 \return The new length of the frame.
182 */
183 int crc_itu32_append(uint8_t *buf, int len);
184
185 /*! \brief Check the ITU/CCITT CRC-32 value in a frame.
186 \param buf The buffer containing the frame.
187 \param len The length of the frame.
188 \return TRUE if the CRC is OK, else FALSE.
189 */
190 int crc_itu32_check(const uint8_t *buf, int len);
191
192 /*! \brief Calculate the ITU/CCITT CRC-16 value in buffer.
193 \param buf The buffer containing the data.
194 \param len The length of the frame.
195 \param crc The initial CRC value. This is usually 0xFFFF, or 0 for a new block (it depends on
196 the application). It is previous returned CRC value for the continuation of a block.
197 \return The CRC value.
198 */
199 uint16_t crc_itu16_calc(const uint8_t *buf, int len, uint16_t crc);
200
201 /*! \brief Append an ITU/CCITT CRC-16 value to a frame.
202 \param buf The buffer containing the frame. This must be at least 2 bytes longer than
203 the frame it contains, to allow room for the CRC value.
204 \param len The length of the frame.
205 \return The new length of the frame.
206 */
207 int crc_itu16_append(uint8_t *buf, int len);
208
209 /*! \brief Check the ITU/CCITT CRC-16 value in a frame.
210 \param buf The buffer containing the frame.
211 \param len The length of the frame.
212 \return TRUE if the CRC is OK, else FALSE.
213 */
214 int crc_itu16_check(const uint8_t *buf, int len);
215
216 /*! \brief Initialise an HDLC receiver context.
217 \param s A pointer to an HDLC receiver context.
218 \param crc32 TRUE to use ITU CRC32. FALSE to use ITU CRC16.
219 \param report_bad_frames TRUE to request the reporting of bad frames.
220 \param framing_ok_threshold The number of back-to-back flags needed to
221 start the framing OK condition. This may be used where a series of
222 flag octets is used as a preamble, such as in the T.30 protocol.
223 \param handler The function to be called when a good HDLC frame is received.
224 \param user_data An opaque parameter for the callback routine.
225 \return A pointer to the HDLC receiver context.
226 */
227 hdlc_rx_state_t *hdlc_rx_init(hdlc_rx_state_t *s,
228 int crc32,
229 int report_bad_frames,
230 int framing_ok_threshold,
231 hdlc_frame_handler_t handler,
232 void *user_data);
233
234 /*! \brief Get the current receive statistics.
235 \param s A pointer to an HDLC receiver context.
236 \param t A pointer to the buffer for the statistics.
237 \return 0 for OK, else -1.
238 */
239 int hdlc_rx_get_stats(hdlc_rx_state_t *s,
240 hdlc_rx_stats_t *t);
241
242 /* Use either the bit-by-bit or byte-by-byte routines. Do not mix them is a
243 single instance of HDLC */
244 void hdlc_rx_put_bit(hdlc_rx_state_t *s, int new_bit);
245 void hdlc_rx_put_byte(hdlc_rx_state_t *s, int new_byte);
246
247 /*! \brief Initialise an HDLC transmitter context.
248 \param s A pointer to an HDLC transmitter context.
249 \param crc32 TRUE to use ITU CRC32. FALSE to use ITU CRC16.
250 \param inter_frame_flags The minimum flag octets to insert between frames (usually one).
251 \param progressive TRUE if frame creation works in progressive mode.
252 \param handler The callback function called when the HDLC transmitter underflows.
253 \param user_data An opaque parameter for the callback routine.
254 \return A pointer to the HDLC transmitter context.
255 */
256 hdlc_tx_state_t *hdlc_tx_init(hdlc_tx_state_t *s,
257 int crc32,
258 int inter_frame_flags,
259 int progressive,
260 hdlc_underflow_handler_t handler,
261 void *user_data);
262
263 /*! \brief Set the maximum frame length for an HDLC transmitter context.
264 \param s A pointer to an HDLC transmitter context.
265 \param max_len The maximum length.
266 */
267 void hdlc_tx_set_max_frame_len(hdlc_tx_state_t *s, int max_len);
268
269 /*! \brief Transmit a frame.
270 \param s A pointer to an HDLC transmitter context.
271 \param frame A pointer to the frame to be transmitted.
272 \param len The length of the frame to be transmitted.
273 \return 0 if the frame was accepted for transmission, else -1.
274 */
275 int hdlc_tx_frame(hdlc_tx_state_t *s, const uint8_t *frame, int len);
276
277 /*! \brief Corrupt the frame currently being transmitted, by giving it the wrong CRC.
278 \param s A pointer to an HDLC transmitter context.
279 \return 0 if the frame was corrupted, else -1.
280 */
281 int hdlc_tx_corrupt_frame(hdlc_tx_state_t *s);
282
283 /*! \brief Transmit a specified quantity of flag octets as a preamble.
284 \param s A pointer to an HDLC transmitter context.
285 \param len The length of the required preamble, in flag octets. If len is zero this
286 requests that HDLC transmission be terminated when the buffers have fully
287 drained.
288 \return 0 if the preamble was accepted for transmission, else -1.
289 */
290 int hdlc_tx_preamble(hdlc_tx_state_t *s, int len);
291
292 /*! \brief Get the next bit for transmission.
293 \param s A pointer to an HDLC transmitter context.
294 \return The next bit for transmission.
295 */
296 int hdlc_tx_get_bit(hdlc_tx_state_t *s);
297
298 /*! \brief Get the next byte for transmission.
299 \param s A pointer to an HDLC transmitter context.
300 \return The next byte for transmission.
301 */
302 int hdlc_tx_get_byte(hdlc_tx_state_t *s);
303
304 #ifdef __cplusplus
305 }
306 #endif
307
308 #endif
309 /*- End of file ------------------------------------------------------------*/

Repositories maintained by Peter Meerwald, pmeerw@pmeerw.net.