Documentation/driver-api/media/dtv-frontend.rst

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