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