summaryrefslogtreecommitdiff
path: root/Documentation/media/uapi/dvb/frontend-stat-properties.rst
blob: 546464db04b58ae50d0f02ba231771a24034ff22 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
.. Permission is granted to copy, distribute and/or modify this
.. document under the terms of the GNU Free Documentation License,
.. Version 1.1 or any later version published by the Free Software
.. Foundation, with no Invariant Sections, no Front-Cover Texts
.. and no Back-Cover Texts. A copy of the license is included at
.. Documentation/media/uapi/fdl-appendix.rst.
..
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections

.. _frontend-stat-properties:

******************************
Frontend statistics indicators
******************************

The values are returned via ``dtv_property.stat``. If the property is
supported, ``dtv_property.stat.len`` is bigger than zero.

For most delivery systems, ``dtv_property.stat.len`` will be 1 if the
stats is supported, and the properties will return a single value for
each parameter.

It should be noted, however, that new OFDM delivery systems like ISDB
can use different modulation types for each group of carriers. On such
standards, up to 3 groups of statistics can be provided, and
``dtv_property.stat.len`` is updated to reflect the "global" metrics,
plus one metric per each carrier group (called "layer" on ISDB).

So, in order to be consistent with other delivery systems, the first
value at :c:type:`dtv_property.stat.dtv_stats <dtv_stats>` array refers
to the global metric. The other elements of the array represent each
layer, starting from layer A(index 1), layer B (index 2) and so on.

The number of filled elements are stored at ``dtv_property.stat.len``.

Each element of the ``dtv_property.stat.dtv_stats`` array consists on
two elements:

-  ``svalue`` or ``uvalue``, where ``svalue`` is for signed values of
   the measure (dB measures) and ``uvalue`` is for unsigned values
   (counters, relative scale)

-  ``scale`` - Scale for the value. It can be:

   -  ``FE_SCALE_NOT_AVAILABLE`` - The parameter is supported by the
      frontend, but it was not possible to collect it (could be a
      transitory or permanent condition)

   -  ``FE_SCALE_DECIBEL`` - parameter is a signed value, measured in
      1/1000 dB

   -  ``FE_SCALE_RELATIVE`` - parameter is a unsigned value, where 0
      means 0% and 65535 means 100%.

   -  ``FE_SCALE_COUNTER`` - parameter is a unsigned value that counts
      the occurrence of an event, like bit error, block error, or lapsed
      time.


.. _DTV-STAT-SIGNAL-STRENGTH:

DTV_STAT_SIGNAL_STRENGTH
========================

Indicates the signal strength level at the analog part of the tuner or
of the demod.

Possible scales for this metric are:

-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
   measurement was not complete yet.

-  ``FE_SCALE_DECIBEL`` - signal strength is in 0.001 dBm units, power
   measured in miliwatts. This value is generally negative.

-  ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100%
   measurement for power (actually, 0 to 65535).


.. _DTV-STAT-CNR:

DTV_STAT_CNR
============

Indicates the Signal to Noise ratio for the main carrier.

Possible scales for this metric are:

-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
   measurement was not complete yet.

-  ``FE_SCALE_DECIBEL`` - Signal/Noise ratio is in 0.001 dB units.

-  ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100%
   measurement for Signal/Noise (actually, 0 to 65535).


.. _DTV-STAT-PRE-ERROR-BIT-COUNT:

DTV_STAT_PRE_ERROR_BIT_COUNT
============================

Measures the number of bit errors before the forward error correction
(FEC) on the inner coding block (before Viterbi, LDPC or other inner
code).

This measure is taken during the same interval as
``DTV_STAT_PRE_TOTAL_BIT_COUNT``.

In order to get the BER (Bit Error Rate) measurement, it should be
divided by
:ref:`DTV_STAT_PRE_TOTAL_BIT_COUNT <DTV-STAT-PRE-TOTAL-BIT-COUNT>`.

This measurement is monotonically increased, as the frontend gets more
bit count measurements. The frontend may reset it when a
channel/transponder is tuned.

Possible scales for this metric are:

