1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3.. _frontend-stat-properties:
4
5******************************
6Frontend statistics indicators
7******************************
8
9The values are returned via ``dtv_property.stat``. If the property is
10supported, ``dtv_property.stat.len`` is bigger than zero.
11
12For most delivery systems, ``dtv_property.stat.len`` will be 1 if the
13stats is supported, and the properties will return a single value for
14each parameter.
15
16It should be noted, however, that new OFDM delivery systems like ISDB
17can use different modulation types for each group of carriers. On such
18standards, up to 3 groups of statistics can be provided, and
19``dtv_property.stat.len`` is updated to reflect the "global" metrics,
20plus one metric per each carrier group (called "layer" on ISDB).
21
22So, in order to be consistent with other delivery systems, the first
23value at :c:type:`dtv_property.stat.dtv_stats <dtv_stats>` array refers
24to the global metric. The other elements of the array represent each
25layer, starting from layer A(index 1), layer B (index 2) and so on.
26
27The number of filled elements are stored at ``dtv_property.stat.len``.
28
29Each element of the ``dtv_property.stat.dtv_stats`` array consists on
30two elements:
31
32-  ``svalue`` or ``uvalue``, where ``svalue`` is for signed values of
33   the measure (dB measures) and ``uvalue`` is for unsigned values
34   (counters, relative scale)
35
36-  ``scale`` - Scale for the value. It can be:
37
38   -  ``FE_SCALE_NOT_AVAILABLE`` - The parameter is supported by the
39      frontend, but it was not possible to collect it (could be a
40      transitory or permanent condition)
41
42   -  ``FE_SCALE_DECIBEL`` - parameter is a signed value, measured in
43      1/1000 dB
44
45   -  ``FE_SCALE_RELATIVE`` - parameter is a unsigned value, where 0
46      means 0% and 65535 means 100%.
47
48   -  ``FE_SCALE_COUNTER`` - parameter is a unsigned value that counts
49      the occurrence of an event, like bit error, block error, or lapsed
50      time.
51
52
53.. _DTV-STAT-SIGNAL-STRENGTH:
54
55DTV_STAT_SIGNAL_STRENGTH
56========================
57
58Indicates the signal strength level at the analog part of the tuner or
59of the demod.
60
61Possible scales for this metric are:
62
63-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
64   measurement was not complete yet.
65
66-  ``FE_SCALE_DECIBEL`` - signal strength is in 0.001 dBm units, power
67   measured in miliwatts. This value is generally negative.
68
69-  ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100%
70   measurement for power (actually, 0 to 65535).
71
72
73.. _DTV-STAT-CNR:
74
75DTV_STAT_CNR
76============
77
78Indicates the Signal to Noise ratio for the main carrier.
79
80Possible scales for this metric are:
81
82-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
83   measurement was not complete yet.
84
85-  ``FE_SCALE_DECIBEL`` - Signal/Noise ratio is in 0.001 dB units.
86
87-  ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100%
88   measurement for Signal/Noise (actually, 0 to 65535).
89
90
91.. _DTV-STAT-PRE-ERROR-BIT-COUNT:
92
93DTV_STAT_PRE_ERROR_BIT_COUNT
94============================
95
96Measures the number of bit errors before the forward error correction
97(FEC) on the inner coding block (before Viterbi, LDPC or other inner
98code).
99
100This measure is taken during the same interval as
101``DTV_STAT_PRE_TOTAL_BIT_COUNT``.
102
103In order to get the BER (Bit Error Rate) measurement, it should be
104divided by
105:ref:`DTV_STAT_PRE_TOTAL_BIT_COUNT <DTV-STAT-PRE-TOTAL-BIT-COUNT>`.
106
107This measurement is monotonically increased, as the frontend gets more
108bit count measurements. The frontend may reset it when a
109channel/transponder is tuned.
110
111Possible scales for this metric are:
112
113-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
114   measurement was not complete yet.
115
116-  ``FE_SCALE_COUNTER`` - Number of error bits counted before the inner
117   coding.
118
119
120.. _DTV-STAT-PRE-TOTAL-BIT-COUNT:
121
122DTV_STAT_PRE_TOTAL_BIT_COUNT
123============================
124
125Measures the amount of bits received before the inner code block, during
126the same period as
127:ref:`DTV_STAT_PRE_ERROR_BIT_COUNT <DTV-STAT-PRE-ERROR-BIT-COUNT>`
128measurement was taken.
129
130It should be noted that this measurement can be smaller than the total
131amount of bits on the transport stream, as the frontend may need to
132manually restart the measurement, losing some data between each
133measurement interval.
134
135This measurement is monotonically increased, as the frontend gets more
136bit count measurements. The frontend may reset it when a
137channel/transponder is tuned.
138
139Possible scales for this metric are:
140
141-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
142   measurement was not complete yet.
143
144-  ``FE_SCALE_COUNTER`` - Number of bits counted while measuring
145   :ref:`DTV_STAT_PRE_ERROR_BIT_COUNT <DTV-STAT-PRE-ERROR-BIT-COUNT>`.
146
147
148.. _DTV-STAT-POST-ERROR-BIT-COUNT:
149
150DTV_STAT_POST_ERROR_BIT_COUNT
151=============================
152
153Measures the number of bit errors after the forward error correction
154(FEC) done by inner code block (after Viterbi, LDPC or other inner
155code).
156
157This measure is taken during the same interval as
158``DTV_STAT_POST_TOTAL_BIT_COUNT``.
159
160In order to get the BER (Bit Error Rate) measurement, it should be
161divided by
162:ref:`DTV_STAT_POST_TOTAL_BIT_COUNT <DTV-STAT-POST-TOTAL-BIT-COUNT>`.
163
164This measurement is monotonically increased, as the frontend gets more
165bit count measurements. The frontend may reset it when a
166channel/transponder is tuned.
167
168Possible scales for this metric are:
169
170-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
171   measurement was not complete yet.
172
173-  ``FE_SCALE_COUNTER`` - Number of error bits counted after the inner
174   coding.
175
176
177.. _DTV-STAT-POST-TOTAL-BIT-COUNT:
178
179DTV_STAT_POST_TOTAL_BIT_COUNT
180=============================
181
182Measures the amount of bits received after the inner coding, during the
183same period as
184:ref:`DTV_STAT_POST_ERROR_BIT_COUNT <DTV-STAT-POST-ERROR-BIT-COUNT>`
185measurement was taken.
186
187It should be noted that this measurement can be smaller than the total
188amount of bits on the transport stream, as the frontend may need to
189manually restart the measurement, losing some data between each
190measurement interval.
191
192This measurement is monotonically increased, as the frontend gets more
193bit count measurements. The frontend may reset it when a
194channel/transponder is tuned.
195
196Possible scales for this metric are:
197
198-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
199   measurement was not complete yet.
200
201-  ``FE_SCALE_COUNTER`` - Number of bits counted while measuring
202   :ref:`DTV_STAT_POST_ERROR_BIT_COUNT <DTV-STAT-POST-ERROR-BIT-COUNT>`.
203
204
205.. _DTV-STAT-ERROR-BLOCK-COUNT:
206
207DTV_STAT_ERROR_BLOCK_COUNT
208==========================
209
210Measures the number of block errors after the outer forward error
211correction coding (after Reed-Solomon or other outer code).
212
213This measurement is monotonically increased, as the frontend gets more
214bit count measurements. The frontend may reset it when a
215channel/transponder is tuned.
216
217Possible scales for this metric are:
218
219-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
220   measurement was not complete yet.
221
222-  ``FE_SCALE_COUNTER`` - Number of error blocks counted after the outer
223   coding.
224
225
226.. _DTV-STAT-TOTAL-BLOCK-COUNT:
227
228DTV-STAT_TOTAL_BLOCK_COUNT
229==========================
230
231Measures the total number of blocks received during the same period as
232:ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>`
233measurement was taken.
234
235It can be used to calculate the PER indicator, by dividing
236:ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>` by
237:ref:`DTV-STAT-TOTAL-BLOCK-COUNT`.
238
239Possible scales for this metric are:
240
241-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
242   measurement was not complete yet.
243
244-  ``FE_SCALE_COUNTER`` - Number of blocks counted while measuring
245   :ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>`.
246