bert.h

00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * bert.h - Bit error rate tests.
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2004 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: bert.h,v 1.9 2005/12/29 09:54:24 steveu Exp $
00027  */
00028 
00029 #if !defined(_BERT_H_)
00030 #define _BERT_H_
00031 
00032 /*! \page bert_page The Bit Error Rate tester
00033 \section bert_page_sec_1 What does it do?
00034 The Bit Error Rate tester generates a pseudo random bit stream. It also accepts such
00035 a pattern, synchronises to it, and checks the bit error rate in this stream.
00036 
00037 \section bert_page_sec_2 How does it work?
00038 The Bit Error Rate tester generates a bit stream, with a repeating 2047 bit pseudo
00039 random pattern, using an 11 stage polynomial generator. It also accepts such a pattern,
00040 synchronises to it, and checks the bit error rate in this stream. If the error rate is
00041 excessive the tester assumes synchronisation has been lost, and it attempts to
00042 resynchronise with the stream.
00043 
00044 The bit error rate is continuously assessed against decadic ranges -
00045     > 1 in 10^2
00046     > 1 in 10^3
00047     > 1 in 10^4
00048     > 1 in 10^5
00049     > 1 in 10^6
00050     > 1 in 10^7
00051     < 1 in 10^7
00052 To ensure fairly smooth results from this assessment, each decadic level is assessed
00053 over 10/error rate bits. That is, to assess if the signal's BER is above or below 1 in 10^5
00054 the software looks over 10*10^5 => 10^6 bits.
00055 */
00056 
00057 enum
00058 {
00059     BERT_REPORT_SYNCED,
00060     BERT_REPORT_UNSYNCED,
00061     BERT_REPORT_REGULAR,
00062     BERT_REPORT_GT_10_2,
00063     BERT_REPORT_LT_10_2,
00064     BERT_REPORT_LT_10_3,
00065     BERT_REPORT_LT_10_4,
00066     BERT_REPORT_LT_10_5,
00067     BERT_REPORT_LT_10_6,
00068     BERT_REPORT_LT_10_7
00069 };
00070 
00071 /* The QBF strings should be:
00072     "VoyeZ Le BricK GeanT QuE J'ExaminE PreS Du WharF 123 456 7890 + - * : = $ % ( )"
00073     "ThE QuicK BrowN FoX JumpS OveR ThE LazY DoG 123 456 7890 + - * : = $ % ( )"
00074 */
00075 
00076 enum
00077 {
00078     BERT_PATTERN_ZEROS,
00079     BERT_PATTERN_ONES,
00080     BERT_PATTERN_7_TO_1,
00081     BERT_PATTERN_3_TO_1,
00082     BERT_PATTERN_1_TO_1,
00083     BERT_PATTERN_1_TO_3,
00084     BERT_PATTERN_1_TO_7,
00085     BERT_PATTERN_QBF,
00086     BERT_PATTERN_ITU_O151_23,
00087     BERT_PATTERN_ITU_O151_20,
00088     BERT_PATTERN_ITU_O151_15,
00089     BERT_PATTERN_ITU_O152_11,
00090     BERT_PATTERN_ITU_O153_9
00091 };
00092 
00093 typedef void (*bert_report_func_t)(void *user_data, int reason);
00094 
00095 /*!
00096     Bit error rate tester (BERT) descriptor. This defines the working state for a
00097     single instance of the BERT.
00098 */
00099 typedef struct
00100 {
00101     int pattern;
00102     int pattern_class;
00103     bert_report_func_t reporter;
00104     void *user_data;
00105     int report_frequency;
00106     int limit;
00107 
00108     uint32_t tx_reg;
00109     int tx_step;
00110     int tx_step_bit;
00111     int tx_bits;
00112     int tx_zeros;
00113 
00114     uint32_t rx_reg;
00115     uint32_t ref_reg;
00116     uint32_t master_reg;
00117     int rx_step;
00118     int rx_step_bit;
00119     int resync;
00120     int rx_bits;
00121     int rx_zeros;
00122     int resync_len;
00123     int resync_percent;
00124     int resync_bad_bits;
00125     int resync_cnt;
00126     int total_bits;
00127     int bad_bits;
00128     int resyncs;
00129     
00130     uint32_t mask;
00131     int shift;
00132     int shift2;
00133     int max_zeros;
00134     int invert;
00135     int resync_time;
00136 
00137     int decade_ptr[8];
00138     int decade_bad[8][10];
00139     int step;
00140     int error_rate;
00141 
00142     int bit_error_status;
00143     int report_countdown;
00144 } bert_state_t;
00145 
00146 /*!
00147     Bit error rate tester (BERT) results descriptor. This is used to report the
00148     results of a BER test.
00149 */
00150 typedef struct
00151 {
00152     int total_bits;
00153     int bad_bits;
00154     int resyncs;
00155 } bert_results_t;
00156 
00157 #ifdef __cplusplus
00158 extern "C" {
00159 #endif
00160 
00161 /*! Initialise a BERT context.
00162     \param s The BERT context.
00163     \param limit The maximum test duration.
00164     \param pattern One of the supported BERT signal patterns.
00165     \param resync_len ???
00166     \param resync_percent The percentage of bad bits which will cause a resync.
00167     \return The BERT context. */
00168 bert_state_t *bert_init(bert_state_t *s, int limit, int pattern, int resync_len, int resync_percent);
00169 
00170 /*! Get the next bit of the BERT sequence from the generator.
00171     \param s The BERT context.
00172     \return The bit. */
00173 int bert_get_bit(bert_state_t *s);
00174 
00175 /*! Put the next bit of the BERT sequence to the analyser.
00176     \param s The BERT context.
00177     \param bit The bit. */
00178 void bert_put_bit(bert_state_t *s, int bit);
00179 
00180 /*! Set the callback function for reporting the test status.
00181     \param s The BERT context.
00182     \param freq The required frequency of regular reports.
00183     \param reporter The callback function.
00184     \param user_data An opaque pointer passed to the reporter routine. */
00185 void bert_set_report(bert_state_t *s, int freq, bert_report_func_t reporter, void *user_data);
00186 
00187 /*! Get the results of the BERT.
00188     \param s The BERT context.
00189     \param results The results.
00190     \return The size of the result structure. */
00191 int bert_result(bert_state_t *s, bert_results_t *results);
00192 
00193 #ifdef __cplusplus
00194 }
00195 #endif
00196 
00197 #endif
00198 /*- End of file ------------------------------------------------------------*/

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