Documentation/media/kapi/dtv-frontend.rst

   1 Digital TV Frontend kABI
   2 ------------------------
   3
   4 Digital TV Frontend
   5 ~~~~~~~~~~~~~~~~~~~
   6
   7 The Digital TV Frontend kABI defines a driver-internal interface for
   8 registering low-level, hardware specific driver to a hardware independent
   9 frontend layer. It is only of interest for Digital TV device driver writers.
  10 The header file for this API is named ``dvb_frontend.h`` and located in
  11 ``include/media/``.
  12
  13 Demodulator driver
  14 ^^^^^^^^^^^^^^^^^^
  15
  16 The demodulator driver is responsible to talk with the decoding part of the
  17 hardware. Such driver should implement :c:type:`dvb_frontend_ops`, with
  18 tells what type of digital TV standards are supported, and points to a
  19 series of functions that allow the DVB core to command the hardware via
  20 the code under ``include/media/dvb_frontend.c``.
  21
  22 A typical example of such struct in a driver ``foo`` is::
  23
  24         static struct dvb_frontend_ops foo_ops = {
  25                 .delsys = { SYS_DVBT, SYS_DVBT2, SYS_DVBC_ANNEX_A },
  26                 .info = {
  27                         .name   = "foo DVB-T/T2/C driver",
  28                         .caps = FE_CAN_FEC_1_2 |
  29                                 FE_CAN_FEC_2_3 |
  30                                 FE_CAN_FEC_3_4 |
  31                                 FE_CAN_FEC_5_6 |
  32                                 FE_CAN_FEC_7_8 |
  33                                 FE_CAN_FEC_AUTO |
  34                                 FE_CAN_QPSK |
  35                                 FE_CAN_QAM_16 |
  36                                 FE_CAN_QAM_32 |
  37                                 FE_CAN_QAM_64 |
  38                                 FE_CAN_QAM_128 |
  39                                 FE_CAN_QAM_256 |
  40                                 FE_CAN_QAM_AUTO |
  41                                 FE_CAN_TRANSMISSION_MODE_AUTO |
  42                                 FE_CAN_GUARD_INTERVAL_AUTO |
  43                                 FE_CAN_HIERARCHY_AUTO |
  44                                 FE_CAN_MUTE_TS |
  45                                 FE_CAN_2G_MODULATION,
  46                         .frequency_min = 42000000, /* Hz */
  47                         .frequency_max = 1002000000, /* Hz */
  48                         .symbol_rate_min = 870000,
  49                         .symbol_rate_max = 11700000
  50                 },
  51                 .init = foo_init,
  52                 .sleep = foo_sleep,
  53                 .release = foo_release,
  54                 .set_frontend = foo_set_frontend,
  55                 .get_frontend = foo_get_frontend,
  56                 .read_status = foo_get_status_and_stats,
  57                 .tune = foo_tune,
  58                 .i2c_gate_ctrl = foo_i2c_gate_ctrl,
  59                 .get_frontend_algo = foo_get_algo,
  60         };
  61
  62 A typical example of such struct in a driver ``bar`` meant to be used on
  63 Satellite TV reception is::
  64
  65         static const struct dvb_frontend_ops bar_ops = {
  66                 .delsys = { SYS_DVBS, SYS_DVBS2 },
  67                 .info = {
  68                         .name           = "Bar DVB-S/S2 demodulator",
  69                         .frequency_min  = 500000, /* KHz */
  70                         .frequency_max  = 2500000, /* KHz */
  71                         .frequency_stepsize     = 0,
  72                         .symbol_rate_min = 1000000,
  73                         .symbol_rate_max = 45000000,
  74                         .symbol_rate_tolerance = 500,
  75                         .caps = FE_CAN_INVERSION_AUTO |
  76                                 FE_CAN_FEC_AUTO |
  77                                 FE_CAN_QPSK,
  78                 },
  79                 .init = bar_init,
  80                 .sleep = bar_sleep,
  81                 .release = bar_release,
  82                 .set_frontend = bar_set_frontend,
  83                 .get_frontend = bar_get_frontend,
  84                 .read_status = bar_get_status_and_stats,
  85                 .i2c_gate_ctrl = bar_i2c_gate_ctrl,
  86                 .get_frontend_algo = bar_get_algo,
  87                 .tune = bar_tune,
  88
  89                 /* Satellite-specific */
  90                 .diseqc_send_master_cmd = bar_send_diseqc_msg,
  91                 .diseqc_send_burst = bar_send_burst,
  92                 .set_tone = bar_set_tone,
  93                 .set_voltage = bar_set_voltage,
  94         };
  95
  96 .. note::
  97
  98    #) For satellite digital TV standards (DVB-S, DVB-S2, ISDB-S), the
  99       frequencies are specified in kHz, while, for terrestrial and cable
 100       standards, they're specified in Hz. Due to that, if the same frontend
 101       supports both types, you'll need to have two separate
 102       :c:type:`dvb_frontend_ops` structures, one for each standard.
 103    #) The ``.i2c_gate_ctrl`` field is present only when the hardware has
 104       allows controlling an I2C gate (either directly of via some GPIO pin),
 105       in order to remove the tuner from the I2C bus after a channel is
 106       tuned.
 107    #) All new drivers should implement the
 108       :ref:`DVBv5 statistics <dvbv5_stats>` via ``.read_status``.
 109       Yet, there are a number of callbacks meant to get statistics for
 110       signal strength, S/N and UCB. Those are there to provide backward
 111       compatibility with legacy applications that don't support the DVBv5
 112       API. Implementing those callbacks are optional. Those callbacks may be
 113       removed in the future, after we have all existing drivers supporting
 114       DVBv5 stats.
 115    #) Other callbacks are required for satellite TV standards, in order to
 116       control LNBf and DiSEqC: ``.diseqc_send_master_cmd``,
 117       ``.diseqc_send_burst``, ``.set_tone``, ``.set_voltage``.
 118
 119 .. |delta|   unicode:: U+00394
 120
 121 The ``include/media/dvb_frontend.c`` has a kernel thread with is
 122 responsible for tuning the device. It supports multiple algorithms to
 123 detect a channel, as defined at enum :c:func:`dvbfe_algo`.
 124
 125 The algorithm to be used is obtained via ``.get_frontend_algo``. If the driver
 126 doesn't fill its field at struct :c:type:`dvb_frontend_ops`, it will default to
 127 ``DVBFE_ALGO_SW``, meaning that the dvb-core will do a zigzag when tuning,
 128 e. g. it will try first to use the specified center frequency ``f``,
 129 then, it will do ``f`` + |delta|, ``f`` - |delta|, ``f`` + 2 x |delta|,
 130 ``f`` - 2 x |delta| and so on.
 131
 132 If the hardware has internally a some sort of zigzag algorithm, you should
 133 define a ``.get_frontend_algo`` function that would return ``DVBFE_ALGO_HW``.
 134
 135 .. note::
 136
 137    The core frontend support also supports
 138    a third type (``DVBFE_ALGO_CUSTOM``), in order to allow the driver to
 139    define its own hardware-assisted algorithm. Very few hardware need to
 140    use it nowadays. Using ``DVBFE_ALGO_CUSTOM`` require to provide other
 141    function callbacks at struct :c:type:`dvb_frontend_ops`.
 142
 143 Attaching frontend driver to the bridge driver
 144 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 145
 146 Before using the Digital TV frontend core, the bridge driver should attach
 147 the frontend demod, tuner and SEC devices and call
 148 :c:func:`dvb_register_frontend()`,
 149 in order to register the new frontend at the subsystem. At device
 150 detach/removal, the bridge driver should call
 151 :c:func:`dvb_unregister_frontend()` to
 152 remove the frontend from the core and then :c:func:`dvb_frontend_detach()`
 153 to free the memory allocated by the frontend drivers.
 154
 155 The drivers should also call :c:func:`dvb_frontend_suspend()` as part of
 156 their handler for the :c:type:`device_driver`.\ ``suspend()``, and
 157 :c:func:`dvb_frontend_resume()` as
 158 part of their handler for :c:type:`device_driver`.\ ``resume()``.
 159
 160 A few other optional functions are provided to handle some special cases.
 161
 162 .. _dvbv5_stats:
 163
 164 Digital TV Frontend statistics
 165 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 166
 167 Introduction
 168 ^^^^^^^^^^^^
 169
 170 Digital TV frontends provide a range of
 171 :ref:`statistics <frontend-stat-properties>` meant to help tuning the device
 172 and measuring the quality of service.
 173
 174 For each statistics measurement, the driver should set the type of scale used,
 175 or ``FE_SCALE_NOT_AVAILABLE`` if the statistics is not available on a given
 176 time. Drivers should also provide the number of statistics for each type.
 177 that's usually 1 for most video standards [#f2]_.
 178
 179 Drivers should initialize each statistic counters with length and
 180 scale at its init code. For example, if the frontend provides signal
 181 strength, it should have, on its init code::
 182
 183         struct dtv_frontend_properties *c = &state->fe.dtv_property_cache;
 184
 185         c->strength.len = 1;
 186         c->strength.stat[0].scale = FE_SCALE_NOT_AVAILABLE;
 187
 188 And, when the statistics got updated, set the scale::
 189
 190         c->strength.stat[0].scale = FE_SCALE_DECIBEL;
 191         c->strength.stat[0].uvalue = strength;
 192
 193 .. [#f2] For ISDB-T, it may provide both a global statistics and a per-layer
 194    set of statistics. On such cases, len should be equal to 4. The first
 195    value corresponds to the global stat; the other ones to each layer, e. g.:
 196
 197    - c->cnr.stat[0] for global S/N carrier ratio,
 198    - c->cnr.stat[1] for Layer A S/N carrier ratio,
 199    - c->cnr.stat[2] for layer B S/N carrier ratio,
 200    - c->cnr.stat[3] for layer C S/N carrier ratio.
 201
 202 .. note:: Please prefer to use ``FE_SCALE_DECIBEL`` instead of
 203    ``FE_SCALE_RELATIVE`` for signal strength and CNR measurements.
 204
 205 Groups of statistics
 206 ^^^^^^^^^^^^^^^^^^^^
 207
 208 There are several groups of statistics currently supported:
 209
 210 Signal strength (:ref:`DTV-STAT-SIGNAL-STRENGTH`)
 211   - Measures the signal strength level at the analog part of the tuner or
 212     demod.
 213
 214   - Typically obtained from the gain applied to the tuner and/or frontend
 215     in order to detect the carrier. When no carrier is detected, the gain is
 216     at the maximum value (so, strength is on its minimal).
 217
 218   - As the gain is visible through the set of registers that adjust the gain,
 219     typically, this statistics is always available [#f3]_.
 220
 221   - Drivers should try to make it available all the times, as this statistics
 222     can be used when adjusting an antenna position and to check for troubles
 223     at the cabling.
 224
 225   .. [#f3] On a few devices, the gain keeps floating if no carrier.
 226      On such devices, strength report should check first if carrier is
 227      detected at the tuner (``FE_HAS_CARRIER``, see :c:type:`fe_status`),
 228      and otherwise return the lowest possible value.
 229
 230 Carrier Signal to Noise ratio (:ref:`DTV-STAT-CNR`)
 231   - Signal to Noise ratio for the main carrier.
 232
 233   - Signal to Noise measurement depends on the device. On some hardware, is
 234     available when the main carrier is detected. On those hardware, CNR
 235     measurement usually comes from the tuner (e. g. after ``FE_HAS_CARRIER``,
 236     see :c:type:`fe_status`).
 237
 238     On other devices, it requires inner FEC decoding,
 239     as the frontend measures it indirectly from other parameters (e. g. after
 240     ``FE_HAS_VITERBI``, see :c:type:`fe_status`).
 241
 242     Having it available after inner FEC is more common.
 243
 244 Bit counts post-FEC (:ref:`DTV-STAT-POST-ERROR-BIT-COUNT` and :ref:`DTV-STAT-POST-TOTAL-BIT-COUNT`)
 245   - Those counters measure the number of bits and bit errors errors after
 246     the forward error correction (FEC) on the inner coding block
 247     (after Viterbi, LDPC or other inner code).
 248
 249   - Due to its nature, those statistics depend on full coding lock
 250     (e. g. after ``FE_HAS_SYNC`` or after ``FE_HAS_LOCK``,
 251     see :c:type:`fe_status`).
 252
 253 Bit counts pre-FEC (:ref:`DTV-STAT-PRE-ERROR-BIT-COUNT` and :ref:`DTV-STAT-PRE-TOTAL-BIT-COUNT`)
 254   - Those counters measure the number of bits and bit errors errors before
 255     the forward error correction (FEC) on the inner coding block
 256     (before Viterbi, LDPC or other inner code).
 257
 258   - Not all frontends provide this kind of statistics.
 259
 260   - Due to its nature, those statistics depend on inner coding lock (e. g.
 261     after ``FE_HAS_VITERBI``, see :c:type:`fe_status`).
 262
 263 Block counts (:ref:`DTV-STAT-ERROR-BLOCK-COUNT` and :ref:`DTV-STAT-TOTAL-BLOCK-COUNT`)
 264   - Those counters measure the number of blocks and block errors errors after
 265     the forward error correction (FEC) on the inner coding block
 266     (before Viterbi, LDPC or other inner code).
 267
 268   - Due to its nature, those statistics depend on full coding lock
 269     (e. g. after ``FE_HAS_SYNC`` or after
 270     ``FE_HAS_LOCK``, see :c:type:`fe_status`).
 271
 272 .. note:: All counters should be monotonically increased as they're
 273    collected from the hardware.
 274
 275 A typical example of the logic that handle status and statistics is::
 276
 277         static int foo_get_status_and_stats(struct dvb_frontend *fe)
 278         {
 279                 struct foo_state *state = fe->demodulator_priv;
 280                 struct dtv_frontend_properties *c = &fe->dtv_property_cache;
 281
 282                 int rc;
 283                 enum fe_status *status;
 284
 285                 /* Both status and strength are always available */
 286                 rc = foo_read_status(fe, &status);
 287                 if (rc < 0)
 288                         return rc;
 289
 290                 rc = foo_read_strength(fe);
 291                 if (rc < 0)
 292                         return rc;
 293
 294                 /* Check if CNR is available */
 295                 if (!(fe->status & FE_HAS_CARRIER))
 296                         return 0;
 297
 298                 rc = foo_read_cnr(fe);
 299                 if (rc < 0)
 300                         return rc;
 301
 302                 /* Check if pre-BER stats are available */
 303                 if (!(fe->status & FE_HAS_VITERBI))
 304                         return 0;
 305
 306                 rc = foo_get_pre_ber(fe);
 307                 if (rc < 0)
 308                         return rc;
 309
 310                 /* Check if post-BER stats are available */
 311                 if (!(fe->status & FE_HAS_SYNC))
 312                         return 0;
 313
 314                 rc = foo_get_post_ber(fe);
 315                 if (rc < 0)
 316                         return rc;
 317         }
 318
 319         static const struct dvb_frontend_ops ops = {
 320                 /* ... */
 321                 .read_status = foo_get_status_and_stats,
 322         };
 323
 324 Statistics collect
 325 ^^^^^^^^^^^^^^^^^^
 326
 327 On almost all frontend hardware, the bit and byte counts are stored by
 328 the hardware after a certain amount of time or after the total bit/block
 329 counter reaches a certain value (usually programable), for example, on
 330 every 1000 ms or after receiving 1,000,000 bits.
 331
 332 So, if you read the registers too soon, you'll end by reading the same
 333 value as in the previous reading, causing the monotonic value to be
 334 incremented too often.
 335
 336 Drivers should take the responsibility to avoid too often reads. That
 337 can be done using two approaches:
 338
 339 if the driver have a bit that indicates when a collected data is ready
 340 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 341
 342 Driver should check such bit before making the statistics available.
 343
 344 An example of such behavior can be found at this code snippet (adapted
 345 from mb86a20s driver's logic)::
 346
 347         static int foo_get_pre_ber(struct dvb_frontend *fe)
 348         {
 349                 struct foo_state *state = fe->demodulator_priv;
 350                 struct dtv_frontend_properties *c = &fe->dtv_property_cache;
 351                 int rc, bit_error;
 352
 353                 /* Check if the BER measures are already available */
 354                 rc = foo_read_u8(state, 0x54);
 355                 if (rc < 0)
 356                         return rc;
 357
 358                 if (!rc)
 359                         return 0;
 360
 361                 /* Read Bit Error Count */
 362                 bit_error = foo_read_u32(state, 0x55);
 363                 if (bit_error < 0)
 364                         return bit_error;
 365
 366                 /* Read Total Bit Count */
 367                 rc = foo_read_u32(state, 0x51);
 368                 if (rc < 0)
 369                         return rc;
 370
 371                 c->pre_bit_error.stat[0].scale = FE_SCALE_COUNTER;
 372                 c->pre_bit_error.stat[0].uvalue += bit_error;
 373                 c->pre_bit_count.stat[0].scale = FE_SCALE_COUNTER;
 374                 c->pre_bit_count.stat[0].uvalue += rc;
 375
 376                 return 0;
 377         }
 378
 379 If the driver doesn't provide a statistics available check bit
 380 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 381
 382 A few devices, however, may not provide a way to check if the stats are
 383 available (or the way to check it is unknown). They may not even provide
 384 a way to directly read the total number of bits or blocks.
 385
 386 On those devices, the driver need to ensure that it won't be reading from
 387 the register too often and/or estimate the total number of bits/blocks.
 388
 389 On such drivers, a typical routine to get statistics would be like
 390 (adapted from dib8000 driver's logic)::
 391
 392         struct foo_state {
 393                 /* ... */
 394
 395                 unsigned long per_jiffies_stats;
 396         }
 397
 398         static int foo_get_pre_ber(struct dvb_frontend *fe)
 399         {
 400                 struct foo_state *state = fe->demodulator_priv;
 401                 struct dtv_frontend_properties *c = &fe->dtv_property_cache;
 402                 int rc, bit_error;
 403                 u64 bits;
 404
 405                 /* Check if time for stats was elapsed */
 406                 if (!time_after(jiffies, state->per_jiffies_stats))
 407                         return 0;
 408
 409                 /* Next stat should be collected in 1000 ms */
 410                 state->per_jiffies_stats = jiffies + msecs_to_jiffies(1000);
 411
 412                 /* Read Bit Error Count */
 413                 bit_error = foo_read_u32(state, 0x55);
 414                 if (bit_error < 0)
 415                         return bit_error;
 416
 417                 /*
 418                  * On this particular frontend, there's no register that
 419                  * would provide the number of bits per 1000ms sample. So,
 420                  * some function would calculate it based on DTV properties
 421                  */
 422                 bits = get_number_of_bits_per_1000ms(fe);
 423
 424                 c->pre_bit_error.stat[0].scale = FE_SCALE_COUNTER;
 425                 c->pre_bit_error.stat[0].uvalue += bit_error;
 426                 c->pre_bit_count.stat[0].scale = FE_SCALE_COUNTER;
 427                 c->pre_bit_count.stat[0].uvalue += bits;
 428
 429                 return 0;
 430         }
 431
 432 Please notice that, on both cases, we're getting the statistics using the
 433 :c:type:`dvb_frontend_ops` ``.read_status`` callback. The rationale is that
 434 the frontend core will automatically call this function periodically
 435 (usually, 3 times per second, when the frontend is locked).
 436
 437 That warrants that we won't miss to collect a counter and increment the
 438 monotonic stats at the right time.
 439
 440 Digital TV Frontend functions and types
 441 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 442
 443 .. kernel-doc:: include/media/dvb_frontend.h