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