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