]>
Commit | Line | Data |
---|---|---|
f2ac8ce8 MCC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
5b3b8c81 MCC |
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 | |
fada1935 | 13 | ``include/media/``. |
5b3b8c81 MCC |
14 | |
15 | Demodulator driver | |
16 | ^^^^^^^^^^^^^^^^^^ | |
17 | ||
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 | |
fada1935 | 22 | the code under ``include/media/dvb_frontend.c``. |
5b3b8c81 MCC |
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 | ||
fada1935 | 123 | The ``include/media/dvb_frontend.c`` has a kernel thread with is |
b2fc98fc | 124 | responsible for tuning the device. It supports multiple algorithms to |
5b3b8c81 MCC |
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 :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. | |
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 :c:type:`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 this 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 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, 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 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 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 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 collect | |
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 | |
adf48e3f | 331 | counter reaches a certain value (usually programmable), for example, on |
5b3b8c81 MCC |
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 | ||
fada1935 | 445 | .. kernel-doc:: include/media/dvb_frontend.h |