async.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * async.h - Asynchronous serial bit stream encoding and decoding
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: async.h,v 1.2 2005/11/25 14:52:00 steveu Exp $
00027  */
00028 
00029 /*! \file */
00030 
00031 /*! \page async_page Asynchronous bit stream processing
00032 \section async_page_sec_1 What does it do?
00033 The asynchronous serial bit stream processing module provides
00034 generation and decoding facilities for most asynchronous data
00035 formats. It supports:
00036  - 1 or 2 stop bits.
00037  - Odd, even or no parity.
00038  - 5, 6, 7, or 8 bit characters.
00039  - V.14 rate adaption.
00040 The input to this module is a bit stream. This means any symbol synchronisation
00041 and decoding must occur before data is fed to this module.
00042 
00043 \section async_page_sec_2 The transmitter
00044 ???.
00045 
00046 \section async_page_sec_3 The receiver
00047 ???.
00048 */
00049 
00050 #if !defined(_ASYNC_H_)
00051 #define _ASYNC_H_
00052 
00053 /* Special "bit" values for the put and get bit functions */
00054 enum
00055 {
00056     PUTBIT_CARRIER_DOWN = -1,
00057     PUTBIT_CARRIER_UP = -2,
00058     PUTBIT_TRAINING_SUCCEEDED = -3,
00059     PUTBIT_TRAINING_FAILED = -4,
00060     PUTBIT_FRAMING_OK = -5,
00061     PUTBIT_END_OF_DATA = -6
00062 };
00063 
00064 /*! Message put function for data pumps */
00065 typedef void (*put_msg_func_t)(void *user_data, const uint8_t *msg, int len);
00066 
00067 /*! Message get function for data pumps */
00068 typedef int (*get_msg_func_t)(void *user_data, uint8_t *msg, int max_len);
00069 
00070 /*! Byte put function for data pumps */
00071 typedef void (*put_byte_func_t)(void *user_data, int byte);
00072 
00073 /*! Byte get function for data pumps */
00074 typedef int (*get_byte_func_t)(void *user_data);
00075 
00076 /*! Bit put function for data pumps */
00077 typedef void (*put_bit_func_t)(void *user_data, int bit);
00078 
00079 /*! Bit get function for data pumps */
00080 typedef int (*get_bit_func_t)(void *user_data);
00081 
00082 /*! No parity bit should be used */
00083 #define ASYNC_PARITY_NONE   0
00084 /*! An even parity bit will exist, after the data bits */
00085 #define ASYNC_PARITY_EVEN   1
00086 /*! An odd parity bit will exist, after the data bits */
00087 #define ASYNC_PARITY_ODD    2
00088 
00089 /*!
00090     Asynchronous data transmit descriptor. This defines the state of a single
00091     working instance of a byte to asynchronous serial converter, for use
00092     in FSK modems.
00093 */
00094 typedef struct
00095 {
00096     /*! \brief The number of data bits per character. */
00097     int data_bits;
00098     /*! \brief The type of parity. */
00099     int parity;
00100     /*! \brief The number of stop bits per character. */
00101     int stop_bits;
00102     /*! \brief A pointer to the callback routine used to get characters to be transmitted. */
00103     get_byte_func_t get_byte;
00104     /*! \brief An opaque pointer passed when calling get_byte. */
00105     void *user_data;
00106 
00107     /*! \brief A current, partially transmitted, character. */
00108     int byte_in_progress;
00109     /*! \brief The current bit position within a partially transmitted character. */
00110     int bitpos;
00111     int parity_bit;
00112 } async_tx_state_t;
00113 
00114 /*!
00115     Asynchronous data receive descriptor. This defines the state of a single
00116     working instance of an asynchronous serial to byte converter, for use
00117     in FSK modems.
00118 */
00119 typedef struct
00120 {
00121     /*! \brief The number of data bits per character. */
00122     int data_bits;
00123     /*! \brief The type of parity. */
00124     int parity;
00125     /*! \brief The number of stop bits per character. */
00126     int stop_bits;
00127     /*! \brief TRUE if V.14 rate adaption processing should be performed. */
00128     int use_v14;
00129     /*! \brief A pointer to the callback routine used to handle received characters. */
00130     put_byte_func_t put_byte;
00131     /*! \brief An opaque pointer passed when calling put_byte. */
00132     void *user_data;
00133 
00134     /*! \brief A current, partially complete, character. */
00135     int byte_in_progress;
00136     /*! \brief The current bit position within a partially complete character. */
00137     int bitpos;
00138     int parity_bit;
00139 
00140     int parity_errors;
00141     int framing_errors;
00142 } async_rx_state_t;
00143 
00144 #ifdef __cplusplus
00145 extern "C" {
00146 #endif
00147 
00148 /*! Initialise an asynchronous data transmit context.
00149     \brief Initialise an asynchronous data transmit context.
00150     \param s The transmitter context.
00151     \param data_bits The number of data bit.
00152     \param parity_bits The type of parity.
00153     \param stop_bits The number of stop bits.
00154     \param use_v14 TRUE if V.14 rate adaption processing should be used.
00155     \param get_byte The callback routine used to get the data to be transmitted.
00156     \param user_data An opaque pointer. */
00157 void async_tx_init(async_tx_state_t *s,
00158                    int data_bits,
00159                    int parity_bits,
00160                    int stop_bits,
00161                    int use_v14,
00162                    get_byte_func_t get_byte,
00163                    void *user_data);
00164 
00165 /*! Get the next bit of a transmitted serial bit stream.
00166     \brief Get the next bit of a transmitted serial bit stream.
00167     \param user_data An opaque point which must point to a transmitter context.
00168     \return the next bit, or PUTBIT_END_OF_DATA to indicate the data stream has ended. */
00169 int async_tx_bit(void *user_data);
00170 
00171 /*! Initialise an asynchronous data receiver context.
00172     \brief Initialise an asynchronous data receiver context.
00173     \param s The receiver context.
00174     \param data_bits The number of data bits.
00175     \param parity_bits The type of parity.
00176     \param stop_bits The number of stop bits.
00177     \param use_v14 TRUE if V.14 rate adaption processing should be used.
00178     \param put_byte The callback routine used to put the received data.
00179     \param user_data An opaque pointer. */
00180 void async_rx_init(async_rx_state_t *s,
00181                    int data_bits,
00182                    int parity_bits,
00183                    int stop_bits,
00184                    int use_v14,
00185                    put_byte_func_t put_byte,
00186                    void *user_data);
00187 
00188 /*! Accept a bit from a received serial bit stream
00189     \brief Accept a bit from a received serial bit stream
00190     \param user_data An opaque point which must point to a receiver context.
00191     \param bit The new bit. Some special values are supported for this field.
00192         - PUTBIT_CARRIER_UP
00193         - PUTBIT_CARRIER_DOWN
00194         - PUTBIT_TRAINING_SUCCEEDED
00195         - PUTBIT_TRAINING_FAILED
00196         - PUTBIT_END_OF_DATA */
00197 void async_rx_bit(void *user_data, int bit);
00198 
00199 #ifdef __cplusplus
00200 }
00201 #endif
00202 
00203 #endif
00204 /*- End of file ------------------------------------------------------------*/

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