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 ------------------------------------------------------------*/