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 version 2, as
00014  * 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 General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU General Public License
00022  * along with this program; if not, write to the Free Software
00023  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00024  *
00025  * $Id: hdlc.h,v 1.30 2007/04/08 08:16:18 steveu Exp $
00026  */
00027 
00028 /*! \file */
00029 
00030 /*! \page hdlc_page HDLC
00031 
00032 \section hdlc_page_sec_1 What does it do?
00033 The HDLC module provides bit stuffing, destuffing, framing and deframing,
00034 according to the HDLC protocol. It also provides 16 and 32 bit CRC generation
00035 and checking services for HDLC frames.
00036 
00037 HDLC may not be a DSP function, but is needed to accompany several DSP components.
00038 
00039 \section hdlc_page_sec_2 How does it work?
00040 */
00041 
00042 
00043 #if !defined(_SPANDSP_HDLC_H_)
00044 #define _SPANDSP_HDLC_H_
00045 
00046 /*! 
00047     HDLC_MAXFRAME_LEN is the maximum length of a stuffed HDLC frame, excluding the CRC.
00048 */
00049 #define HDLC_MAXFRAME_LEN       400     
00050 
00051 typedef void (*hdlc_frame_handler_t)(void *user_data, int ok, const uint8_t *pkt, int len);
00052 typedef void (*hdlc_underflow_handler_t)(void *user_data);
00053 
00054 /*!
00055     HDLC receive descriptor. This contains all the state information for an HDLC receiver.
00056  */
00057 typedef struct
00058 {
00059     /*! 2 for CRC-16, 4 for CRC-32 */
00060     int crc_bytes;
00061     /*! \brief The callback routine called to process each good received frame. */
00062     hdlc_frame_handler_t frame_handler;
00063     /*! \brief An opaque parameter passed to the callback routine. */
00064     void *user_data;
00065     /*! \brief TRUE if bad frames are to be reported. */
00066     int report_bad_frames;
00067     /*! \brief The number of consecutive flags which must be seen before framing is
00068         declared OK. */
00069     int framing_ok_threshold;
00070     /*! \brief TRUE if framing OK has been announced. */
00071     int framing_ok_announced;
00072     /*! \brief Number of consecutive flags seen so far. */
00073     int flags_seen;
00074 
00075     /*! \brief The raw (stuffed) bit stream buffer. */
00076     unsigned int raw_bit_stream;
00077     /*! \brief The destuffed bit stream buffer. */
00078     unsigned int byte_in_progress;
00079     /*! \brief The current number of bits in byte_in_progress. */
00080     int num_bits;
00081         
00082     /*! \brief Buffer for a frame in progress. */
00083     uint8_t buffer[HDLC_MAXFRAME_LEN + 4];
00084     /*! \brief Length of a frame in progress. */
00085     int len;
00086 
00087     /*! \brief The number of bytes of good frames received (CRC not included). */
00088     unsigned long int rx_bytes;
00089     /*! \brief The number of good frames received. */
00090     unsigned long int rx_frames;
00091     /*! \brief The number of frames with CRC errors received. */
00092     unsigned long int rx_crc_errors;
00093     /*! \brief The number of too short and too long frames received. */
00094     unsigned long int rx_length_errors;
00095     /*! \brief The number of HDLC aborts received. */
00096     unsigned long int rx_aborts;
00097 } hdlc_rx_state_t;
00098 
00099 /*!
00100     HDLC received data statistics.
00101  */
00102 typedef struct
00103 {
00104     /*! \brief The number of bytes of good frames received (CRC not included). */
00105     unsigned long int bytes;
00106     /*! \brief The number of good frames received. */
00107     unsigned long int good_frames;
00108     /*! \brief The number of frames with CRC errors received. */
00109     unsigned long int crc_errors;
00110     /*! \brief The number of too short and too long frames received. */
00111     unsigned long int length_errors;
00112     /*! \brief The number of HDLC aborts received. */
00113     unsigned long int aborts;
00114 } hdlc_rx_stats_t;
00115 
00116 /*!
00117     HDLC transmit descriptor. This contains all the state information for an
00118     HDLC transmitter.
00119  */
00120 typedef struct
00121 {
00122     /*! 2 for CRC-16, 4 for CRC-32 */
00123     int crc_bytes;
00124     /*! \brief The callback routine called to indicate transmit underflow. */
00125     hdlc_underflow_handler_t underflow_handler;
00126     /*! \brief An opaque parameter passed to the callback routine. */
00127     void *user_data;
00128     /*! \brief The minimum flag octets to insert between frames. */
00129     int inter_frame_flags;
00130     /*! \brief TRUE if frame creation works in progressive mode. */
00131     int progressive;
00132     /*! \brief Maximum permitted frame length. */
00133     int max_frame_len;
00134 
00135     /*! \brief The stuffed bit stream being created. */
00136     uint32_t octets_in_progress;
00137     /*! \brief The number of bits currently in octets_in_progress. */
00138     int num_bits;
00139     /*! \brief The currently rotated state of the flag octet. */
00140     int idle_octet;
00141     /*! \brief The number of flag octets to send for a timed burst of flags. */
00142     int flag_octets;
00143     /*! \brief TRUE if the next underflow of timed flag octets should be reported */
00144     int report_flag_underflow;
00145 
00146     /*! \brief The current message being transmitted, with its CRC attached. */
00147     uint8_t buffer[HDLC_MAXFRAME_LEN + 4];
00148     /*! \brief The length of the message in the buffer. */
00149     int len;
00150     /*! \brief The current send position within the buffer. */
00151     int pos;
00152     /*! \brief The running CRC, as data fills the frame buffer. */
00153     uint32_t crc;
00154 
00155     /*! \brief The current byte being broken into bits for transmission. */
00156     int byte;
00157     /*! \brief The number of bits remaining in byte. */
00158     int bits;
00159     
00160     /*! \brief TRUE if transmission should end on buffer underflow .*/
00161     int tx_end;
00162 } hdlc_tx_state_t;
00163 
00164 #if defined(__cplusplus)
00165 extern "C"
00166 {
00167 #endif
00168 
00169 /*! \brief Calculate the ITU/CCITT CRC-32 value in buffer.
00170     \param buf The buffer containing the data.
00171     \param len The length of the frame.
00172     \param crc The initial CRC value. This is usually 0xFFFFFFFF, or 0 for a new block (it depends on
00173            the application). It is previous returned CRC value for the continuation of a block.
00174     \return The CRC value.
00175 */
00176 uint32_t crc_itu32_calc(const uint8_t *buf, int len, uint32_t crc);
00177 
00178 /*! \brief Append an ITU/CCITT CRC-32 value to a frame.
00179     \param buf The buffer containing the frame. This must be at least 2 bytes longer than
00180                the frame it contains, to allow room for the CRC value.
00181     \param len The length of the frame.
00182     \return The new length of the frame.
00183 */
00184 int crc_itu32_append(uint8_t *buf, int len);
00185 
00186 /*! \brief Check the ITU/CCITT CRC-32 value in a frame.
00187     \param buf The buffer containing the frame.
00188     \param len The length of the frame.
00189     \return TRUE if the CRC is OK, else FALSE.
00190 */
00191 int crc_itu32_check(const uint8_t *buf, int len);
00192 
00193 /*! \brief Calculate the ITU/CCITT CRC-16 value in buffer.
00194     \param buf The buffer containing the data.
00195     \param len The length of the frame.
00196     \param crc The initial CRC value. This is usually 0xFFFF, or 0 for a new block (it depends on
00197            the application). It is previous returned CRC value for the continuation of a block.
00198     \return The CRC value.
00199 */
00200 uint16_t crc_itu16_calc(const uint8_t *buf, int len, uint16_t crc);
00201 
00202 /*! \brief Append an ITU/CCITT CRC-16 value to a frame.
00203     \param buf The buffer containing the frame. This must be at least 2 bytes longer than
00204                the frame it contains, to allow room for the CRC value.
00205     \param len The length of the frame.
00206     \return The new length of the frame.
00207 */
00208 int crc_itu16_append(uint8_t *buf, int len);
00209 
00210 /*! \brief Check the ITU/CCITT CRC-16 value in a frame.
00211     \param buf The buffer containing the frame.
00212     \param len The length of the frame.
00213     \return TRUE if the CRC is OK, else FALSE.
00214 */
00215 int crc_itu16_check(const uint8_t *buf, int len);
00216 
00217 /*! \brief Initialise an HDLC receiver context.
00218     \param s A pointer to an HDLC receiver context.
00219     \param crc32 TRUE to use ITU CRC32. FALSE to use ITU CRC16.
00220     \param report_bad_frames TRUE to request the reporting of bad frames.
00221     \param framing_ok_threshold The number of back-to-back flags needed to
00222            start the framing OK condition. This may be used where a series of
00223            flag octets is used as a preamble, such as in the T.30 protocol.
00224     \param handler The function to be called when a good HDLC frame is received.
00225     \param user_data An opaque parameter for the callback routine.
00226     \return A pointer to the HDLC receiver context.
00227 */
00228 hdlc_rx_state_t *hdlc_rx_init(hdlc_rx_state_t *s,
00229                               int crc32,
00230                               int report_bad_frames,
00231                               int framing_ok_threshold,
00232                               hdlc_frame_handler_t handler,
00233                               void *user_data);
00234 
00235 /*! \brief Get the current receive statistics.
00236     \param s A pointer to an HDLC receiver context.
00237     \param t A pointer to the buffer for the statistics.
00238     \return 0 for OK, else -1.
00239 */
00240 int hdlc_rx_get_stats(hdlc_rx_state_t *s,
00241                       hdlc_rx_stats_t *t);
00242 
00243 /* Use either the bit-by-bit or byte-by-byte routines. Do not mix them is a
00244    single instance of HDLC */
00245 void hdlc_rx_put_bit(hdlc_rx_state_t *s, int new_bit);
00246 void hdlc_rx_put_byte(hdlc_rx_state_t *s, int new_byte);
00247 
00248 /*! \brief Initialise an HDLC transmitter context.
00249     \param s A pointer to an HDLC transmitter context.
00250     \param crc32 TRUE to use ITU CRC32. FALSE to use ITU CRC16.
00251     \param inter_frame_flags The minimum flag octets to insert between frames (usually one).
00252     \param progressive TRUE if frame creation works in progressive mode.
00253     \param handler The callback function called when the HDLC transmitter underflows.
00254     \param user_data An opaque parameter for the callback routine.
00255     \return A pointer to the HDLC transmitter context.
00256 */
00257 hdlc_tx_state_t *hdlc_tx_init(hdlc_tx_state_t *s,
00258                               int crc32,
00259                               int inter_frame_flags,
00260                               int progressive,
00261                               hdlc_underflow_handler_t handler,
00262                               void *user_data);
00263 
00264 /*! \brief Set the maximum frame length for an HDLC transmitter context.
00265     \param s A pointer to an HDLC transmitter context.
00266     \param max_len The maximum length.
00267 */
00268 void hdlc_tx_set_max_frame_len(hdlc_tx_state_t *s, int max_len);
00269 
00270 /*! \brief Transmit a frame.
00271     \param s A pointer to an HDLC transmitter context.
00272     \param frame A pointer to the frame to be transmitted.
00273     \param len The length of the frame to be transmitted.
00274     \return 0 if the frame was accepted for transmission, else -1.
00275 */
00276 int hdlc_tx_frame(hdlc_tx_state_t *s, const uint8_t *frame, int len);
00277 
00278 /*! \brief Corrupt the frame currently being transmitted, by giving it the wrong CRC.
00279     \param s A pointer to an HDLC transmitter context.
00280     \return 0 if the frame was corrupted, else -1.
00281 */
00282 int hdlc_tx_corrupt_frame(hdlc_tx_state_t *s);
00283 
00284 /*! \brief Transmit a specified quantity of flag octets as a preamble.
00285     \param s A pointer to an HDLC transmitter context.
00286     \param len The length of the required preamble, in flag octets. If len is zero this
00287            requests that HDLC transmission be terminated when the buffers have fully
00288            drained.
00289     \return 0 if the preamble was accepted for transmission, else -1.
00290 */
00291 int hdlc_tx_preamble(hdlc_tx_state_t *s, int len);
00292 
00293 /*! \brief Get the next bit for transmission.
00294     \param s A pointer to an HDLC transmitter context.
00295     \return The next bit for transmission.
00296 */
00297 int hdlc_tx_get_bit(hdlc_tx_state_t *s);
00298 
00299 /*! \brief Get the next byte for transmission.
00300     \param s A pointer to an HDLC transmitter context.
00301     \return The next byte for transmission.
00302 */
00303 int hdlc_tx_get_byte(hdlc_tx_state_t *s);
00304 
00305 #if defined(__cplusplus)
00306 }
00307 #endif
00308 
00309 #endif
00310 /*- End of file ------------------------------------------------------------*/

Generated on Tue Jul 24 11:29:28 2007 for libspandsp by  doxygen 1.5.2