446 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3Digital TV Frontend kABI4------------------------5 6Digital TV Frontend7~~~~~~~~~~~~~~~~~~~8 9The Digital TV Frontend kABI defines a driver-internal interface for10registering low-level, hardware specific driver to a hardware independent11frontend 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 in13``include/media/``.14 15Demodulator driver16^^^^^^^^^^^^^^^^^^17 18The demodulator driver is responsible for talking with the decoding part of the19hardware. Such driver should implement :c:type:`dvb_frontend_ops`, which20tells what type of digital TV standards are supported, and points to a21series of functions that allow the DVB core to command the hardware via22the 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 = 1170000052 },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 on65Satellite 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), the101 frequencies are specified in kHz, while, for terrestrial and cable102 standards, they're specified in Hz. Due to that, if the same frontend103 supports both types, you'll need to have two separate104 :c:type:`dvb_frontend_ops` structures, one for each standard.105 #) The ``.i2c_gate_ctrl`` field is present only when the hardware has106 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 is108 tuned.109 #) All new drivers should implement the110 :ref:`DVBv5 statistics <dvbv5_stats>` via ``.read_status``.111 Yet, there are a number of callbacks meant to get statistics for112 signal strength, S/N and UCB. Those are there to provide backward113 compatibility with legacy applications that don't support the DVBv5114 API. Implementing those callbacks are optional. Those callbacks may be115 removed in the future, after we have all existing drivers supporting116 DVBv5 stats.117 #) Other callbacks are required for satellite TV standards, in order to118 control LNBf and DiSEqC: ``.diseqc_send_master_cmd``,119 ``.diseqc_send_burst``, ``.set_tone``, ``.set_voltage``.120 121.. |delta| unicode:: U+00394122 123The ``include/media/dvb_frontend.c`` has a kernel thread which is124responsible for tuning the device. It supports multiple algorithms to125detect a channel, as defined at enum :c:func:`dvbfe_algo`.126 127The algorithm to be used is obtained via ``.get_frontend_algo``. If the driver128doesn't fill its field at struct dvb_frontend_ops, it will default to129``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 should135define a ``.get_frontend_algo`` function that would return ``DVBFE_ALGO_HW``.136 137.. note::138 139 The core frontend support also supports140 a third type (``DVBFE_ALGO_CUSTOM``), in order to allow the driver to141 define its own hardware-assisted algorithm. Very few hardware need to142 use it nowadays. Using ``DVBFE_ALGO_CUSTOM`` require to provide other143 function callbacks at struct dvb_frontend_ops.144 145Attaching frontend driver to the bridge driver146^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^147 148Before using the Digital TV frontend core, the bridge driver should attach149the frontend demod, tuner and SEC devices and call150:c:func:`dvb_register_frontend()`,151in order to register the new frontend at the subsystem. At device152detach/removal, the bridge driver should call153:c:func:`dvb_unregister_frontend()` to154remove 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 of158their handler for the :c:type:`device_driver`.\ ``suspend()``, and159:c:func:`dvb_frontend_resume()` as160part 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 statistics167~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~168 169Introduction170^^^^^^^^^^^^171 172Digital TV frontends provide a range of173:ref:`statistics <frontend-stat-properties>` meant to help tuning the device174and 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 given178time. 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 and182scale at its init code. For example, if the frontend provides signal183strength, 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-layer196 set of statistics. On such cases, len should be equal to 4. The first197 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 of205 ``FE_SCALE_RELATIVE`` for signal strength and CNR measurements.206 207Groups of statistics208^^^^^^^^^^^^^^^^^^^^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 or214 demod.215 216 - Typically obtained from the gain applied to the tuner and/or frontend217 in order to detect the carrier. When no carrier is detected, the gain is218 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 statistics224 can be used when adjusting an antenna position and to check for troubles225 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 is229 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 is236 available when the main carrier is detected. On those hardware, CNR237 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. after242 ``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 after248 the forward error correction (FEC) on the inner coding block249 (after Viterbi, LDPC or other inner code).250 251 - Due to its nature, those statistics depend on full coding lock252 (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 before257 the forward error correction (FEC) on the inner coding block258 (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 after267 the forward error correction (FEC) on the inner coding block268 (before Viterbi, LDPC or other inner code).269 270 - Due to its nature, those statistics depend on full coding lock271 (e. g. after ``FE_HAS_SYNC`` or after272 ``FE_HAS_LOCK``, see :c:type:`fe_status`).273 274.. note:: All counters should be monotonically increased as they're275 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 collection327^^^^^^^^^^^^^^^^^^^^^328 329On almost all frontend hardware, the bit and byte counts are stored by330the hardware after a certain amount of time or after the total bit/block331counter reaches a certain value (usually programmable), for example, on332every 1000 ms or after receiving 1,000,000 bits.333 334So, if you read the registers too soon, you'll end by reading the same335value as in the previous reading, causing the monotonic value to be336incremented too often.337 338Drivers should take the responsibility to avoid too often reads. That339can be done using two approaches:340 341if the driver have a bit that indicates when a collected data is ready342%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%343 344Driver should check such bit before making the statistics available.345 346An example of such behavior can be found at this code snippet (adapted347from 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 bit382%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%383 384A few devices, however, may not provide a way to check if the stats are385available (or the way to check it is unknown). They may not even provide386a 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 from389the register too often and/or estimate the total number of bits/blocks.390 391On such drivers, a typical routine to get statistics would be like392(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 that421 * would provide the number of bits per 1000ms sample. So,422 * some function would calculate it based on DTV properties423 */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 the435:c:type:`dvb_frontend_ops` ``.read_status`` callback. The rationale is that436the frontend core will automatically call this function periodically437(usually, 3 times per second, when the frontend is locked).438 439That warrants that we won't miss to collect a counter and increment the440monotonic stats at the right time.441 442Digital TV Frontend functions and types443~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~444 445.. kernel-doc:: include/media/dvb_frontend.h446