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.36 2007/08/25 05:10:42 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 #if !defined(_SPANDSP_HDLC_H_)
00043 #define _SPANDSP_HDLC_H_
00044 
00045 /*! 
00046     HDLC_MAXFRAME_LEN is the maximum length of a stuffed HDLC frame, excluding the CRC.
00047 */
00048 #define HDLC_MAXFRAME_LEN       400     
00049 
00050 typedef void (*hdlc_frame_handler_t)(void *user_data, const uint8_t *pkt, int len, int ok);
00051 typedef void (*hdlc_underflow_handler_t)(void *user_data);
00052 
00053 /*!
00054     HDLC receive descriptor. This contains all the state information for an HDLC receiver.
00055  */
00056 typedef struct
00057 {
00058     /*! 2 for CRC-16, 4 for CRC-32 */
00059     int crc_bytes;
00060     /*! \brief Maximum permitted frame length. */
00061     size_t max_frame_len;
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     /*! \brief TRUE if bad frames are to be reported. */
00067     int report_bad_frames;
00068     /*! \brief The number of consecutive flags which must be seen before framing is
00069         declared OK. */
00070     int framing_ok_threshold;
00071     /*! \brief TRUE if framing OK has been announced. */
00072     int framing_ok_announced;
00073     /*! \brief Number of consecutive flags seen so far. */
00074     int flags_seen;
00075 
00076     /*! \brief The raw (stuffed) bit stream buffer. */
00077     unsigned int raw_bit_stream;
00078     /*! \brief The destuffed bit stream buffer. */
00079     unsigned int byte_in_progress;
00080     /*! \brief The current number of bits in byte_in_progress. */
00081     int num_bits;
00082     int octet_counting_mode;
00083     /*! \brief Octet count, to achieve the functionality needed for things
00084                like MTP. */
00085     int octet_count;
00086     int octet_count_report_interval;
00087 
00088     /*! \brief Buffer for a frame in progress. */
00089     uint8_t buffer[HDLC_MAXFRAME_LEN + 4];
00090     /*! \brief Length of a frame in progress. */
00091     size_t len;
00092 
00093     /*! \brief The number of bytes of good frames received (CRC not included). */
00094     unsigned long int rx_bytes;
00095     /*! \brief The number of good frames received. */
00096     unsigned long int rx_frames;
00097     /*! \brief The number of frames with CRC errors received. */
00098     unsigned long int rx_crc_errors;
00099     /*! \brief The number of too short and too long frames received. */
00100     unsigned long int rx_length_errors;
00101     /*! \brief The number of HDLC aborts received. */
00102     unsigned long int rx_aborts;
00103 } hdlc_rx_state_t;
00104 
00105 /*!
00106     HDLC received data statistics.
00107  */
00108 typedef struct
00109 {
00110     /*! \brief The number of bytes of good frames received (CRC not included). */
00111     unsigned long int bytes;
00112     /*! \brief The number of good frames received. */
00113     unsigned long int good_frames;
00114     /*! \brief The number of frames with CRC errors received. */
00115     unsigned long int crc_errors;
00116     /*! \brief The number of too short and too long frames received. */
00117     unsigned long int length_errors;
00118     /*! \brief The number of HDLC aborts received. */
00119     unsigned long int aborts;
00120 } hdlc_rx_stats_t;
00121 
00122 /*!
00123     HDLC transmit descriptor. This contains all the state information for an
00124     HDLC transmitter.
00125  */
00126 typedef struct
00127 {
00128     /*! 2 for CRC-16, 4 for CRC-32 */
00129     int crc_bytes;
00130     /*! \brief The callback routine called to indicate transmit underflow. */
00131     hdlc_underflow_handler_t underflow_handler;
00132     /*! \brief An opaque parameter passed to the callback routine. */
00133     void *user_data;
00134     /*! \brief The minimum flag octets to insert between frames. */
00135     int inter_frame_flags;
00136     /*! \brief TRUE if frame creation works in progressive mode. */
00137     int progressive;
00138     /*! \brief Maximum permitted frame length. */
00139     size_t max_frame_len;
00140 
00141     /*! \brief The stuffed bit stream being created. */
00142     uint32_t octets_in_progress;
00143     /*! \brief The number of bits currently in octets_in_progress. */
00144     int num_bits;
00145     /*! \brief The currently rotated state of the flag octet. */
00146     int idle_octet;
00147     /*! \brief The number of flag octets to send for a timed burst of flags. */
00148     int flag_octets;
00149     /*! \brief The number of abort octets to send for a timed burst of aborts. */
00150     int abort_octets;
00151     /*! \brief TRUE if the next underflow of timed flag octets should be reported */
00152     int report_flag_underflow;
00153 
00154     /*! \brief The current message being transmitted, with its CRC attached. */
00155     uint8_t buffer[HDLC_MAXFRAME_LEN + 4];
00156     /*! \brief The length of the message in the buffer. */
00157     size_t len;
00158     /*! \brief The current send position within the buffer. */
00159     int pos;
00160     /*! \brief The running CRC, as data fills the frame buffer. */
00161     uint32_t crc;
00162 
00163     /*! \brief The current byte being broken into bits for transmission. */
00164     int byte;
00165     /*! \brief The number of bits remaining in byte. */
00166     int bits;
00167     
00168     /*! \brief TRUE if transmission should end on buffer underflow .*/
00169     int tx_end;
00170 } hdlc_tx_state_t;
00171 
00172 #if defined(__cplusplus)
00173 extern "C"
00174 {
00175 #endif
00176 
00177 /*! \brief Initialise an HDLC receiver context.
00178     \param s A pointer to an HDLC receiver context.
00179     \param crc32 TRUE to use ITU CRC32. FALSE to use ITU CRC16.
00180     \param report_bad_frames TRUE to request the reporting of bad frames.
00181     \param framing_ok_threshold The number of back-to-back flags needed to
00182            start the framing OK condition. This may be used where a series of
00183            flag octets is used as a preamble, such as in the T.30 protocol.
00184     \param handler The function to be called when a good HDLC frame is received.
00185     \param user_data An opaque parameter for the callback routine.
00186     \return A pointer to the HDLC receiver context.
00187 */
00188 hdlc_rx_state_t *hdlc_rx_init(hdlc_rx_state_t *s,
00189                               int crc32,
00190                               int report_bad_frames,
00191                               int framing_ok_threshold,
00192                               hdlc_frame_handler_t handler,
00193                               void *user_data);
00194 
00195 /*! \brief Set the maximum frame length for an HDLC receiver context.
00196     \param s A pointer to an HDLC receiver context.
00197     \param max_len The maximum permitted length of a frame.
00198 */
00199 void hdlc_rx_set_max_frame_len(hdlc_rx_state_t *s, size_t max_len);
00200 
00201 /*! \brief Set the octet counting report interval.
00202     \param s A pointer to an HDLC receiver context.
00203     \param interval The interval, in octets.
00204 */
00205 void hdlc_rx_set_octet_counting_report_interval(hdlc_rx_state_t *s, int interval);
00206 
00207 /*! \brief Get the current receive statistics.
00208     \param s A pointer to an HDLC receiver context.
00209     \param t A pointer to the buffer for the statistics.
00210     \return 0 for OK, else -1.
00211 */
00212 int hdlc_rx_get_stats(hdlc_rx_state_t *s,
00213                       hdlc_rx_stats_t *t);
00214 
00215 /*! \brief Put a single bit of data to an HDLC receiver.
00216     \param s A pointer to an HDLC receiver context.
00217     \param new_bit The bit.
00218 */
00219 void hdlc_rx_put_bit(hdlc_rx_state_t *s, int new_bit);
00220 
00221 /*! \brief Put a byte of data to an HDLC receiver.
00222     \param s A pointer to an HDLC receiver context.
00223     \param new_byte The byte of data.
00224 */
00225 void hdlc_rx_put_byte(hdlc_rx_state_t *s, int new_byte);
00226 
00227 /*! \brief Put a series of bytes of data to an HDLC receiver.
00228     \param s A pointer to an HDLC receiver context.
00229     \param buf The buffer of data.
00230     \param len The length of the data in the buffer.
00231 */
00232 void hdlc_rx_put(hdlc_rx_state_t *s, const uint8_t buf[], int len);
00233 
00234 /*! \brief Initialise an HDLC transmitter context.
00235     \param s A pointer to an HDLC transmitter context.
00236     \param crc32 TRUE to use ITU CRC32. FALSE to use ITU CRC16.
00237     \param inter_frame_flags The minimum flag octets to insert between frames (usually one).
00238     \param progressive TRUE if frame creation works in progressive mode.
00239     \param handler The callback function called when the HDLC transmitter underflows.
00240     \param user_data An opaque parameter for the callback routine.
00241     \return A pointer to the HDLC transmitter context.
00242 */
00243 hdlc_tx_state_t *hdlc_tx_init(hdlc_tx_state_t *s,
00244                               int crc32,
00245                               int inter_frame_flags,
00246                               int progressive,
00247                               hdlc_underflow_handler_t handler,
00248                               void *user_data);
00249 
00250 /*! \brief Set the maximum frame length for an HDLC transmitter context.
00251     \param s A pointer to an HDLC transmitter context.
00252     \param max_len The maximum length.
00253 */
00254 void hdlc_tx_set_max_frame_len(hdlc_tx_state_t *s, size_t max_len);
00255 
00256 /*! \brief Transmit a frame.
00257     \param s A pointer to an HDLC transmitter context.
00258     \param frame A pointer to the frame to be transmitted.
00259     \param len The length of the frame to be transmitted.
00260     \return 0 if the frame was accepted for transmission, else -1.
00261 */
00262 int hdlc_tx_frame(hdlc_tx_state_t *s, const uint8_t *frame, size_t len);
00263 
00264 /*! \brief Corrupt the frame currently being transmitted, by giving it the wrong CRC.
00265     \param s A pointer to an HDLC transmitter context.
00266     \return 0 if the frame was corrupted, else -1.
00267 */
00268 int hdlc_tx_corrupt_frame(hdlc_tx_state_t *s);
00269 
00270 /*! \brief Transmit a specified quantity of flag octets, typically as a preamble.
00271     \param s A pointer to an HDLC transmitter context.
00272     \param len The length of the required period of flags, in flag octets. If len is zero this
00273            requests that HDLC transmission be terminated when the buffers have fully
00274            drained.
00275     \return 0 if the flags were accepted for transmission, else -1.
00276 */
00277 int hdlc_tx_flags(hdlc_tx_state_t *s, int len);
00278 
00279 /*! \brief Send an abort.
00280     \param s A pointer to an HDLC transmitter context.
00281     \return 0 if the frame was aborted, else -1.
00282 */
00283 int hdlc_tx_abort(hdlc_tx_state_t *s);
00284 
00285 /*! \brief Get the next bit for transmission.
00286     \param s A pointer to an HDLC transmitter context.
00287     \return The next bit for transmission.
00288 */
00289 int hdlc_tx_get_bit(hdlc_tx_state_t *s);
00290 
00291 /*! \brief Get the next byte for transmission.
00292     \param s A pointer to an HDLC transmitter context.
00293     \return The next byte for transmission.
00294 */
00295 int hdlc_tx_get_byte(hdlc_tx_state_t *s);
00296 
00297 /*! \brief Get the next sequence of bytes for transmission.
00298     \param s A pointer to an HDLC transmitter context.
00299     \param buf The buffer for the data.
00300     \param len The number of bytes to get.
00301     \return The number of bytes actually got.
00302 */
00303 int hdlc_tx_get(hdlc_tx_state_t *s, uint8_t buf[], size_t max_len);
00304 
00305 #if defined(__cplusplus)
00306 }
00307 #endif
00308 
00309 #endif
00310 /*- End of file ------------------------------------------------------------*/

Generated on Sat Nov 3 00:52:52 2007 for libspandsp by  doxygen 1.5.2