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 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  * $Id: hdlc.h,v 1.44 2009/02/12 12:38:39 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 hdlc_rx_state_s hdlc_rx_state_t;
00057 
00058 /*!
00059     HDLC received data statistics.
00060  */
00061 typedef struct
00062 {
00063     /*! \brief The number of bytes of good frames received (CRC not included). */
00064     unsigned long int bytes;
00065     /*! \brief The number of good frames received. */
00066     unsigned long int good_frames;
00067     /*! \brief The number of frames with CRC errors received. */
00068     unsigned long int crc_errors;
00069     /*! \brief The number of too short and too long frames received. */
00070     unsigned long int length_errors;
00071     /*! \brief The number of HDLC aborts received. */
00072     unsigned long int aborts;
00073 } hdlc_rx_stats_t;
00074 
00075 /*!
00076     HDLC transmit descriptor. This contains all the state information for an
00077     HDLC transmitter.
00078  */
00079 typedef struct hdlc_tx_state_s hdlc_tx_state_t;
00080 
00081 #if defined(__cplusplus)
00082 extern "C"
00083 {
00084 #endif
00085 
00086 /*! \brief Initialise an HDLC receiver context.
00087     \param s A pointer to an HDLC receiver context.
00088     \param crc32 TRUE to use ITU CRC32. FALSE to use ITU CRC16.
00089     \param report_bad_frames TRUE to request the reporting of bad frames.
00090     \param framing_ok_threshold The number of back-to-back flags needed to
00091            start the framing OK condition. This may be used where a series of
00092            flag octets is used as a preamble, such as in the T.30 protocol.
00093     \param handler The function to be called when a good HDLC frame is received.
00094     \param user_data An opaque parameter for the callback routine.
00095     \return A pointer to the HDLC receiver context.
00096 */
00097 SPAN_DECLARE(hdlc_rx_state_t *) hdlc_rx_init(hdlc_rx_state_t *s,
00098                                              int crc32,
00099                                              int report_bad_frames,
00100                                              int framing_ok_threshold,
00101                                              hdlc_frame_handler_t handler,
00102                                              void *user_data);
00103 
00104 /*! Change the put_bit function associated with an HDLC receiver context.
00105     \brief Change the put_bit function associated with an HDLC receiver context.
00106     \param s A pointer to an HDLC receiver context.
00107     \param handler The function to be called when a good HDLC frame is received.
00108     \param user_data An opaque parameter for the callback routine.
00109 */
00110 SPAN_DECLARE(void) hdlc_rx_set_frame_handler(hdlc_rx_state_t *s, hdlc_frame_handler_t handler, void *user_data);
00111 
00112 /*! Change the status report function associated with an HDLC receiver context.
00113     \brief Change the status report function associated with an HDLC receiver context.
00114     \param s A pointer to an HDLC receiver context.
00115     \param handler The callback routine used to report status changes.
00116     \param user_data An opaque parameter for the callback routine.
00117 */
00118 SPAN_DECLARE(void) hdlc_rx_set_status_handler(hdlc_rx_state_t *s, modem_rx_status_func_t handler, void *user_data);
00119 
00120 /*! Release an HDLC receiver context.
00121     \brief Release an HDLC receiver context.
00122     \param s A pointer to an HDLC receiver context.
00123     \return 0 for OK */
00124 SPAN_DECLARE(int) hdlc_rx_release(hdlc_rx_state_t *s);
00125 
00126 /*! Free an HDLC receiver context.
00127     \brief Free an HDLC receiver context.
00128     \param s A pointer to an HDLC receiver context.
00129     \return 0 for OK */
00130 SPAN_DECLARE(int) hdlc_rx_free(hdlc_rx_state_t *s);
00131 
00132 /*! \brief Set the maximum frame length for an HDLC receiver context.
00133     \param s A pointer to an HDLC receiver context.
00134     \param max_len The maximum permitted length of a frame.
00135 */
00136 SPAN_DECLARE(void) hdlc_rx_set_max_frame_len(hdlc_rx_state_t *s, size_t max_len);
00137 
00138 /*! \brief Set the octet counting report interval.
00139     \param s A pointer to an HDLC receiver context.
00140     \param interval The interval, in octets.
00141 */
00142 SPAN_DECLARE(void) hdlc_rx_set_octet_counting_report_interval(hdlc_rx_state_t *s,
00143                                                               int interval);
00144 
00145 /*! \brief Get the current receive statistics.
00146     \param s A pointer to an HDLC receiver context.
00147     \param t A pointer to the buffer for the statistics.
00148     \return 0 for OK, else -1.
00149 */
00150 SPAN_DECLARE(int) hdlc_rx_get_stats(hdlc_rx_state_t *s,
00151                                     hdlc_rx_stats_t *t);
00152 
00153 /*! \brief Put a single bit of data to an HDLC receiver.
00154     \param s A pointer to an HDLC receiver context.
00155     \param new_bit The bit.
00156 */
00157 SPAN_DECLARE(void) hdlc_rx_put_bit(hdlc_rx_state_t *s, int new_bit);
00158 
00159 /*! \brief Put a byte of data to an HDLC receiver.
00160     \param s A pointer to an HDLC receiver context.
00161     \param new_byte The byte of data.
00162 */
00163 SPAN_DECLARE(void) hdlc_rx_put_byte(hdlc_rx_state_t *s, int new_byte);
00164 
00165 /*! \brief Put a series of bytes of data to an HDLC receiver.
00166     \param s A pointer to an HDLC receiver context.
00167     \param buf The buffer of data.
00168     \param len The length of the data in the buffer.
00169 */
00170 SPAN_DECLARE(void) hdlc_rx_put(hdlc_rx_state_t *s, const uint8_t buf[], int len);
00171 
00172 /*! \brief Initialise an HDLC transmitter context.
00173     \param s A pointer to an HDLC transmitter context.
00174     \param crc32 TRUE to use ITU CRC32. FALSE to use ITU CRC16.
00175     \param inter_frame_flags The minimum flag octets to insert between frames (usually one).
00176     \param progressive TRUE if frame creation works in progressive mode.
00177     \param handler The callback function called when the HDLC transmitter underflows.
00178     \param user_data An opaque parameter for the callback routine.
00179     \return A pointer to the HDLC transmitter context.
00180 */
00181 SPAN_DECLARE(hdlc_tx_state_t *) hdlc_tx_init(hdlc_tx_state_t *s,
00182                                              int crc32,
00183                                              int inter_frame_flags,
00184                                              int progressive,
00185                                              hdlc_underflow_handler_t handler,
00186                                              void *user_data);
00187 
00188 SPAN_DECLARE(int) hdlc_tx_release(hdlc_tx_state_t *s);
00189 
00190 SPAN_DECLARE(int) hdlc_tx_free(hdlc_tx_state_t *s);
00191 
00192 /*! \brief Set the maximum frame length for an HDLC transmitter context.
00193     \param s A pointer to an HDLC transmitter context.
00194     \param max_len The maximum length.
00195 */
00196 SPAN_DECLARE(void) hdlc_tx_set_max_frame_len(hdlc_tx_state_t *s, size_t max_len);
00197 
00198 /*! \brief Transmit a frame.
00199     \param s A pointer to an HDLC transmitter context.
00200     \param frame A pointer to the frame to be transmitted.
00201     \param len The length of the frame to be transmitted.
00202     \return 0 if the frame was accepted for transmission, else -1.
00203 */
00204 SPAN_DECLARE(int) hdlc_tx_frame(hdlc_tx_state_t *s, const uint8_t *frame, size_t len);
00205 
00206 /*! \brief Corrupt the frame currently being transmitted, by giving it the wrong CRC.
00207     \param s A pointer to an HDLC transmitter context.
00208     \return 0 if the frame was corrupted, else -1.
00209 */
00210 SPAN_DECLARE(int) hdlc_tx_corrupt_frame(hdlc_tx_state_t *s);
00211 
00212 /*! \brief Transmit a specified quantity of flag octets, typically as a preamble.
00213     \param s A pointer to an HDLC transmitter context.
00214     \param len The length of the required period of flags, in flag octets. If len is zero this
00215            requests that HDLC transmission be terminated when the buffers have fully
00216            drained.
00217     \return 0 if the flags were accepted for transmission, else -1.
00218 */
00219 SPAN_DECLARE(int) hdlc_tx_flags(hdlc_tx_state_t *s, int len);
00220 
00221 /*! \brief Send an abort.
00222     \param s A pointer to an HDLC transmitter context.
00223     \return 0 if the frame was aborted, else -1.
00224 */
00225 SPAN_DECLARE(int) hdlc_tx_abort(hdlc_tx_state_t *s);
00226 
00227 /*! \brief Get the next bit for transmission.
00228     \param s A pointer to an HDLC transmitter context.
00229     \return The next bit for transmission.
00230 */
00231 SPAN_DECLARE(int) hdlc_tx_get_bit(hdlc_tx_state_t *s);
00232 
00233 /*! \brief Get the next byte for transmission.
00234     \param s A pointer to an HDLC transmitter context.
00235     \return The next byte for transmission.
00236 */
00237 SPAN_DECLARE(int) hdlc_tx_get_byte(hdlc_tx_state_t *s);
00238 
00239 /*! \brief Get the next sequence of bytes for transmission.
00240     \param s A pointer to an HDLC transmitter context.
00241     \param buf The buffer for the data.
00242     \param max_len The number of bytes to get.
00243     \return The number of bytes actually got.
00244 */
00245 SPAN_DECLARE(int) hdlc_tx_get(hdlc_tx_state_t *s, uint8_t buf[], size_t max_len);
00246 
00247 #if defined(__cplusplus)
00248 }
00249 #endif
00250 
00251 #endif
00252 /*- End of file ------------------------------------------------------------*/

Generated by  doxygen 1.6.2