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 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: bert.h,v 1.23 2009/02/10 13:06:47 steveu Exp $
00026  */
00027 
00028 #if !defined(_SPANDSP_BERT_H_)
00029 #define _SPANDSP_BERT_H_
00030 
00031 /*! \page bert_page The Bit Error Rate tester
00032 \section bert_page_sec_1 What does it do?
00033 The Bit Error Rate tester generates a pseudo random bit stream. It also accepts such
00034 a pattern, synchronises to it, and checks the bit error rate in this stream.
00035 
00036 \section bert_page_sec_2 How does it work?
00037 The Bit Error Rate tester generates a bit stream, with a repeating 2047 bit pseudo
00038 random pattern, using an 11 stage polynomial generator. It also accepts such a pattern,
00039 synchronises to it, and checks the bit error rate in this stream. If the error rate is
00040 excessive the tester assumes synchronisation has been lost, and it attempts to
00041 resynchronise with the stream.
00042 
00043 The bit error rate is continuously assessed against decadic ranges -
00044     > 1 in 10^2
00045     > 1 in 10^3
00046     > 1 in 10^4
00047     > 1 in 10^5
00048     > 1 in 10^6
00049     > 1 in 10^7
00050     < 1 in 10^7
00051 To ensure fairly smooth results from this assessment, each decadic level is assessed
00052 over 10/error rate bits. That is, to assess if the signal's BER is above or below 1 in 10^5
00053 the software looks over 10*10^5 => 10^6 bits.
00054 */
00055 
00056 enum
00057 {
00058     BERT_REPORT_SYNCED = 0,
00059     BERT_REPORT_UNSYNCED,
00060     BERT_REPORT_REGULAR,
00061     BERT_REPORT_GT_10_2,
00062     BERT_REPORT_LT_10_2,
00063     BERT_REPORT_LT_10_3,
00064     BERT_REPORT_LT_10_4,
00065     BERT_REPORT_LT_10_5,
00066     BERT_REPORT_LT_10_6,
00067     BERT_REPORT_LT_10_7
00068 };
00069 
00070 /* The QBF strings should be:
00071     "VoyeZ Le BricK GeanT QuE J'ExaminE PreS Du WharF 123 456 7890 + - * : = $ % ( )"
00072     "ThE QuicK BrowN FoX JumpS OveR ThE LazY DoG 123 456 7890 + - * : = $ % ( )"
00073 */
00074 
00075 enum
00076 {
00077     BERT_PATTERN_ZEROS = 0,
00078     BERT_PATTERN_ONES,
00079     BERT_PATTERN_7_TO_1,
00080     BERT_PATTERN_3_TO_1,
00081     BERT_PATTERN_1_TO_1,
00082     BERT_PATTERN_1_TO_3,
00083     BERT_PATTERN_1_TO_7,
00084     BERT_PATTERN_QBF,
00085     BERT_PATTERN_ITU_O151_23,
00086     BERT_PATTERN_ITU_O151_20,
00087     BERT_PATTERN_ITU_O151_15,
00088     BERT_PATTERN_ITU_O152_11,
00089     BERT_PATTERN_ITU_O153_9
00090 };
00091 
00092 /*!
00093     Bit error rate tester (BERT) results descriptor. This is used to report the
00094     results of a BER test.
00095 */
00096 typedef struct
00097 {
00098     int total_bits;
00099     int bad_bits;
00100     int resyncs;
00101 } bert_results_t;
00102 
00103 typedef void (*bert_report_func_t)(void *user_data, int reason, bert_results_t *bert_results);
00104 
00105 /*!
00106     Bit error rate tester (BERT) descriptor. This defines the working state for a
00107     single instance of the BERT.
00108 */
00109 typedef struct bert_state_s bert_state_t;
00110 
00111 #if defined(__cplusplus)
00112 extern "C"
00113 {
00114 #endif
00115 
00116 /*! Return a short description of a BERT event.
00117     \param event The event type.
00118     \return A pointer to a short text string describing the event. */
00119 SPAN_DECLARE(const char *) bert_event_to_str(int event);
00120 
00121 /*! Initialise a BERT context.
00122     \param s The BERT context.
00123     \param limit The maximum test duration.
00124     \param pattern One of the supported BERT signal patterns.
00125     \param resync_len ???
00126     \param resync_percent The percentage of bad bits which will cause a resync.
00127     \return The BERT context. */
00128 SPAN_DECLARE(bert_state_t *) bert_init(bert_state_t *s, int limit, int pattern, int resync_len, int resync_percent);
00129 
00130 SPAN_DECLARE(int) bert_release(bert_state_t *s);
00131 
00132 SPAN_DECLARE(int) bert_free(bert_state_t *s);
00133 
00134 /*! Get the next bit of the BERT sequence from the generator.
00135     \param s The BERT context.
00136     \return The bit. */
00137 SPAN_DECLARE(int) bert_get_bit(bert_state_t *s);
00138 
00139 /*! Put the next bit of the BERT sequence to the analyser.
00140     \param s The BERT context.
00141     \param bit The bit. */
00142 SPAN_DECLARE(void) bert_put_bit(bert_state_t *s, int bit);
00143 
00144 /*! Set the callback function for reporting the test status.
00145     \param s The BERT context.
00146     \param freq The required frequency of regular reports.
00147     \param reporter The callback function.
00148     \param user_data An opaque pointer passed to the reporter routine. */
00149 SPAN_DECLARE(void) bert_set_report(bert_state_t *s, int freq, bert_report_func_t reporter, void *user_data);
00150 
00151 /*! Get the results of the BERT.
00152     \param s The BERT context.
00153     \param results The results.
00154     \return The size of the result structure. */
00155 SPAN_DECLARE(int) bert_result(bert_state_t *s, bert_results_t *results);
00156 
00157 #if defined(__cplusplus)
00158 }
00159 #endif
00160 
00161 #endif
00162 /*- End of file ------------------------------------------------------------*/

Generated on Tue Aug 4 03:35:55 2009 for spandsp by  doxygen 1.5.9