| blob | fbc5517c8d5a85327800b75615e2a6a7c8e39400 |
1 .. SPDX-License-Identifier: GPL-2.0
3 Digital TV Frontend kABI
4 ------------------------
6 Digital TV Frontend
7 ~~~~~~~~~~~~~~~~~~~
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/``.
15 Demodulator driver
16 ^^^^^^^^^^^^^^^^^^
18 The demodulator driver is responsible to talk with the decoding part of the
19 hardware. Such driver should implement :c:type:`dvb_frontend_ops`, with
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``.
24 A typical example of such struct in a driver ``foo`` is::
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 };
64 A typical example of such struct in a driver ``bar`` meant to be used on
65 Satellite TV reception is::
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,
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 };
98 .. note::
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``.
121 .. |delta| unicode:: U+00394
123 The ``include/media/dvb_frontend.c`` has a kernel thread with is
124 responsible for tuning the device. It supports multiple algorithms to
125 detect a channel, as defined at enum :c:func:`dvbfe_algo`.
127 The algorithm to be used is obtained via ``.get_frontend_algo``. If the driver
128 doesn't fill its field at struct :c:type:`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.
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``.
137 .. note::
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 :c:type:`dvb_frontend_ops`.
145 Attaching frontend driver to the bridge driver
146 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
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()``.
162 A few other optional functions are provided to handle some special cases.
164 .. _dvbv5_stats:
166 Digital TV Frontend statistics
167 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
169 Introduction
170 ^^^^^^^^^^^^
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.
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]_.
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::
185 struct dtv_frontend_properties *c = &state->fe.dtv_property_cache;
187 c->strength.len = 1;
188 c->strength.stat[0].scale = FE_SCALE_NOT_AVAILABLE;
190 And, when the statistics got updated, set the scale::
192 c->strength.stat[0].scale = FE_SCALE_DECIBEL;
193 c->strength.stat[0].uvalue = strength;
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.:
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.
204 .. note:: Please prefer to use ``FE_SCALE_DECIBEL`` instead of
205 ``FE_SCALE_RELATIVE`` for signal strength and CNR measurements.
207 Groups of statistics
208 ^^^^^^^^^^^^^^^^^^^^
210 There are several groups of statistics currently supported:
212 Signal strength (:ref:`DTV-STAT-SIGNAL-STRENGTH`)
213 - Measures the signal strength level at the analog part of the tuner or
214 demod.
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).
220 - As the gain is visible through the set of registers that adjust the gain,
221 typically, this statistics is always available [#f3]_.
223 - Drivers should try to make it available all the times, as this statistics
224 can be used when adjusting an antenna position and to check for troubles
225 at the cabling.
227 .. [#f3] On a few devices, the gain keeps floating if 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.
232 Carrier Signal to Noise ratio (:ref:`DTV-STAT-CNR`)
233 - Signal to Noise ratio for the main carrier.
235 - Signal to Noise measurement depends on the device. On some hardware, 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`).
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`).
244 Having it available after inner FEC is more common.
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 errors after
248 the forward error correction (FEC) on the inner coding block
249 (after Viterbi, LDPC or other inner code).
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`).
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 errors before
257 the forward error correction (FEC) on the inner coding block
258 (before Viterbi, LDPC or other inner code).
260 - Not all frontends provide this kind of statistics.
262 - Due to its nature, those statistics depend on inner coding lock (e. g.
263 after ``FE_HAS_VITERBI``, see :c:type:`fe_status`).
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 errors after
267 the forward error correction (FEC) on the inner coding block
268 (before Viterbi, LDPC or other inner code).
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`).
274 .. note:: All counters should be monotonically increased as they're
275 collected from the hardware.
277 A typical example of the logic that handle status and statistics is::
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;
284 int rc;
285 enum fe_status *status;
287 /* Both status and strength are always available */
288 rc = foo_read_status(fe, &status);
289 if (rc < 0)
290 return rc;
292 rc = foo_read_strength(fe);
293 if (rc < 0)
294 return rc;
296 /* Check if CNR is available */
297 if (!(fe->status & FE_HAS_CARRIER))
298 return 0;
300 rc = foo_read_cnr(fe);
301 if (rc < 0)
302 return rc;
304 /* Check if pre-BER stats are available */
305 if (!(fe->status & FE_HAS_VITERBI))
306 return 0;
308 rc = foo_get_pre_ber(fe);
309 if (rc < 0)
310 return rc;
312 /* Check if post-BER stats are available */
313 if (!(fe->status & FE_HAS_SYNC))
314 return 0;
316 rc = foo_get_post_ber(fe);
317 if (rc < 0)
318 return rc;
319 }
321 static const struct dvb_frontend_ops ops = {
322 /* ... */
323 .read_status = foo_get_status_and_stats,
324 };
326 Statistics collect
327 ^^^^^^^^^^^^^^^^^^
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.
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.
338 Drivers should take the responsibility to avoid too often reads. That
339 can be done using two approaches:
341 if the driver have a bit that indicates when a collected data is ready
342 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
344 Driver should check such bit before making the statistics available.
346 An example of such behavior can be found at this code snippet (adapted
347 from mb86a20s driver's logic)::
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;
355 /* Check if the BER measures are already available */
356 rc = foo_read_u8(state, 0x54);
357 if (rc < 0)
358 return rc;
360 if (!rc)
361 return 0;
363 /* Read Bit Error Count */
364 bit_error = foo_read_u32(state, 0x55);
365 if (bit_error < 0)
366 return bit_error;
368 /* Read Total Bit Count */
369 rc = foo_read_u32(state, 0x51);
370 if (rc < 0)
371 return rc;
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;
378 return 0;
379 }
381 If the driver doesn't provide a statistics available check bit
382 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
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.
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.
391 On such drivers, a typical routine to get statistics would be like
392 (adapted from dib8000 driver's logic)::
394 struct foo_state {
395 /* ... */
397 unsigned long per_jiffies_stats;
398 }
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;
407 /* Check if time for stats was elapsed */
408 if (!time_after(jiffies, state->per_jiffies_stats))
409 return 0;
411 /* Next stat should be collected in 1000 ms */
412 state->per_jiffies_stats = jiffies + msecs_to_jiffies(1000);
414 /* Read Bit Error Count */
415 bit_error = foo_read_u32(state, 0x55);
416 if (bit_error < 0)
417 return bit_error;
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);
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;
431 return 0;
432 }
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).
439 That warrants that we won't miss to collect a counter and increment the
440 monotonic stats at the right time.
442 Digital TV Frontend functions and types
443 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
445 .. kernel-doc:: include/media/dvb_frontend.h