1 Digital TV (DVB) devices
2 ------------------------
4 Digital TV devices are implemented by several different drivers:
6 - A bridge driver that is responsible to talk with the bus where the other
7 devices are connected (PCI, USB, SPI), bind to the other drivers and
8 implement the digital demux logic (either in software or in hardware);
10 - Frontend drivers that are usually implemented as two separate drivers:
12 - A tuner driver that implements the logic with commands the part of the
13 hardware with is reponsible to tune into a digital TV transponder or
14 physical channel. The output of a tuner is usually a baseband or
15 Intermediate Frequency (IF) signal;
17 - A demodulator driver (a.k.a "demod") that implements the logic with
18 commands the digital TV decoding hardware. The output of a demod is
19 a digital stream, with multiple audio, video and data channels typically
20 multiplexed using MPEG Transport Stream [#f1]_.
22 On most hardware, the frontend drivers talk with the bridge driver using an
25 .. [#f1] Some standards use TCP/IP for multiplexing data, like DVB-H (an
26 abandoned standard, not used anymore) and ATSC version 3.0 current
27 proposals. Currently, the DVB subsystem doesn't implement those standards.
29 Digital TV Common functions
30 ---------------------------
32 .. kernel-doc:: drivers/media/dvb-core/dvb_math.h
34 .. kernel-doc:: drivers/media/dvb-core/dvbdev.h
36 Digital TV Ring buffer
37 ----------------------
39 Those routines implement ring buffers used to handle digital TV data and
40 copy it from/to userspace.
44 1) For performance reasons read and write routines don't check buffer sizes
45 and/or number of bytes free/available. This has to be done before these
46 routines are called. For example:
50 /* write @buflen: bytes */
51 free = dvb_ringbuffer_free(rbuf);
53 count = dvb_ringbuffer_write(rbuf, buffer, buflen);
57 /* read min. 1000, max. @bufsize: bytes */
58 avail = dvb_ringbuffer_avail(rbuf);
60 count = dvb_ringbuffer_read(rbuf, buffer, min(avail, bufsize));
64 2) If there is exactly one reader and one writer, there is no need
65 to lock read or write operations.
66 Two or more readers must be locked against each other.
67 Flushing the buffer counts as a read operation.
68 Resetting the buffer counts as a read and write operation.
69 Two or more writers must be locked against each other.
71 .. kernel-doc:: drivers/media/dvb-core/dvb_ringbuffer.h
74 Digital TV Frontend kABI
75 ------------------------
80 The Digital TV Frontend kABI defines a driver-internal interface for
81 registering low-level, hardware specific driver to a hardware independent
82 frontend layer. It is only of interest for Digital TV device driver writers.
83 The header file for this API is named ``dvb_frontend.h`` and located in
84 ``drivers/media/dvb-core``.
89 The demodulator driver is responsible to talk with the decoding part of the
90 hardware. Such driver should implement :c:type:`dvb_frontend_ops`, with
91 tells what type of digital TV standards are supported, and points to a
92 series of functions that allow the DVB core to command the hardware via
93 the code under ``drivers/media/dvb-core/dvb_frontend.c``.
95 A typical example of such struct in a driver ``foo`` is::
97 static struct dvb_frontend_ops foo_ops = {
98 .delsys = { SYS_DVBT, SYS_DVBT2, SYS_DVBC_ANNEX_A },
100 .name = "foo DVB-T/T2/C driver",
101 .caps = FE_CAN_FEC_1_2 |
114 FE_CAN_TRANSMISSION_MODE_AUTO |
115 FE_CAN_GUARD_INTERVAL_AUTO |
116 FE_CAN_HIERARCHY_AUTO |
118 FE_CAN_2G_MODULATION,
119 .frequency_min = 42000000, /* Hz */
120 .frequency_max = 1002000000, /* Hz */
121 .symbol_rate_min = 870000,
122 .symbol_rate_max = 11700000
126 .release = foo_release,
127 .set_frontend = foo_set_frontend,
128 .get_frontend = foo_get_frontend,
129 .read_status = foo_get_status_and_stats,
131 .i2c_gate_ctrl = foo_i2c_gate_ctrl,
132 .get_frontend_algo = foo_get_algo,
135 A typical example of such struct in a driver ``bar`` meant to be used on
136 Satellite TV reception is::
138 static const struct dvb_frontend_ops bar_ops = {
139 .delsys = { SYS_DVBS, SYS_DVBS2 },
141 .name = "Bar DVB-S/S2 demodulator",
142 .frequency_min = 500000, /* KHz */
143 .frequency_max = 2500000, /* KHz */
144 .frequency_stepsize = 0,
145 .symbol_rate_min = 1000000,
146 .symbol_rate_max = 45000000,
147 .symbol_rate_tolerance = 500,
148 .caps = FE_CAN_INVERSION_AUTO |
154 .release = bar_release,
155 .set_frontend = bar_set_frontend,
156 .get_frontend = bar_get_frontend,
157 .read_status = bar_get_status_and_stats,
158 .i2c_gate_ctrl = bar_i2c_gate_ctrl,
159 .get_frontend_algo = bar_get_algo,
162 /* Satellite-specific */
163 .diseqc_send_master_cmd = bar_send_diseqc_msg,
164 .diseqc_send_burst = bar_send_burst,
165 .set_tone = bar_set_tone,
166 .set_voltage = bar_set_voltage,
171 #) For satellite digital TV standards (DVB-S, DVB-S2, ISDB-S), the
172 frequencies are specified in kHz, while, for terrestrial and cable
173 standards, they're specified in Hz. Due to that, if the same frontend
174 supports both types, you'll need to have two separate
175 :c:type:`dvb_frontend_ops` structures, one for each standard.
176 #) The ``.i2c_gate_ctrl`` field is present only when the hardware has
177 allows controlling an I2C gate (either directly of via some GPIO pin),
178 in order to remove the tuner from the I2C bus after a channel is
180 #) All new drivers should implement the
181 :ref:`DVBv5 statistics <dvbv5_stats>` via ``.read_status``.
182 Yet, there are a number of callbacks meant to get statistics for
183 signal strength, S/N and UCB. Those are there to provide backward
184 compatibility with legacy applications that don't support the DVBv5
185 API. Implementing those callbacks are optional. Those callbacks may be
186 removed in the future, after we have all existing drivers supporting
188 #) Other callbacks are required for satellite TV standards, in order to
189 control LNBf and DiSEqC: ``.diseqc_send_master_cmd``,
190 ``.diseqc_send_burst``, ``.set_tone``, ``.set_voltage``.
192 .. |delta| unicode:: U+00394
194 The ``drivers/media/dvb-core/dvb_frontend.c`` has a kernel thread with is
195 responsible for tuning the device. It supports multiple algoritms to
196 detect a channel, as defined at enum :c:func:`dvbfe_algo`.
198 The algorithm to be used is obtained via ``.get_frontend_algo``. If the driver
199 doesn't fill its field at struct :c:type:`dvb_frontend_ops`, it will default to
200 ``DVBFE_ALGO_SW``, meaning that the dvb-core will do a zigzag when tuning,
201 e. g. it will try first to use the specified center frequency ``f``,
202 then, it will do ``f`` + |delta|, ``f`` - |delta|, ``f`` + 2 x |delta|,
203 ``f`` - 2 x |delta| and so on.
205 If the hardware has internally a some sort of zigzag algorithm, you should
206 define a ``.get_frontend_algo`` function that would return ``DVBFE_ALGO_HW``.
210 The core frontend support also supports
211 a third type (``DVBFE_ALGO_CUSTOM``), in order to allow the driver to
212 define its own hardware-assisted algorithm. Very few hardware need to
213 use it nowadays. Using ``DVBFE_ALGO_CUSTOM`` require to provide other
214 function callbacks at struct :c:type:`dvb_frontend_ops`.
216 Attaching frontend driver to the bridge driver
217 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
219 Before using the Digital TV frontend core, the bridge driver should attach
220 the frontend demod, tuner and SEC devices and call
221 :c:func:`dvb_register_frontend()`,
222 in order to register the new frontend at the subsystem. At device
223 detach/removal, the bridge driver should call
224 :c:func:`dvb_unregister_frontend()` to
225 remove the frontend from the core and then :c:func:`dvb_frontend_detach()`
226 to free the memory allocated by the frontend drivers.
228 The drivers should also call :c:func:`dvb_frontend_suspend()` as part of
229 their handler for the :c:type:`device_driver`.\ ``suspend()``, and
230 :c:func:`dvb_frontend_resume()` as
231 part of their handler for :c:type:`device_driver`.\ ``resume()``.
233 A few other optional functions are provided to handle some special cases.
237 Digital TV Frontend statistics
238 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
243 Digital TV frontends provide a range of
244 :ref:`statistics <frontend-stat-properties>` meant to help tuning the device
245 and measuring the quality of service.
247 For each statistics measurement, the driver should set the type of scale used,
248 or ``FE_SCALE_NOT_AVAILABLE`` if the statistics is not available on a given
249 time. Drivers should also provide the number of statistics for each type.
250 that's usually 1 for most video standards [#f2]_.
252 Drivers should initialize each statistic counters with length and
253 scale at its init code. For example, if the frontend provides signal
254 strength, it should have, on its init code::
256 struct dtv_frontend_properties *c = &state->fe.dtv_property_cache;
259 c->strength.stat[0].scale = FE_SCALE_NOT_AVAILABLE;
261 And, when the statistics got updated, set the scale::
263 c->strength.stat[0].scale = FE_SCALE_DECIBEL;
264 c->strength.stat[0].uvalue = strength;
266 .. [#f2] For ISDB-T, it may provide both a global statistics and a per-layer
267 set of statistics. On such cases, len should be equal to 4. The first
268 value corresponds to the global stat; the other ones to each layer, e. g.:
270 - c->cnr.stat[0] for global S/N carrier ratio,
271 - c->cnr.stat[1] for Layer A S/N carrier ratio,
272 - c->cnr.stat[2] for layer B S/N carrier ratio,
273 - c->cnr.stat[3] for layer C S/N carrier ratio.
275 .. note:: Please prefer to use ``FE_SCALE_DECIBEL`` instead of
276 ``FE_SCALE_RELATIVE`` for signal strength and CNR measurements.
281 There are several groups of statistics currently supported:
283 Signal strength (:ref:`DTV-STAT-SIGNAL-STRENGTH`)
284 - Measures the signal strength level at the analog part of the tuner or
287 - Typically obtained from the gain applied to the tuner and/or frontend
288 in order to detect the carrier. When no carrier is detected, the gain is
289 at the maximum value (so, strength is on its minimal).
291 - As the gain is visible through the set of registers that adjust the gain,
292 typically, this statistics is always available [#f3]_.
294 - Drivers should try to make it available all the times, as this statistics
295 can be used when adjusting an antenna position and to check for troubles
298 .. [#f3] On a few devices, the gain keeps floating if no carrier.
299 On such devices, strength report should check first if carrier is
300 detected at the tuner (``FE_HAS_CARRIER``, see :c:type:`fe_status`),
301 and otherwise return the lowest possible value.
303 Carrier Signal to Noise ratio (:ref:`DTV-STAT-CNR`)
304 - Signal to Noise ratio for the main carrier.
306 - Signal to Noise measurement depends on the device. On some hardware, is
307 available when the main carrier is detected. On those hardware, CNR
308 measurement usually comes from the tuner (e. g. after ``FE_HAS_CARRIER``,
309 see :c:type:`fe_status`).
311 On other devices, it requires inner FEC decoding,
312 as the frontend measures it indirectly from other parameters (e. g. after
313 ``FE_HAS_VITERBI``, see :c:type:`fe_status`).
315 Having it available after inner FEC is more common.
317 Bit counts post-FEC (:ref:`DTV-STAT-POST-ERROR-BIT-COUNT` and :ref:`DTV-STAT-POST-TOTAL-BIT-COUNT`)
318 - Those counters measure the number of bits and bit errors errors after
319 the forward error correction (FEC) on the inner coding block
320 (after Viterbi, LDPC or other inner code).
322 - Due to its nature, those statistics depend on full coding lock
323 (e. g. after ``FE_HAS_SYNC`` or after ``FE_HAS_LOCK``,
324 see :c:type:`fe_status`).
326 Bit counts pre-FEC (:ref:`DTV-STAT-PRE-ERROR-BIT-COUNT` and :ref:`DTV-STAT-PRE-TOTAL-BIT-COUNT`)
327 - Those counters measure the number of bits and bit errors errors before
328 the forward error correction (FEC) on the inner coding block
329 (before Viterbi, LDPC or other inner code).
331 - Not all frontends provide this kind of statistics.
333 - Due to its nature, those statistics depend on inner coding lock (e. g.
334 after ``FE_HAS_VITERBI``, see :c:type:`fe_status`).
336 Block counts (:ref:`DTV-STAT-ERROR-BLOCK-COUNT` and :ref:`DTV-STAT-TOTAL-BLOCK-COUNT`)
337 - Those counters measure the number of blocks and block errors errors after
338 the forward error correction (FEC) on the inner coding block
339 (before Viterbi, LDPC or other inner code).
341 - Due to its nature, those statistics depend on full coding lock
342 (e. g. after ``FE_HAS_SYNC`` or after
343 ``FE_HAS_LOCK``, see :c:type:`fe_status`).
345 .. note:: All counters should be monotonically increased as they're
346 collected from the hardware.
348 A typical example of the logic that handle status and statistics is::
350 static int foo_get_status_and_stats(struct dvb_frontend *fe)
352 struct foo_state *state = fe->demodulator_priv;
353 struct dtv_frontend_properties *c = &fe->dtv_property_cache;
356 enum fe_status *status;
358 /* Both status and strength are always available */
359 rc = foo_read_status(fe, &status);
363 rc = foo_read_strength(fe);
367 /* Check if CNR is available */
368 if (!(fe->status & FE_HAS_CARRIER))
371 rc = foo_read_cnr(fe);
375 /* Check if pre-BER stats are available */
376 if (!(fe->status & FE_HAS_VITERBI))
379 rc = foo_get_pre_ber(fe);
383 /* Check if post-BER stats are available */
384 if (!(fe->status & FE_HAS_SYNC))
387 rc = foo_get_post_ber(fe);
392 static const struct dvb_frontend_ops ops = {
394 .read_status = foo_get_status_and_stats,
400 On almost all frontend hardware, the bit and byte counts are stored by
401 the hardware after a certain amount of time or after the total bit/block
402 counter reaches a certain value (usually programable), for example, on
403 every 1000 ms or after receiving 1,000,000 bits.
405 So, if you read the registers too soon, you'll end by reading the same
406 value as in the previous reading, causing the monotonic value to be
407 incremented too often.
409 Drivers should take the responsibility to avoid too often reads. That
410 can be done using two approaches:
412 if the driver have a bit that indicates when a collected data is ready
413 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
415 Driver should check such bit before making the statistics available.
417 An example of such behavior can be found at this code snippet (adapted
418 from mb86a20s driver's logic)::
420 static int foo_get_pre_ber(struct dvb_frontend *fe)
422 struct foo_state *state = fe->demodulator_priv;
423 struct dtv_frontend_properties *c = &fe->dtv_property_cache;
426 /* Check if the BER measures are already available */
427 rc = foo_read_u8(state, 0x54);
434 /* Read Bit Error Count */
435 bit_error = foo_read_u32(state, 0x55);
439 /* Read Total Bit Count */
440 rc = foo_read_u32(state, 0x51);
444 c->pre_bit_error.stat[0].scale = FE_SCALE_COUNTER;
445 c->pre_bit_error.stat[0].uvalue += bit_error;
446 c->pre_bit_count.stat[0].scale = FE_SCALE_COUNTER;
447 c->pre_bit_count.stat[0].uvalue += rc;
452 If the driver doesn't provide a statistics available check bit
453 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
455 A few devices, however, may not provide a way to check if the stats are
456 available (or the way to check it is unknown). They may not even provide
457 a way to directly read the total number of bits or blocks.
459 On those devices, the driver need to ensure that it won't be reading from
460 the register too often and/or estimate the total number of bits/blocks.
462 On such drivers, a typical routine to get statistics would be like
463 (adapted from dib8000 driver's logic)::
468 unsigned long per_jiffies_stats;
471 static int foo_get_pre_ber(struct dvb_frontend *fe)
473 struct foo_state *state = fe->demodulator_priv;
474 struct dtv_frontend_properties *c = &fe->dtv_property_cache;
478 /* Check if time for stats was elapsed */
479 if (!time_after(jiffies, state->per_jiffies_stats))
482 /* Next stat should be collected in 1000 ms */
483 state->per_jiffies_stats = jiffies + msecs_to_jiffies(1000);
485 /* Read Bit Error Count */
486 bit_error = foo_read_u32(state, 0x55);
491 * On this particular frontend, there's no register that
492 * would provide the number of bits per 1000ms sample. So,
493 * some function would calculate it based on DTV properties
495 bits = get_number_of_bits_per_1000ms(fe);
497 c->pre_bit_error.stat[0].scale = FE_SCALE_COUNTER;
498 c->pre_bit_error.stat[0].uvalue += bit_error;
499 c->pre_bit_count.stat[0].scale = FE_SCALE_COUNTER;
500 c->pre_bit_count.stat[0].uvalue += bits;
505 Please notice that, on both cases, we're getting the statistics using the
506 :c:type:`dvb_frontend_ops` ``.read_status`` callback. The rationale is that
507 the frontend core will automatically call this function periodically
508 (usually, 3 times per second, when the frontend is locked).
510 That warrants that we won't miss to collect a counter and increment the
511 monotonic stats at the right time.
513 Digital TV Frontend functions and types
514 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
516 .. kernel-doc:: drivers/media/dvb-core/dvb_frontend.h
519 Digital TV Demux kABI
520 ---------------------
525 The Kernel Digital TV Demux kABI defines a driver-internal interface for
526 registering low-level, hardware specific driver to a hardware independent
527 demux layer. It is only of interest for Digital TV device driver writers.
528 The header file for this kABI is named demux.h and located in
529 drivers/media/dvb-core.
531 The demux kABI should be implemented for each demux in the system. It is
532 used to select the TS source of a demux and to manage the demux resources.
533 When the demux client allocates a resource via the demux kABI, it receives
534 a pointer to the kABI of that resource.
536 Each demux receives its TS input from a DVB front-end or from memory, as
537 set via this demux kABI. In a system with more than one front-end, the kABI
538 can be used to select one of the DVB front-ends as a TS source for a demux,
539 unless this is fixed in the HW platform.
541 The demux kABI only controls front-ends regarding to their connections with
542 demuxes; the kABI used to set the other front-end parameters, such as
543 tuning, are devined via the Digital TV Frontend kABI.
545 The functions that implement the abstract interface demux should be defined
546 static or module private and registered to the Demux core for external
547 access. It is not necessary to implement every function in the struct
548 &dmx_demux. For example, a demux interface might support Section filtering,
549 but not PES filtering. The kABI client is expected to check the value of any
550 function pointer before calling the function: the value of ``NULL`` means
551 that the function is not available.
553 Whenever the functions of the demux API modify shared data, the
554 possibilities of lost update and race condition problems should be
555 addressed, e.g. by protecting parts of code with mutexes.
557 Note that functions called from a bottom half context must not sleep.
558 Even a simple memory allocation without using ``GFP_ATOMIC`` can result in a
559 kernel thread being put to sleep if swapping is needed. For example, the
560 Linux Kernel calls the functions of a network device interface from a
561 bottom half context. Thus, if a demux kABI function is called from network
562 device code, the function must not sleep.
572 This kernel-space API comprises the callback functions that deliver filtered
573 data to the demux client. Unlike the other DVB kABIs, these functions are
574 provided by the client and called from the demux code.
576 The function pointers of this abstract interface are not packed into a
577 structure as in the other demux APIs, because the callback functions are
578 registered and used independent of each other. As an example, it is possible
579 for the API client to provide several callback functions for receiving TS
580 packets and no callbacks for PES packets or sections.
582 The functions that implement the callback API need not be re-entrant: when
583 a demux driver calls one of these functions, the driver is not allowed to
584 call the function again before the original call returns. If a callback is
585 triggered by a hardware interrupt, it is recommended to use the Linux
586 bottom half mechanism or start a tasklet instead of making the callback
587 function call directly from a hardware interrupt.
589 This mechanism is implemented by :c:func:`dmx_ts_cb()` and :c:func:`dmx_section_cb()`
592 .. kernel-doc:: drivers/media/dvb-core/demux.h
594 Digital TV Conditional Access kABI
595 ----------------------------------
597 .. kernel-doc:: drivers/media/dvb-core/dvb_ca_en50221.h