Documentation/media/uapi/dvb/frontend-stat-properties.rst

   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/media/uapi/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 ******************************
  13 Frontend statistics indicators
  14 ******************************
  15
  16 The values are returned via ``dtv_property.stat``. If the property is
  17 supported, ``dtv_property.stat.len`` is bigger than zero.
  18
  19 For most delivery systems, ``dtv_property.stat.len`` will be 1 if the
  20 stats is supported, and the properties will return a single value for
  21 each parameter.
  22
  23 It should be noted, however, that new OFDM delivery systems like ISDB
  24 can use different modulation types for each group of carriers. On such
  25 standards, up to 3 groups of statistics can be provided, and
  26 ``dtv_property.stat.len`` is updated to reflect the "global" metrics,
  27 plus one metric per each carrier group (called "layer" on ISDB).
  28
  29 So, in order to be consistent with other delivery systems, the first
  30 value at :c:type:`dtv_property.stat.dtv_stats <dtv_stats>` array refers
  31 to the global metric. The other elements of the array represent each
  32 layer, starting from layer A(index 1), layer B (index 2) and so on.
  33
  34 The number of filled elements are stored at ``dtv_property.stat.len``.
  35
  36 Each element of the ``dtv_property.stat.dtv_stats`` array consists on
  37 two 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
  62 DTV_STAT_SIGNAL_STRENGTH
  63 ========================
  64
  65 Indicates the signal strength level at the analog part of the tuner or
  66 of the demod.
  67
  68 Possible 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
  82 DTV_STAT_CNR
  83 ============
  84
  85 Indicates the Signal to Noise ratio for the main carrier.
  86
  87 Possible 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
 100 DTV_STAT_PRE_ERROR_BIT_COUNT
 101 ============================
 102
 103 Measures the number of bit errors before the forward error correction
 104 (FEC) on the inner coding block (before Viterbi, LDPC or other inner
 105 code).
 106
 107 This measure is taken during the same interval as
 108 ``DTV_STAT_PRE_TOTAL_BIT_COUNT``.
 109
 110 In order to get the BER (Bit Error Rate) measurement, it should be
 111 divided by
 112 :ref:`DTV_STAT_PRE_TOTAL_BIT_COUNT <DTV-STAT-PRE-TOTAL-BIT-COUNT>`.
 113
 114 This measurement is monotonically increased, as the frontend gets more
 115 bit count measurements. The frontend may reset it when a
 116 channel/transponder is tuned.
 117
 118 Possible 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
 129 DTV_STAT_PRE_TOTAL_BIT_COUNT
 130 ============================
 131
 132 Measures the amount of bits received before the inner code block, during
 133 the same period as
 134 :ref:`DTV_STAT_PRE_ERROR_BIT_COUNT <DTV-STAT-PRE-ERROR-BIT-COUNT>`
 135 measurement was taken.
 136
 137 It should be noted that this measurement can be smaller than the total
 138 amount of bits on the transport stream, as the frontend may need to
 139 manually restart the measurement, losing some data between each
 140 measurement interval.
 141
 142 This measurement is monotonically increased, as the frontend gets more
 143 bit count measurements. The frontend may reset it when a
 144 channel/transponder is tuned.
 145
 146 Possible 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
 157 DTV_STAT_POST_ERROR_BIT_COUNT
 158 =============================
 159
 160 Measures the number of bit errors after the forward error correction
 161 (FEC) done by inner code block (after Viterbi, LDPC or other inner
 162 code).
 163
 164 This measure is taken during the same interval as
 165 ``DTV_STAT_POST_TOTAL_BIT_COUNT``.
 166
 167 In order to get the BER (Bit Error Rate) measurement, it should be
 168 divided by
 169 :ref:`DTV_STAT_POST_TOTAL_BIT_COUNT <DTV-STAT-POST-TOTAL-BIT-COUNT>`.
 170
 171 This measurement is monotonically increased, as the frontend gets more
 172 bit count measurements. The frontend may reset it when a
 173 channel/transponder is tuned.
 174
 175 Possible 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
 186 DTV_STAT_POST_TOTAL_BIT_COUNT
 187 =============================
 188
 189 Measures the amount of bits received after the inner coding, during the
 190 same period as
 191 :ref:`DTV_STAT_POST_ERROR_BIT_COUNT <DTV-STAT-POST-ERROR-BIT-COUNT>`
 192 measurement was taken.
 193
 194 It should be noted that this measurement can be smaller than the total
 195 amount of bits on the transport stream, as the frontend may need to
 196 manually restart the measurement, losing some data between each
 197 measurement interval.
 198
 199 This measurement is monotonically increased, as the frontend gets more
 200 bit count measurements. The frontend may reset it when a
 201 channel/transponder is tuned.
 202
 203 Possible 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
 214 DTV_STAT_ERROR_BLOCK_COUNT
 215 ==========================
 216
 217 Measures the number of block errors after the outer forward error
 218 correction coding (after Reed-Solomon or other outer code).
 219
 220 This measurement is monotonically increased, as the frontend gets more
 221 bit count measurements. The frontend may reset it when a
 222 channel/transponder is tuned.
 223
 224 Possible 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
 235 DTV-STAT_TOTAL_BLOCK_COUNT
 236 ==========================
 237
 238 Measures the total number of blocks received during the same period as
 239 :ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>`
 240 measurement was taken.
 241
 242 It 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
 246 Possible 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>`.