spandsp: bert.h Source File

spandsp 0.0.6

bert.h
1/*
2 * SpanDSP - a series of DSP components for telephony
3 *
4 * bert.h - Bit error rate tests.
5 *
6 * Written by Steve Underwood <steveu@coppice.org>
7 *
8 * Copyright (C) 2004 Steve Underwood
9 *
10 * All rights reserved.
11 *
12 * This program is free software; you can redistribute it and/or modify
13 * it under the terms of the GNU Lesser General Public License version 2.1,
14 * as published by the Free Software Foundation.
15 *
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU Lesser General Public License for more details.
20 *
21 * You should have received a copy of the GNU Lesser General Public
22 * License along with this program; if not, write to the Free Software
23 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24 */
25
26#if !defined(_SPANDSP_BERT_H_)
27#define _SPANDSP_BERT_H_
28
29/*! \page bert_page The Bit Error Rate tester
30\section bert_page_sec_1 What does it do?
31The Bit Error Rate tester generates a pseudo random bit stream. It also accepts such
32a pattern, synchronises to it, and checks the bit error rate in this stream.
33
34\section bert_page_sec_2 How does it work?
35The Bit Error Rate tester generates a bit stream, with a repeating 2047 bit pseudo
36random pattern, using an 11 stage polynomial generator. It also accepts such a pattern,
37synchronises to it, and checks the bit error rate in this stream. If the error rate is
38excessive the tester assumes synchronisation has been lost, and it attempts to
39resynchronise with the stream.
40
41The bit error rate is continuously assessed against decadic ranges -
42 > 1 in 10^2
43 > 1 in 10^3
44 > 1 in 10^4
45 > 1 in 10^5
46 > 1 in 10^6
47 > 1 in 10^7
48 < 1 in 10^7
49To ensure fairly smooth results from this assessment, each decadic level is assessed
50over 10/error rate bits. That is, to assess if the signal's BER is above or below 1 in 10^5
51the software looks over 10*10^5 => 10^6 bits.
52*/
53
54enum
55{
56 BERT_REPORT_SYNCED = 0,
57 BERT_REPORT_UNSYNCED,
58 BERT_REPORT_REGULAR,
59 BERT_REPORT_GT_10_2,
60 BERT_REPORT_LT_10_2,
61 BERT_REPORT_LT_10_3,
62 BERT_REPORT_LT_10_4,
63 BERT_REPORT_LT_10_5,
64 BERT_REPORT_LT_10_6,
65 BERT_REPORT_LT_10_7
66};
67
68/* The QBF strings should be:
69 "VoyeZ Le BricK GeanT QuE J'ExaminE PreS Du WharF 123 456 7890 + - * : = $ % ( )"
70 "ThE QuicK BrowN FoX JumpS OveR ThE LazY DoG 123 456 7890 + - * : = $ % ( )"
71*/
72
73enum
74{
75 BERT_PATTERN_ZEROS = 0,
76 BERT_PATTERN_ONES,
77 BERT_PATTERN_7_TO_1,
78 BERT_PATTERN_3_TO_1,
79 BERT_PATTERN_1_TO_1,
80 BERT_PATTERN_1_TO_3,
81 BERT_PATTERN_1_TO_7,
82 BERT_PATTERN_QBF,
83 BERT_PATTERN_ITU_O151_23,
84 BERT_PATTERN_ITU_O151_20,
85 BERT_PATTERN_ITU_O151_15,
86 BERT_PATTERN_ITU_O152_11,
87 BERT_PATTERN_ITU_O153_9
88};
89
90/*!
91 Bit error rate tester (BERT) results descriptor. This is used to report the
92 results of a BER test.
93*/
94 typedef struct
95{
96 int total_bits;
97 int bad_bits;
98 int resyncs;
99} bert_results_t;
100
101typedef void (*bert_report_func_t)(void *user_data, int reason, bert_results_t *bert_results);
102
103/*!
104 Bit error rate tester (BERT) descriptor. This defines the working state for a
105 single instance of the BERT.
106*/
107typedef struct bert_state_s bert_state_t;
108
109#if defined(__cplusplus)
110extern "C"
111{
112#endif
113
114/*! Return a short description of a BERT event.
115 \param event The event type.
116 \return A pointer to a short text string describing the event. */
117SPAN_DECLARE(const char *) bert_event_to_str(int event);
118
119/*! Initialise a BERT context.
120 \param s The BERT context.
121 \param limit The maximum test duration.
122 \param pattern One of the supported BERT signal patterns.
123 \param resync_len ???
124 \param resync_percent The percentage of bad bits which will cause a resync.
125 \return The BERT context. */
126SPAN_DECLARE(bert_state_t *) bert_init(bert_state_t *s, int limit, int pattern, int resync_len, int resync_percent);
127
128SPAN_DECLARE(int) bert_release(bert_state_t *s);
129
130SPAN_DECLARE(int) bert_free(bert_state_t *s);
131
132/*! Get the next bit of the BERT sequence from the generator.
133 \param s The BERT context.
134 \return The bit. */
135SPAN_DECLARE(int) bert_get_bit(bert_state_t *s);
136
137/*! Put the next bit of the BERT sequence to the analyser.
138 \param s The BERT context.
139 \param bit The bit. */
140SPAN_DECLARE(void) bert_put_bit(bert_state_t *s, int bit);
141
142/*! Set the callback function for reporting the test status.
143 \param s The BERT context.
144 \param freq The required frequency of regular reports.
145 \param reporter The callback function.
146 \param user_data An opaque pointer passed to the reporter routine. */
147SPAN_DECLARE(void) bert_set_report(bert_state_t *s, int freq, bert_report_func_t reporter, void *user_data);
148
149/*! Get the results of the BERT.
150 \param s The BERT context.
151 \param results The results.
152 \return The size of the result structure. */
153SPAN_DECLARE(int) bert_result(bert_state_t *s, bert_results_t *results);
154
155#if defined(__cplusplus)
156}
157#endif
158
159#endif
160/*- End of file ------------------------------------------------------------*/
bert_results_t
Definition bert.h:95
bert_state_s
Definition private/bert.h:61