spandsp
0.0.6
|
00001 /* 00002 * SpanDSP - a series of DSP components for telephony 00003 * 00004 * hdlc.h 00005 * 00006 * Written by Steve Underwood <steveu@coppice.org> 00007 * 00008 * Copyright (C) 2003 Steve Underwood 00009 * 00010 * All rights reserved. 00011 * 00012 * This program is free software; you can redistribute it and/or modify 00013 * it under the terms of the GNU Lesser General Public License version 2.1, 00014 * as published by the Free Software Foundation. 00015 * 00016 * This program is distributed in the hope that it will be useful, 00017 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00018 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00019 * GNU Lesser General Public License for more details. 00020 * 00021 * You should have received a copy of the GNU Lesser General Public 00022 * License along with this program; if not, write to the Free Software 00023 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 00024 */ 00025 00026 /*! \file */ 00027 00028 /*! \page hdlc_page HDLC 00029 00030 \section hdlc_page_sec_1 What does it do? 00031 The HDLC module provides bit stuffing, destuffing, framing and deframing, 00032 according to the HDLC protocol. It also provides 16 and 32 bit CRC generation 00033 and checking services for HDLC frames. 00034 00035 HDLC may not be a DSP function, but is needed to accompany several DSP components. 00036 00037 \section hdlc_page_sec_2 How does it work? 00038 */ 00039 00040 #if !defined(_SPANDSP_HDLC_H_) 00041 #define _SPANDSP_HDLC_H_ 00042 00043 /*! 00044 HDLC_MAXFRAME_LEN is the maximum length of a stuffed HDLC frame, excluding the CRC. 00045 */ 00046 #define HDLC_MAXFRAME_LEN 400 00047 00048 typedef void (*hdlc_frame_handler_t)(void *user_data, const uint8_t *pkt, int len, int ok); 00049 typedef void (*hdlc_underflow_handler_t)(void *user_data); 00050 00051 /*! 00052 HDLC receive descriptor. This contains all the state information for an HDLC receiver. 00053 */ 00054 typedef struct hdlc_rx_state_s hdlc_rx_state_t; 00055 00056 /*! 00057 HDLC received data statistics. 00058 */ 00059 typedef struct 00060 { 00061 /*! \brief The number of bytes of good frames received (CRC not included). */ 00062 unsigned long int bytes; 00063 /*! \brief The number of good frames received. */ 00064 unsigned long int good_frames; 00065 /*! \brief The number of frames with CRC errors received. */ 00066 unsigned long int crc_errors; 00067 /*! \brief The number of too short and too long frames received. */ 00068 unsigned long int length_errors; 00069 /*! \brief The number of HDLC aborts received. */ 00070 unsigned long int aborts; 00071 } hdlc_rx_stats_t; 00072 00073 /*! 00074 HDLC transmit descriptor. This contains all the state information for an 00075 HDLC transmitter. 00076 */ 00077 typedef struct hdlc_tx_state_s hdlc_tx_state_t; 00078 00079 #if defined(__cplusplus) 00080 extern "C" 00081 { 00082 #endif 00083 00084 /*! \brief Initialise an HDLC receiver context. 00085 \param s A pointer to an HDLC receiver context. 00086 \param crc32 TRUE to use ITU CRC32. FALSE to use ITU CRC16. 00087 \param report_bad_frames TRUE to request the reporting of bad frames. 00088 \param framing_ok_threshold The number of back-to-back flags needed to 00089 start the framing OK condition. This may be used where a series of 00090 flag octets is used as a preamble, such as in the T.30 protocol. 00091 \param handler The function to be called when a good HDLC frame is received. 00092 \param user_data An opaque parameter for the callback routine. 00093 \return A pointer to the HDLC receiver context. 00094 */ 00095 SPAN_DECLARE(hdlc_rx_state_t *) hdlc_rx_init(hdlc_rx_state_t *s, 00096 int crc32, 00097 int report_bad_frames, 00098 int framing_ok_threshold, 00099 hdlc_frame_handler_t handler, 00100 void *user_data); 00101 00102 /*! Change the put_bit function associated with an HDLC receiver context. 00103 \brief Change the put_bit function associated with an HDLC receiver context. 00104 \param s A pointer to an HDLC receiver context. 00105 \param handler The function to be called when a good HDLC frame is received. 00106 \param user_data An opaque parameter for the callback routine. 00107 */ 00108 SPAN_DECLARE(void) hdlc_rx_set_frame_handler(hdlc_rx_state_t *s, hdlc_frame_handler_t handler, void *user_data); 00109 00110 /*! Change the status report function associated with an HDLC receiver context. 00111 \brief Change the status report function associated with an HDLC receiver context. 00112 \param s A pointer to an HDLC receiver context. 00113 \param handler The callback routine used to report status changes. 00114 \param user_data An opaque parameter for the callback routine. 00115 */ 00116 SPAN_DECLARE(void) hdlc_rx_set_status_handler(hdlc_rx_state_t *s, modem_rx_status_func_t handler, void *user_data); 00117 00118 /*! Release an HDLC receiver context. 00119 \brief Release an HDLC receiver context. 00120 \param s A pointer to an HDLC receiver context. 00121 \return 0 for OK */ 00122 SPAN_DECLARE(int) hdlc_rx_release(hdlc_rx_state_t *s); 00123 00124 /*! Free an HDLC receiver context. 00125 \brief Free an HDLC receiver context. 00126 \param s A pointer to an HDLC receiver context. 00127 \return 0 for OK */ 00128 SPAN_DECLARE(int) hdlc_rx_free(hdlc_rx_state_t *s); 00129 00130 /*! \brief Set the maximum frame length for an HDLC receiver context. 00131 \param s A pointer to an HDLC receiver context. 00132 \param max_len The maximum permitted length of a frame. 00133 */ 00134 SPAN_DECLARE(void) hdlc_rx_set_max_frame_len(hdlc_rx_state_t *s, size_t max_len); 00135 00136 /*! \brief Set the octet counting report interval. 00137 \param s A pointer to an HDLC receiver context. 00138 \param interval The interval, in octets. 00139 */ 00140 SPAN_DECLARE(void) hdlc_rx_set_octet_counting_report_interval(hdlc_rx_state_t *s, 00141 int interval); 00142 00143 /*! \brief Get the current receive statistics. 00144 \param s A pointer to an HDLC receiver context. 00145 \param t A pointer to the buffer for the statistics. 00146 \return 0 for OK, else -1. 00147 */ 00148 SPAN_DECLARE(int) hdlc_rx_get_stats(hdlc_rx_state_t *s, 00149 hdlc_rx_stats_t *t); 00150 00151 /*! \brief Put a single bit of data to an HDLC receiver. 00152 \param s A pointer to an HDLC receiver context. 00153 \param new_bit The bit. 00154 */ 00155 SPAN_DECLARE_NONSTD(void) hdlc_rx_put_bit(hdlc_rx_state_t *s, int new_bit); 00156 00157 /*! \brief Put a byte of data to an HDLC receiver. 00158 \param s A pointer to an HDLC receiver context. 00159 \param new_byte The byte of data. 00160 */ 00161 SPAN_DECLARE_NONSTD(void) hdlc_rx_put_byte(hdlc_rx_state_t *s, int new_byte); 00162 00163 /*! \brief Put a series of bytes of data to an HDLC receiver. 00164 \param s A pointer to an HDLC receiver context. 00165 \param buf The buffer of data. 00166 \param len The length of the data in the buffer. 00167 */ 00168 SPAN_DECLARE_NONSTD(void) hdlc_rx_put(hdlc_rx_state_t *s, const uint8_t buf[], int len); 00169 00170 /*! \brief Initialise an HDLC transmitter context. 00171 \param s A pointer to an HDLC transmitter context. 00172 \param crc32 TRUE to use ITU CRC32. FALSE to use ITU CRC16. 00173 \param inter_frame_flags The minimum flag octets to insert between frames (usually one). 00174 \param progressive TRUE if frame creation works in progressive mode. 00175 \param handler The callback function called when the HDLC transmitter underflows. 00176 \param user_data An opaque parameter for the callback routine. 00177 \return A pointer to the HDLC transmitter context. 00178 */ 00179 SPAN_DECLARE(hdlc_tx_state_t *) hdlc_tx_init(hdlc_tx_state_t *s, 00180 int crc32, 00181 int inter_frame_flags, 00182 int progressive, 00183 hdlc_underflow_handler_t handler, 00184 void *user_data); 00185 00186 SPAN_DECLARE(int) hdlc_tx_release(hdlc_tx_state_t *s); 00187 00188 SPAN_DECLARE(int) hdlc_tx_free(hdlc_tx_state_t *s); 00189 00190 /*! \brief Set the maximum frame length for an HDLC transmitter context. 00191 \param s A pointer to an HDLC transmitter context. 00192 \param max_len The maximum length. 00193 */ 00194 SPAN_DECLARE(void) hdlc_tx_set_max_frame_len(hdlc_tx_state_t *s, size_t max_len); 00195 00196 /*! \brief Transmit a frame. 00197 \param s A pointer to an HDLC transmitter context. 00198 \param frame A pointer to the frame to be transmitted. 00199 \param len The length of the frame to be transmitted. 00200 \return 0 if the frame was accepted for transmission, else -1. 00201 */ 00202 SPAN_DECLARE(int) hdlc_tx_frame(hdlc_tx_state_t *s, const uint8_t *frame, size_t len); 00203 00204 /*! \brief Corrupt the frame currently being transmitted, by giving it the wrong CRC. 00205 \param s A pointer to an HDLC transmitter context. 00206 \return 0 if the frame was corrupted, else -1. 00207 */ 00208 SPAN_DECLARE(int) hdlc_tx_corrupt_frame(hdlc_tx_state_t *s); 00209 00210 /*! \brief Transmit a specified quantity of flag octets, typically as a preamble. 00211 \param s A pointer to an HDLC transmitter context. 00212 \param len The length of the required period of flags, in flag octets. If len is zero this 00213 requests that HDLC transmission be terminated when the buffers have fully 00214 drained. 00215 \return 0 if the flags were accepted for transmission, else -1. 00216 */ 00217 SPAN_DECLARE(int) hdlc_tx_flags(hdlc_tx_state_t *s, int len); 00218 00219 /*! \brief Send an abort. 00220 \param s A pointer to an HDLC transmitter context. 00221 \return 0 if the frame was aborted, else -1. 00222 */ 00223 SPAN_DECLARE(int) hdlc_tx_abort(hdlc_tx_state_t *s); 00224 00225 /*! \brief Get the next bit for transmission. 00226 \param s A pointer to an HDLC transmitter context. 00227 \return The next bit for transmission. 00228 */ 00229 SPAN_DECLARE_NONSTD(int) hdlc_tx_get_bit(hdlc_tx_state_t *s); 00230 00231 /*! \brief Get the next byte for transmission. 00232 \param s A pointer to an HDLC transmitter context. 00233 \return The next byte for transmission. 00234 */ 00235 SPAN_DECLARE_NONSTD(int) hdlc_tx_get_byte(hdlc_tx_state_t *s); 00236 00237 /*! \brief Get the next sequence of bytes for transmission. 00238 \param s A pointer to an HDLC transmitter context. 00239 \param buf The buffer for the data. 00240 \param max_len The number of bytes to get. 00241 \return The number of bytes actually got. 00242 */ 00243 SPAN_DECLARE_NONSTD(int) hdlc_tx_get(hdlc_tx_state_t *s, uint8_t buf[], size_t max_len); 00244 00245 #if defined(__cplusplus) 00246 } 00247 #endif 00248 00249 #endif 00250 /*- End of file ------------------------------------------------------------*/