spandsp 0.0.6

hdlc.h
Go to the documentation of this file.
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
26/*! \file */
27
28/*! \page hdlc_page HDLC
29
30\section hdlc_page_sec_1 What does it do?
31 The HDLC module provides bit stuffing, destuffing, framing and deframing,
32 according to the HDLC protocol. It also provides 16 and 32 bit CRC generation
33 and checking services for HDLC frames.
34
35 HDLC may not be a DSP function, but is needed to accompany several DSP components.
36
37\section hdlc_page_sec_2 How does it work?
38*/
39
40#if !defined(_SPANDSP_HDLC_H_)
41#define _SPANDSP_HDLC_H_
42
43/*!
44 HDLC_MAXFRAME_LEN is the maximum length of a stuffed HDLC frame, excluding the CRC.
45*/
46#define HDLC_MAXFRAME_LEN 400
47
48 typedef void (*hdlc_frame_handler_t)(void *user_data, const uint8_t *pkt, int len, int ok);
49 typedef void (*hdlc_underflow_handler_t)(void *user_data);
50
51/*!
52 HDLC receive descriptor. This contains all the state information for an HDLC receiver.
53 */
54 typedef struct hdlc_rx_state_s hdlc_rx_state_t;
55
56/*!
57 HDLC received data statistics.
58 */
59 typedef struct
60{
61 /*! \brief The number of bytes of good frames received (CRC not included). */
62 unsigned long int bytes;
63 /*! \brief The number of good frames received. */
64 unsigned long int good_frames;
65 /*! \brief The number of frames with CRC errors received. */
66 unsigned long int crc_errors;
67 /*! \brief The number of too short and too long frames received. */
68 unsigned long int length_errors;
69 /*! \brief The number of HDLC aborts received. */
70 unsigned long int aborts;
71} hdlc_rx_stats_t;
72
73/*!
74 HDLC transmit descriptor. This contains all the state information for an
75 HDLC transmitter.
76 */
77 typedef struct hdlc_tx_state_s hdlc_tx_state_t;
78
79#if defined(__cplusplus)
80 extern "C"
81{
82#endif
83
84/*! Initialise an HDLC receiver context.
85 \brief Initialise an HDLC receiver context.
86 \param s A pointer to an HDLC receiver context.
87 \param crc32 TRUE to use ITU CRC32. FALSE to use ITU CRC16.
88 \param report_bad_frames TRUE to request the reporting of bad frames.
89 \param framing_ok_threshold The number of back-to-back flags needed to
90 start the framing OK condition. This may be used where a series of
91 flag octets is used as a preamble, such as in the T.30 protocol.
92 \param handler The function to be called when a good HDLC frame is received.
93 \param user_data An opaque parameter for the callback routine.
94 \return A pointer to the HDLC receiver context.
95*/
96SPAN_DECLARE(hdlc_rx_state_t *) hdlc_rx_init(hdlc_rx_state_t *s,
97 int crc32,
98 int report_bad_frames,
99 int framing_ok_threshold,
100 hdlc_frame_handler_t handler,
101 void *user_data);
102
103/*! Re-initialise an HDLC receiver context. This does not reset the usage statistics.
104 \brief Re-initialise an HDLC receiver context.
105 \param s A pointer to an HDLC receiver context.
106 \return 0 for success.
107*/
108SPAN_DECLARE(int) hdlc_rx_restart(hdlc_rx_state_t *s);
109
110/*! Change the put_bit function associated with an HDLC receiver context.
111 \brief Change the put_bit function associated with an HDLC receiver context.
112 \param s A pointer to an HDLC receiver context.
113 \param handler The function to be called when a good HDLC frame is received.
114 \param user_data An opaque parameter for the callback routine.
115*/
116SPAN_DECLARE(void) hdlc_rx_set_frame_handler(hdlc_rx_state_t *s, hdlc_frame_handler_t handler, void *user_data);
117
118/*! Change the status report function associated with an HDLC receiver context.
119 \brief Change the status report function associated with an HDLC receiver context.
120 \param s A pointer to an HDLC receiver context.
121 \param handler The callback routine used to report status changes.
122 \param user_data An opaque parameter for the callback routine.
123*/
124SPAN_DECLARE(void) hdlc_rx_set_status_handler(hdlc_rx_state_t *s, modem_status_func_t handler, void *user_data);
125
126/*! Release an HDLC receiver context.
127 \brief Release an HDLC receiver context.
128 \param s A pointer to an HDLC receiver context.
129 \return 0 for OK */
130SPAN_DECLARE(int) hdlc_rx_release(hdlc_rx_state_t *s);
131
132/*! Free an HDLC receiver context.
133 \brief Free an HDLC receiver context.
134 \param s A pointer to an HDLC receiver context.
135 \return 0 for OK */
136SPAN_DECLARE(int) hdlc_rx_free(hdlc_rx_state_t *s);
137
138/*! \brief Set the maximum frame length for an HDLC receiver context.
139 \param s A pointer to an HDLC receiver context.
140 \param max_len The maximum permitted length of a frame.
141*/
142SPAN_DECLARE(void) hdlc_rx_set_max_frame_len(hdlc_rx_state_t *s, size_t max_len);
143
144/*! \brief Set the octet counting report interval.
145 \param s A pointer to an HDLC receiver context.
146 \param interval The interval, in octets.
147*/
148SPAN_DECLARE(void) hdlc_rx_set_octet_counting_report_interval(hdlc_rx_state_t *s,
149 int interval);
150
151/*! \brief Get the current receive statistics.
152 \param s A pointer to an HDLC receiver context.
153 \param t A pointer to the buffer for the statistics.
154 \return 0 for OK, else -1.
155*/
156SPAN_DECLARE(int) hdlc_rx_get_stats(hdlc_rx_state_t *s,
157 hdlc_rx_stats_t *t);
158
159/*! \brief Put a single bit of data to an HDLC receiver.
160 \param s A pointer to an HDLC receiver context.
161 \param new_bit The bit.
162*/
163 SPAN_DECLARE_NONSTD(void) hdlc_rx_put_bit(hdlc_rx_state_t *s, int new_bit);
164
165/*! \brief Put a byte of data to an HDLC receiver.
166 \param s A pointer to an HDLC receiver context.
167 \param new_byte The byte of data.
168*/
169 SPAN_DECLARE_NONSTD(void) hdlc_rx_put_byte(hdlc_rx_state_t *s, int new_byte);
170
171/*! \brief Put a series of bytes of data to an HDLC receiver.
172 \param s A pointer to an HDLC receiver context.
173 \param buf The buffer of data.
174 \param len The length of the data in the buffer.
175*/
176 SPAN_DECLARE_NONSTD(void) hdlc_rx_put(hdlc_rx_state_t *s, const uint8_t buf[], int len);
177
178/*! Initialise an HDLC transmitter context.
179 \brief Initialise an HDLC transmitter context.
180 \param s A pointer to an HDLC transmitter context.
181 \param crc32 TRUE to use ITU CRC32. FALSE to use ITU CRC16.
182 \param inter_frame_flags The minimum flag octets to insert between frames (usually one).
183 \param progressive TRUE if frame creation works in progressive mode.
184 \param handler The callback function called when the HDLC transmitter underflows.
185 \param user_data An opaque parameter for the callback routine.
186 \return A pointer to the HDLC transmitter context.
187*/
188SPAN_DECLARE(hdlc_tx_state_t *) hdlc_tx_init(hdlc_tx_state_t *s,
189 int crc32,
190 int inter_frame_flags,
191 int progressive,
192 hdlc_underflow_handler_t handler,
193 void *user_data);
194
195/*! Re-initialise an HDLC transmitter context.
196 \brief Re-initialise an HDLC transmitter context.
197 \param s A pointer to an HDLC transmitter context.
198 \return 0 for success.
199*/
200SPAN_DECLARE(int) hdlc_tx_restart(hdlc_tx_state_t *s);
201
202/*! Release an HDLC transmitter context.
203 \brief Release an HDLC transmitter context.
204 \param s A pointer to an HDLC transmitter context.
205 \return 0 for OK */
206SPAN_DECLARE(int) hdlc_tx_release(hdlc_tx_state_t *s);
207
208/*! Free an HDLC transmitter context.
209 \brief Free an HDLC transmitter context.
210 \param s A pointer to an HDLC transmitter context.
211 \return 0 for OK */
212SPAN_DECLARE(int) hdlc_tx_free(hdlc_tx_state_t *s);
213
214/*! \brief Set the maximum frame length for an HDLC transmitter context.
215 \param s A pointer to an HDLC transmitter context.
216 \param max_len The maximum length.
217*/
218SPAN_DECLARE(void) hdlc_tx_set_max_frame_len(hdlc_tx_state_t *s, size_t max_len);
219
220/*! \brief Transmit a frame.
221 \param s A pointer to an HDLC transmitter context.
222 \param frame A pointer to the frame to be transmitted.
223 \param len The length of the frame to be transmitted.
224 \return 0 if the frame was accepted for transmission, else -1.
225*/
226SPAN_DECLARE(int) hdlc_tx_frame(hdlc_tx_state_t *s, const uint8_t *frame, size_t len);
227
228/*! \brief Corrupt the frame currently being transmitted, by giving it the wrong CRC.
229 \param s A pointer to an HDLC transmitter context.
230 \return 0 if the frame was corrupted, else -1.
231*/
232SPAN_DECLARE(int) hdlc_tx_corrupt_frame(hdlc_tx_state_t *s);
233
234/*! \brief Transmit a specified quantity of flag octets, typically as a preamble.
235 \param s A pointer to an HDLC transmitter context.
236 \param len The length of the required period of flags, in flag octets. If len is zero this
237 requests that HDLC transmission be terminated when the buffers have fully
238 drained.
239 \return 0 if the flags were accepted for transmission, else -1.
240*/
241SPAN_DECLARE(int) hdlc_tx_flags(hdlc_tx_state_t *s, int len);
242
243/*! \brief Send an abort.
244 \param s A pointer to an HDLC transmitter context.
245 \return 0 if the frame was aborted, else -1.
246*/
247SPAN_DECLARE(int) hdlc_tx_abort(hdlc_tx_state_t *s);
248
249/*! \brief Get the next bit for transmission.
250 \param s A pointer to an HDLC transmitter context.
251 \return The next bit for transmission.
252*/
253 SPAN_DECLARE_NONSTD(int) hdlc_tx_get_bit(hdlc_tx_state_t *s);
254
255/*! \brief Get the next byte for transmission.
256 \param s A pointer to an HDLC transmitter context.
257 \return The next byte for transmission.
258*/
259 SPAN_DECLARE_NONSTD(int) hdlc_tx_get_byte(hdlc_tx_state_t *s);
260
261/*! \brief Get the next sequence of bytes for transmission.
262 \param s A pointer to an HDLC transmitter context.
263 \param buf The buffer for the data.
264 \param max_len The number of bytes to get.
265 \return The number of bytes actually got.
266*/
267 SPAN_DECLARE_NONSTD(int) hdlc_tx_get(hdlc_tx_state_t *s, uint8_t buf[], size_t max_len);
268
269#if defined(__cplusplus)
270}
271#endif
272
273#endif
274/*- End of file ------------------------------------------------------------*/
modem_status_func_t
void(* modem_status_func_t)(void *user_data, int status)
Definition async.h:114
hdlc_rx_set_frame_handler
void hdlc_rx_set_frame_handler(hdlc_rx_state_t *s, hdlc_frame_handler_t handler, void *user_data)
Change the put_bit function associated with an HDLC receiver context.
Definition hdlc.c:350
hdlc_tx_set_max_frame_len
void hdlc_tx_set_max_frame_len(hdlc_tx_state_t *s, size_t max_len)
Set the maximum frame length for an HDLC transmitter context.
Definition hdlc.c:599
hdlc_tx_free
int hdlc_tx_free(hdlc_tx_state_t *s)
Free an HDLC transmitter context.
Definition hdlc.c:665
hdlc_rx_set_status_handler
void hdlc_rx_set_status_handler(hdlc_rx_state_t *s, modem_status_func_t handler, void *user_data)
Change the status report function associated with an HDLC receiver context.
Definition hdlc.c:357
hdlc_rx_state_t
struct hdlc_rx_state_s hdlc_rx_state_t
Definition hdlc.h:54
hdlc_tx_restart
int hdlc_tx_restart(hdlc_tx_state_t *s)
Re-initialise an HDLC transmitter context.
Definition hdlc.c:605
hdlc_rx_init
hdlc_rx_state_t * hdlc_rx_init(hdlc_rx_state_t *s, int crc32, int report_bad_frames, int framing_ok_threshold, hdlc_frame_handler_t handler, void *user_data)
Initialise an HDLC receiver context.
Definition hdlc.c:327
hdlc_tx_frame
int hdlc_tx_frame(hdlc_tx_state_t *s, const uint8_t *frame, size_t len)
Transmit a frame.
Definition hdlc.c:389
hdlc_tx_release
int hdlc_tx_release(hdlc_tx_state_t *s)
Release an HDLC transmitter context.
Definition hdlc.c:659
hdlc_rx_restart
int hdlc_rx_restart(hdlc_rx_state_t *s)
Re-initialise an HDLC receiver context.
Definition hdlc.c:313
hdlc_rx_set_max_frame_len
void hdlc_rx_set_max_frame_len(hdlc_rx_state_t *s, size_t max_len)
Set the maximum frame length for an HDLC receiver context.
Definition hdlc.c:300
hdlc_tx_flags
int hdlc_tx_flags(hdlc_tx_state_t *s, int len)
Transmit a specified quantity of flag octets, typically as a preamble.
Definition hdlc.c:424
hdlc_tx_state_t
struct hdlc_tx_state_s hdlc_tx_state_t
Definition hdlc.h:77
SPAN_DECLARE_NONSTD
SPAN_DECLARE_NONSTD(void) hdlc_rx_put_bit(hdlc_rx_state_t *s
Put a single bit of data to an HDLC receiver.
hdlc_rx_release
int hdlc_rx_release(hdlc_rx_state_t *s)
Release an HDLC receiver context.
Definition hdlc.c:364
hdlc_rx_get_stats
int hdlc_rx_get_stats(hdlc_rx_state_t *s, hdlc_rx_stats_t *t)
Get the current receive statistics.
Definition hdlc.c:377
hdlc_tx_abort
int hdlc_tx_abort(hdlc_tx_state_t *s)
Send an abort.
Definition hdlc.c:440
hdlc_tx_corrupt_frame
int hdlc_tx_corrupt_frame(hdlc_tx_state_t *s)
Corrupt the frame currently being transmitted, by giving it the wrong CRC.
Definition hdlc.c:450
hdlc_rx_set_octet_counting_report_interval
void hdlc_rx_set_octet_counting_report_interval(hdlc_rx_state_t *s, int interval)
Set the octet counting report interval.
Definition hdlc.c:307
hdlc_tx_init
hdlc_tx_state_t * hdlc_tx_init(hdlc_tx_state_t *s, int crc32, int inter_frame_flags, int progressive, hdlc_underflow_handler_t handler, void *user_data)
Initialise an HDLC transmitter context.
Definition hdlc.c:626
hdlc_rx_free
int hdlc_rx_free(hdlc_rx_state_t *s)
Free an HDLC receiver context.
Definition hdlc.c:370
hdlc_rx_state_s
Definition private/hdlc.h:33
hdlc_rx_stats_t
Definition hdlc.h:60
hdlc_rx_stats_t::length_errors
unsigned long int length_errors
The number of too short and too long frames received.
Definition hdlc.h:68
hdlc_rx_stats_t::aborts
unsigned long int aborts
The number of HDLC aborts received.
Definition hdlc.h:70
hdlc_rx_stats_t::crc_errors
unsigned long int crc_errors
The number of frames with CRC errors received.
Definition hdlc.h:66
hdlc_rx_stats_t::good_frames
unsigned long int good_frames
The number of good frames received.
Definition hdlc.h:64
hdlc_rx_stats_t::bytes
unsigned long int bytes
The number of bytes of good frames received (CRC not included).
Definition hdlc.h:62
hdlc_tx_state_s
Definition private/hdlc.h:92
hdlc_tx_state_s::inter_frame_flags
int inter_frame_flags
The minimum flag octets to insert between frames.
Definition private/hdlc.h:100
hdlc_tx_state_s::progressive
int progressive
TRUE if frame creation works in progressive mode.
Definition private/hdlc.h:102
hdlc_tx_state_s::user_data
void * user_data
An opaque parameter passed to the callback routine.
Definition private/hdlc.h:98