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 General Public License as published by 00014 * the Free Software Foundation; either version 2 of the License, or 00015 * (at your option) any later version. 00016 * 00017 * This program is distributed in the hope that it will be useful, 00018 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00019 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00020 * GNU General Public License for more details. 00021 * 00022 * You should have received a copy of the GNU General Public License 00023 * along with this program; if not, write to the Free Software 00024 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 00025 * 00026 * $Id: hdlc.h,v 1.14 2005/11/28 13:43:34 steveu Exp $ 00027 */ 00028 00029 /*! \file */ 00030 00031 /*! \page hdlc_page HDLC 00032 00033 \section hdlc_page_sec_1 What does it do? 00034 The HDLC module provides bit stuffing, destuffing, framing and deframing, 00035 according to the HDLC protocol. It also provides 16 and 32 bit CRC generation 00036 and checking services for HDLC frames. 00037 00038 HDLC may not be a DSP function, but is needed to accompany several DSP components. 00039 00040 \section hdlc_page_sec_2 How does it work? 00041 */ 00042 00043 00044 #if !defined(_HDLC_H_) 00045 #define _HDLC_H_ 00046 00047 /*! 00048 HDLC_MAXFRAME_LEN is the maximum length of a stuffed HDLC frame, excluding the CRC. 00049 */ 00050 #define HDLC_MAXFRAME_LEN 400 00051 00052 typedef void (*hdlc_frame_handler_t)(void *user_data, int ok, const uint8_t *pkt, int len); 00053 typedef void (*hdlc_underflow_handler_t)(void *user_data); 00054 00055 /*! 00056 HDLC receive descriptor. This contains all the state information for an HDLC receiver. 00057 */ 00058 typedef struct 00059 { 00060 /*! 2 for CRC-16, 4 for CRC-32 */ 00061 int crc_bytes; 00062 /*! \brief The callback routine called to process each good received frame. */ 00063 hdlc_frame_handler_t frame_handler; 00064 /*! \brief An opaque parameter passed to the callback routine. */ 00065 void *user_data; 00066 int report_bad_frames; 00067 int framing_ok_threshold; 00068 int flags_seen; 00069 00070 /*! \brief 0 = sync hunt, !0 = receiving */ 00071 int rx_state; 00072 unsigned int bit_buf; 00073 unsigned int byte_in_progress; 00074 int num_bits; 00075 00076 /*! \brief Buffer for a frame in progress. */ 00077 uint8_t buffer[HDLC_MAXFRAME_LEN + 2]; 00078 /*! \brief Length of a frame in progress. */ 00079 int len; 00080 00081 /*! \brief The number of bytes of good frames received (CRC not included). */ 00082 unsigned long int rx_bytes; 00083 /*! \brief The number of good frames received. */ 00084 unsigned long int rx_frames; 00085 /*! \brief The number of frames with CRC errors received. */ 00086 unsigned long int rx_crc_errors; 00087 /*! \brief The number of too short and too long frames received. */ 00088 unsigned long int rx_length_errors; 00089 /*! \brief The number of HDLC aborts received. */ 00090 unsigned long int rx_aborts; 00091 } hdlc_rx_state_t; 00092 00093 /*! 00094 HDLC received data statistics. 00095 */ 00096 typedef struct 00097 { 00098 /*! \brief The number of bytes of good frames received (CRC not included). */ 00099 unsigned long int bytes; 00100 /*! \brief The number of good frames received. */ 00101 unsigned long int good_frames; 00102 /*! \brief The number of frames with CRC errors received. */ 00103 unsigned long int crc_errors; 00104 /*! \brief The number of too short and too long frames received. */ 00105 unsigned long int length_errors; 00106 /*! \brief The number of HDLC aborts received. */ 00107 unsigned long int aborts; 00108 } hdlc_rx_stats_t; 00109 00110 /*! 00111 HDLC transmit descriptor. This contains all the state information for an 00112 HDLC transmitter. 00113 */ 00114 typedef struct 00115 { 00116 /*! 2 for CRC-16, 4 for CRC-32 */ 00117 int crc_bytes; 00118 /*! \brief The callback routine called to indicate transmit underflow. */ 00119 hdlc_underflow_handler_t underflow_handler; 00120 /*! \brief An opaque parameter passed to the callback routine. */ 00121 void *user_data; 00122 00123 int num_bits; 00124 int idle_byte; 00125 00126 int len; 00127 uint8_t buffer[HDLC_MAXFRAME_LEN + 2]; 00128 int pos; 00129 00130 int byte; 00131 int bits; 00132 00133 int underflow_reported; 00134 } hdlc_tx_state_t; 00135 00136 #ifdef __cplusplus 00137 extern "C" { 00138 #endif 00139 00140 /*! \brief Calculate the ITU/CCITT CRC-32 value in buffer. 00141 \param buf The buffer containing the data. 00142 \param len The length of the frame. 00143 \param crc The initial CRC value. This is usually 0xFFFFFFFF, or 0 for a new block (it depends on 00144 the application). It is previous returned CRC value for the continuation of a block. 00145 \return The CRC value. 00146 */ 00147 uint32_t crc_itu32_calc(const uint8_t *buf, int len, uint32_t crc); 00148 00149 /*! \brief Append an ITU/CCITT CRC-32 value to a frame. 00150 \param buf The buffer containing the frame. This must be at least 2 bytes longer than 00151 the frame it contains, to allow room for the CRC value. 00152 \param len The length of the frame. 00153 \return The new length of the frame. 00154 */ 00155 int crc_itu32_append(uint8_t *buf, int len); 00156 00157 /*! \brief Check the ITU/CCITT CRC-32 value in a frame. 00158 \param buf The buffer containing the frame. 00159 \param len The length of the frame. 00160 \return TRUE if the CRC is OK, else FALSE. 00161 */ 00162 int crc_itu32_check(const uint8_t *buf, int len); 00163 00164 /*! \brief Calculate the ITU/CCITT CRC-16 value in buffer. 00165 \param buf The buffer containing the data. 00166 \param len The length of the frame. 00167 \param crc The initial CRC value. This is usually 0xFFFF, or 0 for a new block (it depends on 00168 the application). It is previous returned CRC value for the continuation of a block. 00169 \return The CRC value. 00170 */ 00171 uint16_t crc_itu16_calc(const uint8_t *buf, int len, uint16_t crc); 00172 00173 /*! \brief Append an ITU/CCITT CRC-16 value to a frame. 00174 \param buf The buffer containing the frame. This must be at least 2 bytes longer than 00175 the frame it contains, to allow room for the CRC value. 00176 \param len The length of the frame. 00177 \return The new length of the frame. 00178 */ 00179 int crc_itu16_append(uint8_t *buf, int len); 00180 00181 /*! \brief Check the ITU/CCITT CRC-16 value in a frame. 00182 \param buf The buffer containing the frame. 00183 \param len The length of the frame. 00184 \return TRUE if the CRC is OK, else FALSE. 00185 */ 00186 int crc_itu16_check(const uint8_t *buf, int len); 00187 00188 /*! \brief Initialise an HDLC receiver context. 00189 \param s A pointer to an HDLC receiver context. 00190 \param crc32 TRUE to use CRC32. FALSE to use CRC16. 00191 \param report_bad_frames TRUE to request the reporting of bad frames. 00192 \param framing_ok_threshold The number of flags needed to start the framing OK condition. 00193 \param handler The function to be called when a good HDLC frame is received. 00194 \param user_data An opaque parameter for the callback routine. 00195 \return A pointer to the HDLC receiver context. 00196 */ 00197 hdlc_rx_state_t *hdlc_rx_init(hdlc_rx_state_t *s, 00198 int crc32, 00199 int report_bad_frames, 00200 int framing_ok_threshold, 00201 hdlc_frame_handler_t handler, 00202 void *user_data); 00203 00204 /*! \brief Get the current receive statistics. 00205 \param s A pointer to an HDLC receiver context. 00206 \param t A pointer to the buffer for the statistics. 00207 \return 0 for OK, else -1. 00208 */ 00209 int hdlc_rx_get_stats(hdlc_rx_state_t *s, 00210 hdlc_rx_stats_t *t); 00211 00212 /* Use either the bit-by-bit or byte-by-byte routines. Do not mix them is a 00213 single instance of HDLC */ 00214 void hdlc_rx_bit(hdlc_rx_state_t *s, int new_bit); 00215 void hdlc_rx_byte(hdlc_rx_state_t *s, int new_byte); 00216 00217 /*! \brief Initialise an HDLC transmitter context. 00218 \param s A pointer to an HDLC transmitter context. 00219 \param handler The callback function called when the HDLC transmitter underflows. 00220 \param user_data An opaque parameter for the callback routine. 00221 \return A pointer to the HDLC transmitter context. 00222 */ 00223 hdlc_tx_state_t *hdlc_tx_init(hdlc_tx_state_t *s, 00224 int crc32, 00225 hdlc_underflow_handler_t handler, 00226 void *user_data); 00227 void hdlc_tx_frame(hdlc_tx_state_t *s, const uint8_t *frame, int len); 00228 void hdlc_tx_preamble(hdlc_tx_state_t *s, int len); 00229 int hdlc_tx_getbit(hdlc_tx_state_t *s); 00230 int hdlc_tx_getbyte(hdlc_tx_state_t *s); 00231 00232 #ifdef __cplusplus 00233 } 00234 #endif 00235 00236 #endif 00237 /*- End of file ------------------------------------------------------------*/