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

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _frontend-stat-properties:
   4
   5 ******************************
   6 Frontend statistics indicators
   7 ******************************
   8
   9 The values are returned via ``dtv_property.stat``. If the property is
  10 supported, ``dtv_property.stat.len`` is bigger than zero.
  11
  12 For most delivery systems, ``dtv_property.stat.len`` will be 1 if the
  13 stats is supported, and the properties will return a single value for
  14 each parameter.
  15
  16 It should be noted, however, that new OFDM delivery systems like ISDB
  17 can use different modulation types for each group of carriers. On such
  18 standards, up to 3 groups of statistics can be provided, and
  19 ``dtv_property.stat.len`` is updated to reflect the "global" metrics,
  20 plus one metric per each carrier group (called "layer" on ISDB).
  21
  22 So, in order to be consistent with other delivery systems, the first
  23 value at :c:type:`dtv_property.stat.dtv_stats <dtv_stats>` array refers
  24 to the global metric. The other elements of the array represent each
  25 layer, starting from layer A(index 1), layer B (index 2) and so on.
  26
  27 The number of filled elements are stored at ``dtv_property.stat.len``.
  28
  29 Each element of the ``dtv_property.stat.dtv_stats`` array consists on
  30 two 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
  55 DTV_STAT_SIGNAL_STRENGTH
  56 ========================
  57
  58 Indicates the signal strength level at the analog part of the tuner or
  59 of the demod.
  60
  61 Possible 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
  75 DTV_STAT_CNR
  76 ============
  77
  78 Indicates the Signal to Noise ratio for the main carrier.
  79
  80 Possible 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
  93 DTV_STAT_PRE_ERROR_BIT_COUNT
  94 ============================
  95
  96 Measures the number of bit errors before the forward error correction
  97 (FEC) on the inner coding block (before Viterbi, LDPC or other inner
  98 code).
  99
 100 This measure is taken during the same interval as
 101 ``DTV_STAT_PRE_TOTAL_BIT_COUNT``.
 102
 103 In order to get the BER (Bit Error Rate) measurement, it should be
 104 divided by
 105 :ref:`DTV_STAT_PRE_TOTAL_BIT_COUNT <DTV-STAT-PRE-TOTAL-BIT-COUNT>`.
 106
 107 This measurement is monotonically increased, as the frontend gets more
 108 bit count measurements. The frontend may reset it when a
 109 channel/transponder is tuned.
 110
 111 Possible 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
 122 DTV_STAT_PRE_TOTAL_BIT_COUNT
 123 ============================
 124
 125 Measures the amount of bits received before the inner code block, during
 126 the same period as
 127 :ref:`DTV_STAT_PRE_ERROR_BIT_COUNT <DTV-STAT-PRE-ERROR-BIT-COUNT>`
 128 measurement was taken.
 129
 130 It should be noted that this measurement can be smaller than the total
 131 amount of bits on the transport stream, as the frontend may need to
 132 manually restart the measurement, losing some data between each
 133 measurement interval.
 134
 135 This measurement is monotonically increased, as the frontend gets more
 136 bit count measurements. The frontend may reset it when a
 137 channel/transponder is tuned.
 138
 139 Possible 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
 150 DTV_STAT_POST_ERROR_BIT_COUNT
 151 =============================
 152
 153 Measures the number of bit errors after the forward error correction
 154 (FEC) done by inner code block (after Viterbi, LDPC or other inner
 155 code).
 156
 157 This measure is taken during the same interval as
 158 ``DTV_STAT_POST_TOTAL_BIT_COUNT``.
 159
 160 In order to get the BER (Bit Error Rate) measurement, it should be
 161 divided by
 162 :ref:`DTV_STAT_POST_TOTAL_BIT_COUNT <DTV-STAT-POST-TOTAL-BIT-COUNT>`.
 163
 164 This measurement is monotonically increased, as the frontend gets more
 165 bit count measurements. The frontend may reset it when a
 166 channel/transponder is tuned.
 167
 168 Possible 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
 179 DTV_STAT_POST_TOTAL_BIT_COUNT
 180 =============================
 181
 182 Measures the amount of bits received after the inner coding, during the
 183 same period as
 184 :ref:`DTV_STAT_POST_ERROR_BIT_COUNT <DTV-STAT-POST-ERROR-BIT-COUNT>`
 185 measurement was taken.
 186
 187 It should be noted that this measurement can be smaller than the total
 188 amount of bits on the transport stream, as the frontend may need to
 189 manually restart the measurement, losing some data between each
 190 measurement interval.
 191
 192 This measurement is monotonically increased, as the frontend gets more
 193 bit count measurements. The frontend may reset it when a
 194 channel/transponder is tuned.
 195
 196 Possible 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
 207 DTV_STAT_ERROR_BLOCK_COUNT
 208 ==========================
 209
 210 Measures the number of block errors after the outer forward error
 211 correction coding (after Reed-Solomon or other outer code).
 212
 213 This measurement is monotonically increased, as the frontend gets more
 214 bit count measurements. The frontend may reset it when a
 215 channel/transponder is tuned.
 216
 217 Possible 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
 228 DTV-STAT_TOTAL_BLOCK_COUNT
 229 ==========================
 230
 231 Measures the total number of blocks received during the same period as
 232 :ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>`
 233 measurement was taken.
 234
 235 It 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
 239 Possible 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>`.