hdlc.h

Go to the documentation of this file.
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 ------------------------------------------------------------*/

Generated on Fri Nov 10 09:40:24 2006 for libspandsp by  doxygen 1.5.1