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-
10 registering low-level, hardware specific drive
11 frontend layer. It is only of interest for Dig
12 The header file for this API is named ``dvb_fr
13 ``include/media/``.
14
15 Demodulator driver
16 ^^^^^^^^^^^^^^^^^^
17
18 The demodulator driver is responsible for talk
19 hardware. Such driver should implement :c:type
20 tells what type of digital TV standards are su
21 series of functions that allow the DVB core to
22 the code under ``include/media/dvb_frontend.c`
23
24 A typical example of such struct in a driver `
25
26 static struct dvb_frontend_ops foo_ops
27 .delsys = { SYS_DVBT, SYS_DVBT
28 .info = {
29 .name = "foo DVB-T/T
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_AUT
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_AUT
43 FE_CAN_TRANSMI
44 FE_CAN_GUARD_I
45 FE_CAN_HIERARC
46 FE_CAN_MUTE_TS
47 FE_CAN_2G_MODU
48 .frequency_min = 42000
49 .frequency_max = 10020
50 .symbol_rate_min = 870
51 .symbol_rate_max = 117
52 },
53 .init = foo_init,
54 .sleep = foo_sleep,
55 .release = foo_release,
56 .set_frontend = foo_set_fronte
57 .get_frontend = foo_get_fronte
58 .read_status = foo_get_status_
59 .tune = foo_tune,
60 .i2c_gate_ctrl = foo_i2c_gate_
61 .get_frontend_algo = foo_get_a
62 };
63
64 A typical example of such struct in a driver `
65 Satellite TV reception is::
66
67 static const struct dvb_frontend_ops b
68 .delsys = { SYS_DVBS, SYS_DVBS
69 .info = {
70 .name = "Bar
71 .frequency_min = 5000
72 .frequency_max = 2500
73 .frequency_stepsize
74 .symbol_rate_min = 100
75 .symbol_rate_max = 450
76 .symbol_rate_tolerance
77 .caps = FE_CAN_INVERSI
78 FE_CAN_FEC_AUT
79 FE_CAN_QPSK,
80 },
81 .init = bar_init,
82 .sleep = bar_sleep,
83 .release = bar_release,
84 .set_frontend = bar_set_fronte
85 .get_frontend = bar_get_fronte
86 .read_status = bar_get_status_
87 .i2c_gate_ctrl = bar_i2c_gate_
88 .get_frontend_algo = bar_get_a
89 .tune = bar_tune,
90
91 /* Satellite-specific */
92 .diseqc_send_master_cmd = bar_
93 .diseqc_send_burst = bar_send_
94 .set_tone = bar_set_tone,
95 .set_voltage = bar_set_voltage
96 };
97
98 .. note::
99
100 #) For satellite digital TV standards (DVB-
101 frequencies are specified in kHz, while,
102 standards, they're specified in Hz. Due
103 supports both types, you'll need to have
104 :c:type:`dvb_frontend_ops` structures, o
105 #) The ``.i2c_gate_ctrl`` field is present
106 allows controlling an I2C gate (either d
107 in order to remove the tuner from the I2
108 tuned.
109 #) All new drivers should implement the
110 :ref:`DVBv5 statistics <dvbv5_stats>` vi
111 Yet, there are a number of callbacks mea
112 signal strength, S/N and UCB. Those are
113 compatibility with legacy applications t
114 API. Implementing those callbacks are op
115 removed in the future, after we have all
116 DVBv5 stats.
117 #) Other callbacks are required for satelli
118 control LNBf and DiSEqC: ``.diseqc_send_
119 ``.diseqc_send_burst``, ``.set_tone``, `
120
121 .. |delta| unicode:: U+00394
122
123 The ``include/media/dvb_frontend.c`` has a ker
124 responsible for tuning the device. It supports
125 detect a channel, as defined at enum :c:func:`
126
127 The algorithm to be used is obtained via ``.ge
128 doesn't fill its field at struct dvb_frontend_
129 ``DVBFE_ALGO_SW``, meaning that the dvb-core w
130 e. g. it will try first to use the specified c
131 then, it will do ``f`` + |delta|, ``f`` - |del
132 ``f`` - 2 x |delta| and so on.
133
134 If the hardware has internally a some sort of
135 define a ``.get_frontend_algo`` function that
136
137 .. note::
138
139 The core frontend support also supports
140 a third type (``DVBFE_ALGO_CUSTOM``), in or
141 define its own hardware-assisted algorithm.
142 use it nowadays. Using ``DVBFE_ALGO_CUSTOM`
143 function callbacks at struct dvb_frontend_o
144
145 Attaching frontend driver to the bridge driver
146 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
147
148 Before using the Digital TV frontend core, the
149 the frontend demod, tuner and SEC devices and
150 :c:func:`dvb_register_frontend()`,
151 in order to register the new frontend at the s
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:
155 to free the memory allocated by the frontend d
156
157 The drivers should also call :c:func:`dvb_fron
158 their handler for the :c:type:`device_driver`.
159 :c:func:`dvb_frontend_resume()` as
160 part of their handler for :c:type:`device_driv
161
162 A few other optional functions are provided to
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>` m
174 and measuring the quality of service.
175
176 For each statistics measurement, the driver sh
177 or ``FE_SCALE_NOT_AVAILABLE`` if the statistic
178 time. Drivers should also provide the number o
179 that's usually 1 for most video standards [#f2
180
181 Drivers should initialize each statistic count
182 scale at its init code. For example, if the fr
183 strength, it should have, on its init code::
184
185 struct dtv_frontend_properties *c = &s
186
187 c->strength.len = 1;
188 c->strength.stat[0].scale = FE_SCALE_N
189
190 And, when the statistics got updated, set the
191
192 c->strength.stat[0].scale = FE_SCALE_D
193 c->strength.stat[0].uvalue = strength;
194
195 .. [#f2] For ISDB-T, it may provide both a glo
196 set of statistics. On such cases, len shoul
197 value corresponds to the global stat; the o
198
199 - c->cnr.stat[0] for global S/N carrier rat
200 - c->cnr.stat[1] for Layer A S/N carrier ra
201 - c->cnr.stat[2] for layer B S/N carrier ra
202 - c->cnr.stat[3] for layer C S/N carrier ra
203
204 .. note:: Please prefer to use ``FE_SCALE_DECI
205 ``FE_SCALE_RELATIVE`` for signal strength a
206
207 Groups of statistics
208 ^^^^^^^^^^^^^^^^^^^^
209
210 There are several groups of statistics current
211
212 Signal strength (:ref:`DTV-STAT-SIGNAL-STRENGT
213 - Measures the signal strength level at the
214 demod.
215
216 - Typically obtained from the gain applied t
217 in order to detect the carrier. When no ca
218 at the maximum value (so, strength is on i
219
220 - As the gain is visible through the set of
221 typically, this statistics is always avail
222
223 - Drivers should try to make it available al
224 can be used when adjusting an antenna posi
225 at the cabling.
226
227 .. [#f3] On a few devices, the gain keeps fl
228 On such devices, strength report should c
229 detected at the tuner (``FE_HAS_CARRIER``
230 and otherwise return the lowest possible
231
232 Carrier Signal to Noise ratio (:ref:`DTV-STAT-
233 - Signal to Noise ratio for the main carrier
234
235 - Signal to Noise measurement depends on the
236 available when the main carrier is detecte
237 measurement usually comes from the tuner (
238 see :c:type:`fe_status`).
239
240 On other devices, it requires inner FEC de
241 as the frontend measures it indirectly fro
242 ``FE_HAS_VITERBI``, see :c:type:`fe_status
243
244 Having it available after inner FEC is mor
245
246 Bit counts post-FEC (:ref:`DTV-STAT-POST-ERROR
247 - Those counters measure the number of bits
248 the forward error correction (FEC) on the
249 (after Viterbi, LDPC or other inner code).
250
251 - Due to its nature, those statistics depend
252 (e. g. after ``FE_HAS_SYNC`` or after ``FE
253 see :c:type:`fe_status`).
254
255 Bit counts pre-FEC (:ref:`DTV-STAT-PRE-ERROR-B
256 - Those counters measure the number of bits
257 the forward error correction (FEC) on the
258 (before Viterbi, LDPC or other inner code)
259
260 - Not all frontends provide this kind of sta
261
262 - Due to its nature, those statistics depend
263 after ``FE_HAS_VITERBI``, see :c:type:`fe_
264
265 Block counts (:ref:`DTV-STAT-ERROR-BLOCK-COUNT
266 - Those counters measure the number of block
267 the forward error correction (FEC) on the
268 (before Viterbi, LDPC or other inner code)
269
270 - Due to its nature, those statistics depend
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
275 collected from the hardware.
276
277 A typical example of the logic that handle sta
278
279 static int foo_get_status_and_stats(st
280 {
281 struct foo_state *state = fe->
282 struct dtv_frontend_properties
283
284 int rc;
285 enum fe_status *status;
286
287 /* Both status and strength ar
288 rc = foo_read_status(fe, &stat
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_CARR
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
305 if (!(fe->status & FE_HAS_VITE
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
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 o
322 /* ... */
323 .read_status = foo_get_status_
324 };
325
326 Statistics collection
327 ^^^^^^^^^^^^^^^^^^^^^
328
329 On almost all frontend hardware, the bit and b
330 the hardware after a certain amount of time or
331 counter reaches a certain value (usually progr
332 every 1000 ms or after receiving 1,000,000 bit
333
334 So, if you read the registers too soon, you'll
335 value as in the previous reading, causing the
336 incremented too often.
337
338 Drivers should take the responsibility to avoi
339 can be done using two approaches:
340
341 if the driver have a bit that indicates when a
342 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
343
344 Driver should check such bit before making the
345
346 An example of such behavior can be found at th
347 from mb86a20s driver's logic)::
348
349 static int foo_get_pre_ber(struct dvb_
350 {
351 struct foo_state *state = fe->
352 struct dtv_frontend_properties
353 int rc, bit_error;
354
355 /* Check if the BER measures a
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
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
374 c->pre_bit_error.stat[0].uvalu
375 c->pre_bit_count.stat[0].scale
376 c->pre_bit_count.stat[0].uvalu
377
378 return 0;
379 }
380
381 If the driver doesn't provide a statistics ava
382 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
383
384 A few devices, however, may not provide a way
385 available (or the way to check it is unknown).
386 a way to directly read the total number of bit
387
388 On those devices, the driver need to ensure th
389 the register too often and/or estimate the tot
390
391 On such drivers, a typical routine to get stat
392 (adapted from dib8000 driver's logic)::
393
394 struct foo_state {
395 /* ... */
396
397 unsigned long per_jiffies_stat
398 }
399
400 static int foo_get_pre_ber(struct dvb_
401 {
402 struct foo_state *state = fe->
403 struct dtv_frontend_properties
404 int rc, bit_error;
405 u64 bits;
406
407 /* Check if time for stats was
408 if (!time_after(jiffies, state
409 return 0;
410
411 /* Next stat should be collect
412 state->per_jiffies_stats = jif
413
414 /* Read Bit Error Count */
415 bit_error = foo_read_u32(state
416 if (bit_error < 0)
417 return bit_error;
418
419 /*
420 * On this particular frontend
421 * would provide the number of
422 * some function would calcula
423 */
424 bits = get_number_of_bits_per_
425
426 c->pre_bit_error.stat[0].scale
427 c->pre_bit_error.stat[0].uvalu
428 c->pre_bit_count.stat[0].scale
429 c->pre_bit_count.stat[0].uvalu
430
431 return 0;
432 }
433
434 Please notice that, on both cases, we're getti
435 :c:type:`dvb_frontend_ops` ``.read_status`` ca
436 the frontend core will automatically call this
437 (usually, 3 times per second, when the fronten
438
439 That warrants that we won't miss to collect a
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
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.