0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 Digital TV Frontend kABI
0004 ------------------------
0005
0006 Digital TV Frontend
0007 ~~~~~~~~~~~~~~~~~~~
0008
0009 The Digital TV Frontend kABI defines a driver-internal interface for
0010 registering low-level, hardware specific driver to a hardware independent
0011 frontend layer. It is only of interest for Digital TV device driver writers.
0012 The header file for this API is named ``dvb_frontend.h`` and located in
0013 ``include/media/``.
0014
0015 Demodulator driver
0016 ^^^^^^^^^^^^^^^^^^
0017
0018 The demodulator driver is responsible for talking with the decoding part of the
0019 hardware. Such driver should implement :c:type:`dvb_frontend_ops`, which
0020 tells what type of digital TV standards are supported, and points to a
0021 series of functions that allow the DVB core to command the hardware via
0022 the code under ``include/media/dvb_frontend.c``.
0023
0024 A typical example of such struct in a driver ``foo`` is::
0025
0026 static struct dvb_frontend_ops foo_ops = {
0027 .delsys = { SYS_DVBT, SYS_DVBT2, SYS_DVBC_ANNEX_A },
0028 .info = {
0029 .name = "foo DVB-T/T2/C driver",
0030 .caps = FE_CAN_FEC_1_2 |
0031 FE_CAN_FEC_2_3 |
0032 FE_CAN_FEC_3_4 |
0033 FE_CAN_FEC_5_6 |
0034 FE_CAN_FEC_7_8 |
0035 FE_CAN_FEC_AUTO |
0036 FE_CAN_QPSK |
0037 FE_CAN_QAM_16 |
0038 FE_CAN_QAM_32 |
0039 FE_CAN_QAM_64 |
0040 FE_CAN_QAM_128 |
0041 FE_CAN_QAM_256 |
0042 FE_CAN_QAM_AUTO |
0043 FE_CAN_TRANSMISSION_MODE_AUTO |
0044 FE_CAN_GUARD_INTERVAL_AUTO |
0045 FE_CAN_HIERARCHY_AUTO |
0046 FE_CAN_MUTE_TS |
0047 FE_CAN_2G_MODULATION,
0048 .frequency_min = 42000000, /* Hz */
0049 .frequency_max = 1002000000, /* Hz */
0050 .symbol_rate_min = 870000,
0051 .symbol_rate_max = 11700000
0052 },
0053 .init = foo_init,
0054 .sleep = foo_sleep,
0055 .release = foo_release,
0056 .set_frontend = foo_set_frontend,
0057 .get_frontend = foo_get_frontend,
0058 .read_status = foo_get_status_and_stats,
0059 .tune = foo_tune,
0060 .i2c_gate_ctrl = foo_i2c_gate_ctrl,
0061 .get_frontend_algo = foo_get_algo,
0062 };
0063
0064 A typical example of such struct in a driver ``bar`` meant to be used on
0065 Satellite TV reception is::
0066
0067 static const struct dvb_frontend_ops bar_ops = {
0068 .delsys = { SYS_DVBS, SYS_DVBS2 },
0069 .info = {
0070 .name = "Bar DVB-S/S2 demodulator",
0071 .frequency_min = 500000, /* KHz */
0072 .frequency_max = 2500000, /* KHz */
0073 .frequency_stepsize = 0,
0074 .symbol_rate_min = 1000000,
0075 .symbol_rate_max = 45000000,
0076 .symbol_rate_tolerance = 500,
0077 .caps = FE_CAN_INVERSION_AUTO |
0078 FE_CAN_FEC_AUTO |
0079 FE_CAN_QPSK,
0080 },
0081 .init = bar_init,
0082 .sleep = bar_sleep,
0083 .release = bar_release,
0084 .set_frontend = bar_set_frontend,
0085 .get_frontend = bar_get_frontend,
0086 .read_status = bar_get_status_and_stats,
0087 .i2c_gate_ctrl = bar_i2c_gate_ctrl,
0088 .get_frontend_algo = bar_get_algo,
0089 .tune = bar_tune,
0090
0091 /* Satellite-specific */
0092 .diseqc_send_master_cmd = bar_send_diseqc_msg,
0093 .diseqc_send_burst = bar_send_burst,
0094 .set_tone = bar_set_tone,
0095 .set_voltage = bar_set_voltage,
0096 };
0097
0098 .. note::
0099
0100 #) For satellite digital TV standards (DVB-S, DVB-S2, ISDB-S), the
0101 frequencies are specified in kHz, while, for terrestrial and cable
0102 standards, they're specified in Hz. Due to that, if the same frontend
0103 supports both types, you'll need to have two separate
0104 :c:type:`dvb_frontend_ops` structures, one for each standard.
0105 #) The ``.i2c_gate_ctrl`` field is present only when the hardware has
0106 allows controlling an I2C gate (either directly of via some GPIO pin),
0107 in order to remove the tuner from the I2C bus after a channel is
0108 tuned.
0109 #) All new drivers should implement the
0110 :ref:`DVBv5 statistics <dvbv5_stats>` via ``.read_status``.
0111 Yet, there are a number of callbacks meant to get statistics for
0112 signal strength, S/N and UCB. Those are there to provide backward
0113 compatibility with legacy applications that don't support the DVBv5
0114 API. Implementing those callbacks are optional. Those callbacks may be
0115 removed in the future, after we have all existing drivers supporting
0116 DVBv5 stats.
0117 #) Other callbacks are required for satellite TV standards, in order to
0118 control LNBf and DiSEqC: ``.diseqc_send_master_cmd``,
0119 ``.diseqc_send_burst``, ``.set_tone``, ``.set_voltage``.
0120
0121 .. |delta| unicode:: U+00394
0122
0123 The ``include/media/dvb_frontend.c`` has a kernel thread which is
0124 responsible for tuning the device. It supports multiple algorithms to
0125 detect a channel, as defined at enum :c:func:`dvbfe_algo`.
0126
0127 The algorithm to be used is obtained via ``.get_frontend_algo``. If the driver
0128 doesn't fill its field at struct dvb_frontend_ops, it will default to
0129 ``DVBFE_ALGO_SW``, meaning that the dvb-core will do a zigzag when tuning,
0130 e. g. it will try first to use the specified center frequency ``f``,
0131 then, it will do ``f`` + |delta|, ``f`` - |delta|, ``f`` + 2 x |delta|,
0132 ``f`` - 2 x |delta| and so on.
0133
0134 If the hardware has internally a some sort of zigzag algorithm, you should
0135 define a ``.get_frontend_algo`` function that would return ``DVBFE_ALGO_HW``.
0136
0137 .. note::
0138
0139 The core frontend support also supports
0140 a third type (``DVBFE_ALGO_CUSTOM``), in order to allow the driver to
0141 define its own hardware-assisted algorithm. Very few hardware need to
0142 use it nowadays. Using ``DVBFE_ALGO_CUSTOM`` require to provide other
0143 function callbacks at struct dvb_frontend_ops.
0144
0145 Attaching frontend driver to the bridge driver
0146 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
0147
0148 Before using the Digital TV frontend core, the bridge driver should attach
0149 the frontend demod, tuner and SEC devices and call
0150 :c:func:`dvb_register_frontend()`,
0151 in order to register the new frontend at the subsystem. At device
0152 detach/removal, the bridge driver should call
0153 :c:func:`dvb_unregister_frontend()` to
0154 remove the frontend from the core and then :c:func:`dvb_frontend_detach()`
0155 to free the memory allocated by the frontend drivers.
0156
0157 The drivers should also call :c:func:`dvb_frontend_suspend()` as part of
0158 their handler for the :c:type:`device_driver`.\ ``suspend()``, and
0159 :c:func:`dvb_frontend_resume()` as
0160 part of their handler for :c:type:`device_driver`.\ ``resume()``.
0161
0162 A few other optional functions are provided to handle some special cases.
0163
0164 .. _dvbv5_stats:
0165
0166 Digital TV Frontend statistics
0167 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0168
0169 Introduction
0170 ^^^^^^^^^^^^
0171
0172 Digital TV frontends provide a range of
0173 :ref:`statistics <frontend-stat-properties>` meant to help tuning the device
0174 and measuring the quality of service.
0175
0176 For each statistics measurement, the driver should set the type of scale used,
0177 or ``FE_SCALE_NOT_AVAILABLE`` if the statistics is not available on a given
0178 time. Drivers should also provide the number of statistics for each type.
0179 that's usually 1 for most video standards [#f2]_.
0180
0181 Drivers should initialize each statistic counters with length and
0182 scale at its init code. For example, if the frontend provides signal
0183 strength, it should have, on its init code::
0184
0185 struct dtv_frontend_properties *c = &state->fe.dtv_property_cache;
0186
0187 c->strength.len = 1;
0188 c->strength.stat[0].scale = FE_SCALE_NOT_AVAILABLE;
0189
0190 And, when the statistics got updated, set the scale::
0191
0192 c->strength.stat[0].scale = FE_SCALE_DECIBEL;
0193 c->strength.stat[0].uvalue = strength;
0194
0195 .. [#f2] For ISDB-T, it may provide both a global statistics and a per-layer
0196 set of statistics. On such cases, len should be equal to 4. The first
0197 value corresponds to the global stat; the other ones to each layer, e. g.:
0198
0199 - c->cnr.stat[0] for global S/N carrier ratio,
0200 - c->cnr.stat[1] for Layer A S/N carrier ratio,
0201 - c->cnr.stat[2] for layer B S/N carrier ratio,
0202 - c->cnr.stat[3] for layer C S/N carrier ratio.
0203
0204 .. note:: Please prefer to use ``FE_SCALE_DECIBEL`` instead of
0205 ``FE_SCALE_RELATIVE`` for signal strength and CNR measurements.
0206
0207 Groups of statistics
0208 ^^^^^^^^^^^^^^^^^^^^
0209
0210 There are several groups of statistics currently supported:
0211
0212 Signal strength (:ref:`DTV-STAT-SIGNAL-STRENGTH`)
0213 - Measures the signal strength level at the analog part of the tuner or
0214 demod.
0215
0216 - Typically obtained from the gain applied to the tuner and/or frontend
0217 in order to detect the carrier. When no carrier is detected, the gain is
0218 at the maximum value (so, strength is on its minimal).
0219
0220 - As the gain is visible through the set of registers that adjust the gain,
0221 typically, this statistics is always available [#f3]_.
0222
0223 - Drivers should try to make it available all the times, as these statistics
0224 can be used when adjusting an antenna position and to check for troubles
0225 at the cabling.
0226
0227 .. [#f3] On a few devices, the gain keeps floating if there is no carrier.
0228 On such devices, strength report should check first if carrier is
0229 detected at the tuner (``FE_HAS_CARRIER``, see :c:type:`fe_status`),
0230 and otherwise return the lowest possible value.
0231
0232 Carrier Signal to Noise ratio (:ref:`DTV-STAT-CNR`)
0233 - Signal to Noise ratio for the main carrier.
0234
0235 - Signal to Noise measurement depends on the device. On some hardware, it is
0236 available when the main carrier is detected. On those hardware, CNR
0237 measurement usually comes from the tuner (e. g. after ``FE_HAS_CARRIER``,
0238 see :c:type:`fe_status`).
0239
0240 On other devices, it requires inner FEC decoding,
0241 as the frontend measures it indirectly from other parameters (e. g. after
0242 ``FE_HAS_VITERBI``, see :c:type:`fe_status`).
0243
0244 Having it available after inner FEC is more common.
0245
0246 Bit counts post-FEC (:ref:`DTV-STAT-POST-ERROR-BIT-COUNT` and :ref:`DTV-STAT-POST-TOTAL-BIT-COUNT`)
0247 - Those counters measure the number of bits and bit errors after
0248 the forward error correction (FEC) on the inner coding block
0249 (after Viterbi, LDPC or other inner code).
0250
0251 - Due to its nature, those statistics depend on full coding lock
0252 (e. g. after ``FE_HAS_SYNC`` or after ``FE_HAS_LOCK``,
0253 see :c:type:`fe_status`).
0254
0255 Bit counts pre-FEC (:ref:`DTV-STAT-PRE-ERROR-BIT-COUNT` and :ref:`DTV-STAT-PRE-TOTAL-BIT-COUNT`)
0256 - Those counters measure the number of bits and bit errors before
0257 the forward error correction (FEC) on the inner coding block
0258 (before Viterbi, LDPC or other inner code).
0259
0260 - Not all frontends provide this kind of statistics.
0261
0262 - Due to its nature, those statistics depend on inner coding lock (e. g.
0263 after ``FE_HAS_VITERBI``, see :c:type:`fe_status`).
0264
0265 Block counts (:ref:`DTV-STAT-ERROR-BLOCK-COUNT` and :ref:`DTV-STAT-TOTAL-BLOCK-COUNT`)
0266 - Those counters measure the number of blocks and block errors after
0267 the forward error correction (FEC) on the inner coding block
0268 (before Viterbi, LDPC or other inner code).
0269
0270 - Due to its nature, those statistics depend on full coding lock
0271 (e. g. after ``FE_HAS_SYNC`` or after
0272 ``FE_HAS_LOCK``, see :c:type:`fe_status`).
0273
0274 .. note:: All counters should be monotonically increased as they're
0275 collected from the hardware.
0276
0277 A typical example of the logic that handle status and statistics is::
0278
0279 static int foo_get_status_and_stats(struct dvb_frontend *fe)
0280 {
0281 struct foo_state *state = fe->demodulator_priv;
0282 struct dtv_frontend_properties *c = &fe->dtv_property_cache;
0283
0284 int rc;
0285 enum fe_status *status;
0286
0287 /* Both status and strength are always available */
0288 rc = foo_read_status(fe, &status);
0289 if (rc < 0)
0290 return rc;
0291
0292 rc = foo_read_strength(fe);
0293 if (rc < 0)
0294 return rc;
0295
0296 /* Check if CNR is available */
0297 if (!(fe->status & FE_HAS_CARRIER))
0298 return 0;
0299
0300 rc = foo_read_cnr(fe);
0301 if (rc < 0)
0302 return rc;
0303
0304 /* Check if pre-BER stats are available */
0305 if (!(fe->status & FE_HAS_VITERBI))
0306 return 0;
0307
0308 rc = foo_get_pre_ber(fe);
0309 if (rc < 0)
0310 return rc;
0311
0312 /* Check if post-BER stats are available */
0313 if (!(fe->status & FE_HAS_SYNC))
0314 return 0;
0315
0316 rc = foo_get_post_ber(fe);
0317 if (rc < 0)
0318 return rc;
0319 }
0320
0321 static const struct dvb_frontend_ops ops = {
0322 /* ... */
0323 .read_status = foo_get_status_and_stats,
0324 };
0325
0326 Statistics collection
0327 ^^^^^^^^^^^^^^^^^^^^^
0328
0329 On almost all frontend hardware, the bit and byte counts are stored by
0330 the hardware after a certain amount of time or after the total bit/block
0331 counter reaches a certain value (usually programmable), for example, on
0332 every 1000 ms or after receiving 1,000,000 bits.
0333
0334 So, if you read the registers too soon, you'll end by reading the same
0335 value as in the previous reading, causing the monotonic value to be
0336 incremented too often.
0337
0338 Drivers should take the responsibility to avoid too often reads. That
0339 can be done using two approaches:
0340
0341 if the driver have a bit that indicates when a collected data is ready
0342 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0343
0344 Driver should check such bit before making the statistics available.
0345
0346 An example of such behavior can be found at this code snippet (adapted
0347 from mb86a20s driver's logic)::
0348
0349 static int foo_get_pre_ber(struct dvb_frontend *fe)
0350 {
0351 struct foo_state *state = fe->demodulator_priv;
0352 struct dtv_frontend_properties *c = &fe->dtv_property_cache;
0353 int rc, bit_error;
0354
0355 /* Check if the BER measures are already available */
0356 rc = foo_read_u8(state, 0x54);
0357 if (rc < 0)
0358 return rc;
0359
0360 if (!rc)
0361 return 0;
0362
0363 /* Read Bit Error Count */
0364 bit_error = foo_read_u32(state, 0x55);
0365 if (bit_error < 0)
0366 return bit_error;
0367
0368 /* Read Total Bit Count */
0369 rc = foo_read_u32(state, 0x51);
0370 if (rc < 0)
0371 return rc;
0372
0373 c->pre_bit_error.stat[0].scale = FE_SCALE_COUNTER;
0374 c->pre_bit_error.stat[0].uvalue += bit_error;
0375 c->pre_bit_count.stat[0].scale = FE_SCALE_COUNTER;
0376 c->pre_bit_count.stat[0].uvalue += rc;
0377
0378 return 0;
0379 }
0380
0381 If the driver doesn't provide a statistics available check bit
0382 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0383
0384 A few devices, however, may not provide a way to check if the stats are
0385 available (or the way to check it is unknown). They may not even provide
0386 a way to directly read the total number of bits or blocks.
0387
0388 On those devices, the driver need to ensure that it won't be reading from
0389 the register too often and/or estimate the total number of bits/blocks.
0390
0391 On such drivers, a typical routine to get statistics would be like
0392 (adapted from dib8000 driver's logic)::
0393
0394 struct foo_state {
0395 /* ... */
0396
0397 unsigned long per_jiffies_stats;
0398 }
0399
0400 static int foo_get_pre_ber(struct dvb_frontend *fe)
0401 {
0402 struct foo_state *state = fe->demodulator_priv;
0403 struct dtv_frontend_properties *c = &fe->dtv_property_cache;
0404 int rc, bit_error;
0405 u64 bits;
0406
0407 /* Check if time for stats was elapsed */
0408 if (!time_after(jiffies, state->per_jiffies_stats))
0409 return 0;
0410
0411 /* Next stat should be collected in 1000 ms */
0412 state->per_jiffies_stats = jiffies + msecs_to_jiffies(1000);
0413
0414 /* Read Bit Error Count */
0415 bit_error = foo_read_u32(state, 0x55);
0416 if (bit_error < 0)
0417 return bit_error;
0418
0419 /*
0420 * On this particular frontend, there's no register that
0421 * would provide the number of bits per 1000ms sample. So,
0422 * some function would calculate it based on DTV properties
0423 */
0424 bits = get_number_of_bits_per_1000ms(fe);
0425
0426 c->pre_bit_error.stat[0].scale = FE_SCALE_COUNTER;
0427 c->pre_bit_error.stat[0].uvalue += bit_error;
0428 c->pre_bit_count.stat[0].scale = FE_SCALE_COUNTER;
0429 c->pre_bit_count.stat[0].uvalue += bits;
0430
0431 return 0;
0432 }
0433
0434 Please notice that, on both cases, we're getting the statistics using the
0435 :c:type:`dvb_frontend_ops` ``.read_status`` callback. The rationale is that
0436 the frontend core will automatically call this function periodically
0437 (usually, 3 times per second, when the frontend is locked).
0438
0439 That warrants that we won't miss to collect a counter and increment the
0440 monotonic stats at the right time.
0441
0442 Digital TV Frontend functions and types
0443 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0444
0445 .. kernel-doc:: include/media/dvb_frontend.h
