1.. SPDX-License-Identifier: GPL-2.0 2 3Digital TV Frontend kABI 4------------------------ 5 6Digital TV Frontend 7~~~~~~~~~~~~~~~~~~~ 8 9The Digital TV Frontend kABI defines a driver-internal interface for 10registering low-level, hardware specific driver to a hardware independent 11frontend layer. It is only of interest for Digital TV device driver writers. 12The header file for this API is named ``dvb_frontend.h`` and located in 13``include/media/``. 14 15Demodulator driver 16^^^^^^^^^^^^^^^^^^ 17 18The demodulator driver is responsible for talking with the decoding part of the 19hardware. Such driver should implement :c:type:`dvb_frontend_ops`, which 20tells what type of digital TV standards are supported, and points to a 21series of functions that allow the DVB core to command the hardware via 22the code under ``include/media/dvb_frontend.c``. 23 24A 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 64A typical example of such struct in a driver ``bar`` meant to be used on 65Satellite 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 123The ``include/media/dvb_frontend.c`` has a kernel thread which is 124responsible for tuning the device. It supports multiple algorithms to 125detect a channel, as defined at enum :c:func:`dvbfe_algo`. 126 127The algorithm to be used is obtained via ``.get_frontend_algo``. If the driver 128doesn'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, 130e. g. it will try first to use the specified center frequency ``f``, 131then, it will do ``f`` + |delta|, ``f`` - |delta|, ``f`` + 2 x |delta|, 132``f`` - 2 x |delta| and so on. 133 134If the hardware has internally a some sort of zigzag algorithm, you should 135define 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 145Attaching frontend driver to the bridge driver 146^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 147 148Before using the Digital TV frontend core, the bridge driver should attach 149the frontend demod, tuner and SEC devices and call 150:c:func:`dvb_register_frontend()`, 151in order to register the new frontend at the subsystem. At device 152detach/removal, the bridge driver should call 153:c:func:`dvb_unregister_frontend()` to 154remove the frontend from the core and then :c:func:`dvb_frontend_detach()` 155to free the memory allocated by the frontend drivers. 156 157The drivers should also call :c:func:`dvb_frontend_suspend()` as part of 158their handler for the :c:type:`device_driver`.\ ``suspend()``, and 159:c:func:`dvb_frontend_resume()` as 160part of their handler for :c:type:`device_driver`.\ ``resume()``. 161 162A few other optional functions are provided to handle some special cases. 163 164.. _dvbv5_stats: 165 166Digital TV Frontend statistics 167~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 168 169Introduction 170^^^^^^^^^^^^ 171 172Digital TV frontends provide a range of 173:ref:`statistics <frontend-stat-properties>` meant to help tuning the device 174and measuring the quality of service. 175 176For each statistics measurement, the driver should set the type of scale used, 177or ``FE_SCALE_NOT_AVAILABLE`` if the statistics is not available on a given 178time. Drivers should also provide the number of statistics for each type. 179that's usually 1 for most video standards [#f2]_. 180 181Drivers should initialize each statistic counters with length and 182scale at its init code. For example, if the frontend provides signal 183strength, 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 190And, 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 207Groups of statistics 208^^^^^^^^^^^^^^^^^^^^ 209 210There are several groups of statistics currently supported: 211 212Signal 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 232Carrier 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 246Bit 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 255Bit 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 265Block 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 277A 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 326Statistics collection 327^^^^^^^^^^^^^^^^^^^^^ 328 329On almost all frontend hardware, the bit and byte counts are stored by 330the hardware after a certain amount of time or after the total bit/block 331counter reaches a certain value (usually programmable), for example, on 332every 1000 ms or after receiving 1,000,000 bits. 333 334So, if you read the registers too soon, you'll end by reading the same 335value as in the previous reading, causing the monotonic value to be 336incremented too often. 337 338Drivers should take the responsibility to avoid too often reads. That 339can be done using two approaches: 340 341if the driver have a bit that indicates when a collected data is ready 342%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 343 344Driver should check such bit before making the statistics available. 345 346An example of such behavior can be found at this code snippet (adapted 347from 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 381If the driver doesn't provide a statistics available check bit 382%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 383 384A few devices, however, may not provide a way to check if the stats are 385available (or the way to check it is unknown). They may not even provide 386a way to directly read the total number of bits or blocks. 387 388On those devices, the driver need to ensure that it won't be reading from 389the register too often and/or estimate the total number of bits/blocks. 390 391On 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 434Please 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 436the frontend core will automatically call this function periodically 437(usually, 3 times per second, when the frontend is locked). 438 439That warrants that we won't miss to collect a counter and increment the 440monotonic stats at the right time. 441 442Digital TV Frontend functions and types 443~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 444 445.. kernel-doc:: include/media/dvb_frontend.h 446