-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
   measurement was not complete yet.

-  ``FE_SCALE_COUNTER`` - Number of error bits counted before the inner
   coding.


.. _DTV-STAT-PRE-TOTAL-BIT-COUNT:

DTV_STAT_PRE_TOTAL_BIT_COUNT
============================

Measures the amount of bits received before the inner code block, during
the same period as
:ref:`DTV_STAT_PRE_ERROR_BIT_COUNT <DTV-STAT-PRE-ERROR-BIT-COUNT>`
measurement was taken.

It should be noted that this measurement can be smaller than the total
amount of bits on the transport stream, as the frontend may need to
manually restart the measurement, losing some data between each
measurement interval.

This measurement is monotonically increased, as the frontend gets more
bit count measurements. The frontend may reset it when a
channel/transponder is tuned.

Possible scales for this metric are:

-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
   measurement was not complete yet.

-  ``FE_SCALE_COUNTER`` - Number of bits counted while measuring
   :ref:`DTV_STAT_PRE_ERROR_BIT_COUNT <DTV-STAT-PRE-ERROR-BIT-COUNT>`.


.. _DTV-STAT-POST-ERROR-BIT-COUNT:

DTV_STAT_POST_ERROR_BIT_COUNT
=============================

Measures the number of bit errors after the forward error correction
(FEC) done by inner code block (after Viterbi, LDPC or other inner
code).

This measure is taken during the same interval as
``DTV_STAT_POST_TOTAL_BIT_COUNT``.

In order to get the BER (Bit Error Rate) measurement, it should be
divided by
:ref:`DTV_STAT_POST_TOTAL_BIT_COUNT <DTV-STAT-POST-TOTAL-BIT-COUNT>`.

This measurement is monotonically increased, as the frontend gets more
bit count measurements. The frontend may reset it when a
channel/transponder is tuned.

Possible scales for this metric are:

-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
   measurement was not complete yet.

-  ``FE_SCALE_COUNTER`` - Number of error bits counted after the inner
   coding.


.. _DTV-STAT-POST-TOTAL-BIT-COUNT:

DTV_STAT_POST_TOTAL_BIT_COUNT
=============================

Measures the amount of bits received after the inner coding, during the
same period as
:ref:`DTV_STAT_POST_ERROR_BIT_COUNT <DTV-STAT-POST-ERROR-BIT-COUNT>`
measurement was taken.

It should be noted that this measurement can be smaller than the total
amount of bits on the transport stream, as the frontend may need to
manually restart the measurement, losing some data between each
measurement interval.

This measurement is monotonically increased, as the frontend gets more
bit count measurements. The frontend may reset it when a
channel/transponder is tuned.

Possible scales for this metric are:

-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
   measurement was not complete yet.

-  ``FE_SCALE_COUNTER`` - Number of bits counted while measuring
   :ref:`DTV_STAT_POST_ERROR_BIT_COUNT <DTV-STAT-POST-ERROR-BIT-COUNT>`.


.. _DTV-STAT-ERROR-BLOCK-COUNT:

DTV_STAT_ERROR_BLOCK_COUNT
==========================

Measures the number of block errors after the outer forward error
correction coding (after Reed-Solomon or other outer code).

This measurement is monotonically increased, as the frontend gets more
bit count measurements. The frontend may reset it when a
channel/transponder is tuned.

Possible scales for this metric are:

-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
   measurement was not complete yet.

-  ``FE_SCALE_COUNTER`` - Number of error blocks counted after the outer
   coding.


.. _DTV-STAT-TOTAL-BLOCK-COUNT:

DTV-STAT_TOTAL_BLOCK_COUNT
==========================

Measures the total number of blocks received during the same period as
:ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>`
measurement was taken.

It can be used to calculate the PER indicator, by dividing
:ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>` by
:ref:`DTV-STAT-TOTAL-BLOCK-COUNT`.

Possible scales for this metric are:

-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
   measurement was not complete yet.

-  ``FE_SCALE_COUNTER`` - Number of blocks counted while measuring
   :ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>`.