Mercurial > hg > audiostuff

comparison spandsp-0.0.6pre17/src/spandsp/hdlc.h @ 4:26cd8f1ef0b1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
import spandsp-0.0.6pre17
author Peter Meerwald <pmeerw@cosy.sbg.ac.at>
date Fri, 25 Jun 2010 15:50:58 +0200
parents
children
comparison
equal deleted inserted replaced
3:c6c5a16ce2f2 4:26cd8f1ef0b1
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 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 * $Id: hdlc.h,v 1.45 2009/06/02 16:03:56 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 #if !defined(_SPANDSP_HDLC_H_)
43 #define _SPANDSP_HDLC_H_
44
45 /*!
46 HDLC_MAXFRAME_LEN is the maximum length of a stuffed HDLC frame, excluding the CRC.
47 */
48 #define HDLC_MAXFRAME_LEN 400
49
50 typedef void (*hdlc_frame_handler_t)(void *user_data, const uint8_t *pkt, int len, int ok);
51 typedef void (*hdlc_underflow_handler_t)(void *user_data);
52
53 /*!
54 HDLC receive descriptor. This contains all the state information for an HDLC receiver.
55 */
56 typedef struct hdlc_rx_state_s hdlc_rx_state_t;
57
58 /*!
59 HDLC received data statistics.
60 */
61 typedef struct
62 {
63 /*! \brief The number of bytes of good frames received (CRC not included). */
64 unsigned long int bytes;
65 /*! \brief The number of good frames received. */
66 unsigned long int good_frames;
67 /*! \brief The number of frames with CRC errors received. */
68 unsigned long int crc_errors;
69 /*! \brief The number of too short and too long frames received. */
70 unsigned long int length_errors;
71 /*! \brief The number of HDLC aborts received. */
72 unsigned long int aborts;
73 } hdlc_rx_stats_t;
74
75 /*!
76 HDLC transmit descriptor. This contains all the state information for an
77 HDLC transmitter.
78 */
79 typedef struct hdlc_tx_state_s hdlc_tx_state_t;
80
81 #if defined(__cplusplus)
82 extern "C"
83 {
84 #endif
85
86 /*! \brief Initialise an HDLC receiver context.
87 \param s A pointer to an HDLC receiver context.
88 \param crc32 TRUE to use ITU CRC32. FALSE to use ITU CRC16.
89 \param report_bad_frames TRUE to request the reporting of bad frames.
90 \param framing_ok_threshold The number of back-to-back flags needed to
91 start the framing OK condition. This may be used where a series of
92 flag octets is used as a preamble, such as in the T.30 protocol.
93 \param handler The function to be called when a good HDLC frame is received.
94 \param user_data An opaque parameter for the callback routine.
95 \return A pointer to the HDLC receiver context.
96 */
97 SPAN_DECLARE(hdlc_rx_state_t *) hdlc_rx_init(hdlc_rx_state_t *s,
98 int crc32,
99 int report_bad_frames,
100 int framing_ok_threshold,
101 hdlc_frame_handler_t handler,
102 void *user_data);
103
104 /*! Change the put_bit function associated with an HDLC receiver context.
105 \brief Change the put_bit function associated with an HDLC receiver context.
106 \param s A pointer to an HDLC receiver context.
107 \param handler The function to be called when a good HDLC frame is received.
108 \param user_data An opaque parameter for the callback routine.
109 */
110 SPAN_DECLARE(void) hdlc_rx_set_frame_handler(hdlc_rx_state_t *s, hdlc_frame_handler_t handler, void *user_data);
111
112 /*! Change the status report function associated with an HDLC receiver context.
113 \brief Change the status report function associated with an HDLC receiver context.
114 \param s A pointer to an HDLC receiver context.
115 \param handler The callback routine used to report status changes.
116 \param user_data An opaque parameter for the callback routine.
117 */
118 SPAN_DECLARE(void) hdlc_rx_set_status_handler(hdlc_rx_state_t *s, modem_rx_status_func_t handler, void *user_data);
119
120 /*! Release an HDLC receiver context.
121 \brief Release an HDLC receiver context.
122 \param s A pointer to an HDLC receiver context.
123 \return 0 for OK */
124 SPAN_DECLARE(int) hdlc_rx_release(hdlc_rx_state_t *s);
125
126 /*! Free an HDLC receiver context.
127 \brief Free an HDLC receiver context.
128 \param s A pointer to an HDLC receiver context.
129 \return 0 for OK */
130 SPAN_DECLARE(int) hdlc_rx_free(hdlc_rx_state_t *s);
131
132 /*! \brief Set the maximum frame length for an HDLC receiver context.
133 \param s A pointer to an HDLC receiver context.
134 \param max_len The maximum permitted length of a frame.
135 */
136 SPAN_DECLARE(void) hdlc_rx_set_max_frame_len(hdlc_rx_state_t *s, size_t max_len);
137
138 /*! \brief Set the octet counting report interval.
139 \param s A pointer to an HDLC receiver context.
140 \param interval The interval, in octets.
141 */
142 SPAN_DECLARE(void) hdlc_rx_set_octet_counting_report_interval(hdlc_rx_state_t *s,
143 int interval);
144
145 /*! \brief Get the current receive statistics.
146 \param s A pointer to an HDLC receiver context.
147 \param t A pointer to the buffer for the statistics.
148 \return 0 for OK, else -1.
149 */
150 SPAN_DECLARE(int) hdlc_rx_get_stats(hdlc_rx_state_t *s,
151 hdlc_rx_stats_t *t);
152
153 /*! \brief Put a single bit of data to an HDLC receiver.
154 \param s A pointer to an HDLC receiver context.
155 \param new_bit The bit.
156 */
157 SPAN_DECLARE_NONSTD(void) hdlc_rx_put_bit(hdlc_rx_state_t *s, int new_bit);
158
159 /*! \brief Put a byte of data to an HDLC receiver.
160 \param s A pointer to an HDLC receiver context.
161 \param new_byte The byte of data.
162 */
163 SPAN_DECLARE_NONSTD(void) hdlc_rx_put_byte(hdlc_rx_state_t *s, int new_byte);
164
165 /*! \brief Put a series of bytes of data to an HDLC receiver.
166 \param s A pointer to an HDLC receiver context.
167 \param buf The buffer of data.
168 \param len The length of the data in the buffer.
169 */
170 SPAN_DECLARE_NONSTD(void) hdlc_rx_put(hdlc_rx_state_t *s, const uint8_t buf[], int len);
171
172 /*! \brief Initialise an HDLC transmitter context.
173 \param s A pointer to an HDLC transmitter context.
174 \param crc32 TRUE to use ITU CRC32. FALSE to use ITU CRC16.
175 \param inter_frame_flags The minimum flag octets to insert between frames (usually one).
176 \param progressive TRUE if frame creation works in progressive mode.
177 \param handler The callback function called when the HDLC transmitter underflows.
178 \param user_data An opaque parameter for the callback routine.
179 \return A pointer to the HDLC transmitter context.
180 */
181 SPAN_DECLARE(hdlc_tx_state_t *) hdlc_tx_init(hdlc_tx_state_t *s,
182 int crc32,
183 int inter_frame_flags,
184 int progressive,
185 hdlc_underflow_handler_t handler,
186 void *user_data);
187
188 SPAN_DECLARE(int) hdlc_tx_release(hdlc_tx_state_t *s);
189
190 SPAN_DECLARE(int) hdlc_tx_free(hdlc_tx_state_t *s);
191
192 /*! \brief Set the maximum frame length for an HDLC transmitter context.
193 \param s A pointer to an HDLC transmitter context.
194 \param max_len The maximum length.
195 */
196 SPAN_DECLARE(void) hdlc_tx_set_max_frame_len(hdlc_tx_state_t *s, size_t max_len);
197
198 /*! \brief Transmit a frame.
199 \param s A pointer to an HDLC transmitter context.
200 \param frame A pointer to the frame to be transmitted.
201 \param len The length of the frame to be transmitted.
202 \return 0 if the frame was accepted for transmission, else -1.
203 */
204 SPAN_DECLARE(int) hdlc_tx_frame(hdlc_tx_state_t *s, const uint8_t *frame, size_t len);
205
206 /*! \brief Corrupt the frame currently being transmitted, by giving it the wrong CRC.
207 \param s A pointer to an HDLC transmitter context.
208 \return 0 if the frame was corrupted, else -1.
209 */
210 SPAN_DECLARE(int) hdlc_tx_corrupt_frame(hdlc_tx_state_t *s);
211
212 /*! \brief Transmit a specified quantity of flag octets, typically as a preamble.
213 \param s A pointer to an HDLC transmitter context.
214 \param len The length of the required period of flags, in flag octets. If len is zero this
215 requests that HDLC transmission be terminated when the buffers have fully
216 drained.
217 \return 0 if the flags were accepted for transmission, else -1.
218 */
219 SPAN_DECLARE(int) hdlc_tx_flags(hdlc_tx_state_t *s, int len);
220
221 /*! \brief Send an abort.
222 \param s A pointer to an HDLC transmitter context.
223 \return 0 if the frame was aborted, else -1.
224 */
225 SPAN_DECLARE(int) hdlc_tx_abort(hdlc_tx_state_t *s);
226
227 /*! \brief Get the next bit for transmission.
228 \param s A pointer to an HDLC transmitter context.
229 \return The next bit for transmission.
230 */
231 SPAN_DECLARE_NONSTD(int) hdlc_tx_get_bit(hdlc_tx_state_t *s);
232
233 /*! \brief Get the next byte for transmission.
234 \param s A pointer to an HDLC transmitter context.
235 \return The next byte for transmission.
236 */
237 SPAN_DECLARE_NONSTD(int) hdlc_tx_get_byte(hdlc_tx_state_t *s);
238
239 /*! \brief Get the next sequence of bytes for transmission.
240 \param s A pointer to an HDLC transmitter context.
241 \param buf The buffer for the data.
242 \param max_len The number of bytes to get.
243 \return The number of bytes actually got.
244 */
245 SPAN_DECLARE_NONSTD(int) hdlc_tx_get(hdlc_tx_state_t *s, uint8_t buf[], size_t max_len);
246
247 #if defined(__cplusplus)
248 }
249 #endif
250
251 #endif
252 /*- End of file ------------------------------------------------------------*/

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