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