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