|
5
|
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 ------------------------------------------------------------*/
|
