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