]>
Commit | Line | Data |
---|---|---|
684ffa2d MCC |
1 | Digital TV (DVB) devices |
2 | ------------------------ | |
3 | ||
f495ab86 MCC |
4 | Digital TV devices are implemented by several different drivers: |
5 | ||
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); | |
9 | ||
10 | - Frontend drivers that are usually implemented as two separate drivers: | |
11 | ||
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; | |
16 | ||
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]_. | |
21 | ||
22 | On most hardware, the frontend drivers talk with the bridge driver using an | |
23 | I2C bus. | |
24 | ||
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. | |
28 | ||
684ffa2d MCC |
29 | Digital TV Common functions |
30 | --------------------------- | |
31 | ||
32 | .. kernel-doc:: drivers/media/dvb-core/dvb_math.h | |
33 | ||
684ffa2d MCC |
34 | .. kernel-doc:: drivers/media/dvb-core/dvbdev.h |
35 | ||
b6df512a MCC |
36 | Digital TV Ring buffer |
37 | ---------------------- | |
38 | ||
39 | Those routines implement ring buffers used to handle digital TV data and | |
40 | copy it from/to userspace. | |
41 | ||
42 | .. note:: | |
43 | ||
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: | |
47 | ||
48 | .. code-block:: c | |
49 | ||
50 | /* write @buflen: bytes */ | |
51 | free = dvb_ringbuffer_free(rbuf); | |
52 | if (free >= buflen) | |
53 | count = dvb_ringbuffer_write(rbuf, buffer, buflen); | |
54 | else | |
55 | /* do something */ | |
56 | ||
57 | /* read min. 1000, max. @bufsize: bytes */ | |
58 | avail = dvb_ringbuffer_avail(rbuf); | |
59 | if (avail >= 1000) | |
60 | count = dvb_ringbuffer_read(rbuf, buffer, min(avail, bufsize)); | |
61 | else | |
62 | /* do something */ | |
63 | ||
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. | |
70 | ||
71 | .. kernel-doc:: drivers/media/dvb-core/dvb_ringbuffer.h | |
d2f01985 MCC |
72 | |
73 | ||
684ffa2d MCC |
74 | Digital TV Frontend kABI |
75 | ------------------------ | |
76 | ||
77 | Digital TV Frontend | |
78 | ~~~~~~~~~~~~~~~~~~~ | |
79 | ||
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. | |
f91df2e4 MCC |
83 | The header file for this API is named ``dvb_frontend.h`` and located in |
84 | ``drivers/media/dvb-core``. | |
85 | ||
86 | Demodulator driver | |
87 | ^^^^^^^^^^^^^^^^^^ | |
88 | ||
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``. | |
94 | ||
95 | A typical example of such struct in a driver ``foo`` is:: | |
96 | ||
97 | static struct dvb_frontend_ops foo_ops = { | |
98 | .delsys = { SYS_DVBT, SYS_DVBT2, SYS_DVBC_ANNEX_A }, | |
99 | .info = { | |
100 | .name = "foo DVB-T/T2/C driver", | |
101 | .caps = FE_CAN_FEC_1_2 | | |
102 | FE_CAN_FEC_2_3 | | |
103 | FE_CAN_FEC_3_4 | | |
104 | FE_CAN_FEC_5_6 | | |
105 | FE_CAN_FEC_7_8 | | |
106 | FE_CAN_FEC_AUTO | | |
107 | FE_CAN_QPSK | | |
108 | FE_CAN_QAM_16 | | |
109 | FE_CAN_QAM_32 | | |
110 | FE_CAN_QAM_64 | | |
111 | FE_CAN_QAM_128 | | |
112 | FE_CAN_QAM_256 | | |
113 | FE_CAN_QAM_AUTO | | |
114 | FE_CAN_TRANSMISSION_MODE_AUTO | | |
115 | FE_CAN_GUARD_INTERVAL_AUTO | | |
116 | FE_CAN_HIERARCHY_AUTO | | |
117 | FE_CAN_MUTE_TS | | |
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 | |
123 | }, | |
124 | .init = foo_init, | |
125 | .sleep = foo_sleep, | |
126 | .release = foo_release, | |
127 | .set_frontend = foo_set_frontend, | |
128 | .get_frontend = foo_get_frontend, | |
129 | .read_status = foo_get_status_and_stats, | |
130 | .tune = foo_tune, | |
131 | .i2c_gate_ctrl = foo_i2c_gate_ctrl, | |
132 | .get_frontend_algo = foo_get_algo, | |
133 | }; | |
134 | ||
135 | A typical example of such struct in a driver ``bar`` meant to be used on | |
136 | Satellite TV reception is:: | |
137 | ||
138 | static const struct dvb_frontend_ops bar_ops = { | |
139 | .delsys = { SYS_DVBS, SYS_DVBS2 }, | |
140 | .info = { | |
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 | | |
149 | FE_CAN_FEC_AUTO | | |
150 | FE_CAN_QPSK, | |
151 | }, | |
152 | .init = bar_init, | |
153 | .sleep = bar_sleep, | |
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, | |
160 | .tune = bar_tune, | |
161 | ||
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, | |
167 | }; | |
168 | ||
169 | .. note:: | |
170 | ||
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 | |
179 | tuned. | |
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 | |
187 | DVBv5 stats. | |
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``. | |
191 | ||
192 | .. |delta| unicode:: U+00394 | |
193 | ||
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`. | |
197 | ||
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. | |
204 | ||
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``. | |
207 | ||
208 | .. note:: | |
209 | ||
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`. | |
215 | ||
216 | Attaching frontend driver to the bridge driver | |
217 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
684ffa2d MCC |
218 | |
219 | Before using the Digital TV frontend core, the bridge driver should attach | |
d2f01985 | 220 | the frontend demod, tuner and SEC devices and call |
7b998bae | 221 | :c:func:`dvb_register_frontend()`, |
684ffa2d | 222 | in order to register the new frontend at the subsystem. At device |
d2f01985 | 223 | detach/removal, the bridge driver should call |
7b998bae MCC |
224 | :c:func:`dvb_unregister_frontend()` to |
225 | remove the frontend from the core and then :c:func:`dvb_frontend_detach()` | |
d2f01985 | 226 | to free the memory allocated by the frontend drivers. |
684ffa2d | 227 | |
7b998bae | 228 | The drivers should also call :c:func:`dvb_frontend_suspend()` as part of |
d2f01985 | 229 | their handler for the :c:type:`device_driver`.\ ``suspend()``, and |
7b998bae | 230 | :c:func:`dvb_frontend_resume()` as |
d2f01985 | 231 | part of their handler for :c:type:`device_driver`.\ ``resume()``. |
684ffa2d | 232 | |
d2f01985 | 233 | A few other optional functions are provided to handle some special cases. |
684ffa2d | 234 | |
f91df2e4 MCC |
235 | .. _dvbv5_stats: |
236 | ||
77f1f992 MCC |
237 | Digital TV Frontend statistics |
238 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
239 | ||
240 | Introduction | |
241 | ^^^^^^^^^^^^ | |
242 | ||
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. | |
246 | ||
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. | |
f495ab86 | 250 | that's usually 1 for most video standards [#f2]_. |
77f1f992 MCC |
251 | |
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:: | |
255 | ||
256 | struct dtv_frontend_properties *c = &state->fe.dtv_property_cache; | |
257 | ||
258 | c->strength.len = 1; | |
259 | c->strength.stat[0].scale = FE_SCALE_NOT_AVAILABLE; | |
260 | ||
261 | And, when the statistics got updated, set the scale:: | |
262 | ||
263 | c->strength.stat[0].scale = FE_SCALE_DECIBEL; | |
264 | c->strength.stat[0].uvalue = strength; | |
265 | ||
f495ab86 | 266 | .. [#f2] For ISDB-T, it may provide both a global statistics and a per-layer |
77f1f992 MCC |
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.: | |
269 | ||
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. | |
274 | ||
275 | .. note:: Please prefer to use ``FE_SCALE_DECIBEL`` instead of | |
276 | ``FE_SCALE_RELATIVE`` for signal strength and CNR measurements. | |
277 | ||
278 | Groups of statistics | |
279 | ^^^^^^^^^^^^^^^^^^^^ | |
280 | ||
281 | There are several groups of statistics currently supported: | |
282 | ||
283 | Signal strength (:ref:`DTV-STAT-SIGNAL-STRENGTH`) | |
284 | - Measures the signal strength level at the analog part of the tuner or | |
285 | demod. | |
286 | ||
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). | |
290 | ||
291 | - As the gain is visible through the set of registers that adjust the gain, | |
f495ab86 | 292 | typically, this statistics is always available [#f3]_. |
77f1f992 MCC |
293 | |
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 | |
296 | at the cabling. | |
297 | ||
f495ab86 | 298 | .. [#f3] On a few devices, the gain keeps floating if no carrier. |
77f1f992 MCC |
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. | |
302 | ||
303 | Carrier Signal to Noise ratio (:ref:`DTV-STAT-CNR`) | |
304 | - Signal to Noise ratio for the main carrier. | |
305 | ||
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`). | |
310 | ||
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`). | |
314 | ||
315 | Having it available after inner FEC is more common. | |
316 | ||
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). | |
321 | ||
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`). | |
325 | ||
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). | |
330 | ||
331 | - Not all frontends provide this kind of statistics. | |
332 | ||
333 | - Due to its nature, those statistics depend on inner coding lock (e. g. | |
334 | after ``FE_HAS_VITERBI``, see :c:type:`fe_status`). | |
335 | ||
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). | |
340 | ||
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`). | |
344 | ||
345 | .. note:: All counters should be monotonically increased as they're | |
346 | collected from the hardware. | |
347 | ||
348 | A typical example of the logic that handle status and statistics is:: | |
349 | ||
350 | static int foo_get_status_and_stats(struct dvb_frontend *fe) | |
351 | { | |
352 | struct foo_state *state = fe->demodulator_priv; | |
353 | struct dtv_frontend_properties *c = &fe->dtv_property_cache; | |
354 | ||
355 | int rc; | |
356 | enum fe_status *status; | |
357 | ||
358 | /* Both status and strength are always available */ | |
359 | rc = foo_read_status(fe, &status); | |
360 | if (rc < 0) | |
361 | return rc; | |
362 | ||
363 | rc = foo_read_strength(fe); | |
364 | if (rc < 0) | |
365 | return rc; | |
366 | ||
367 | /* Check if CNR is available */ | |
368 | if (!(fe->status & FE_HAS_CARRIER)) | |
369 | return 0; | |
370 | ||
371 | rc = foo_read_cnr(fe); | |
372 | if (rc < 0) | |
373 | return rc; | |
374 | ||
375 | /* Check if pre-BER stats are available */ | |
376 | if (!(fe->status & FE_HAS_VITERBI)) | |
377 | return 0; | |
378 | ||
379 | rc = foo_get_pre_ber(fe); | |
380 | if (rc < 0) | |
381 | return rc; | |
382 | ||
383 | /* Check if post-BER stats are available */ | |
384 | if (!(fe->status & FE_HAS_SYNC)) | |
385 | return 0; | |
386 | ||
387 | rc = foo_get_post_ber(fe); | |
388 | if (rc < 0) | |
389 | return rc; | |
390 | } | |
391 | ||
392 | static const struct dvb_frontend_ops ops = { | |
393 | /* ... */ | |
394 | .read_status = foo_get_status_and_stats, | |
395 | }; | |
396 | ||
397 | Statistics collect | |
398 | ^^^^^^^^^^^^^^^^^^ | |
399 | ||
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. | |
404 | ||
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. | |
408 | ||
409 | Drivers should take the responsibility to avoid too often reads. That | |
410 | can be done using two approaches: | |
411 | ||
412 | if the driver have a bit that indicates when a collected data is ready | |
413 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
414 | ||
415 | Driver should check such bit before making the statistics available. | |
416 | ||
417 | An example of such behavior can be found at this code snippet (adapted | |
418 | from mb86a20s driver's logic):: | |
419 | ||
420 | static int foo_get_pre_ber(struct dvb_frontend *fe) | |
421 | { | |
422 | struct foo_state *state = fe->demodulator_priv; | |
423 | struct dtv_frontend_properties *c = &fe->dtv_property_cache; | |
424 | int rc, bit_error; | |
425 | ||
426 | /* Check if the BER measures are already available */ | |
427 | rc = foo_read_u8(state, 0x54); | |
428 | if (rc < 0) | |
429 | return rc; | |
430 | ||
431 | if (!rc) | |
432 | return 0; | |
433 | ||
434 | /* Read Bit Error Count */ | |
435 | bit_error = foo_read_u32(state, 0x55); | |
436 | if (bit_error < 0) | |
437 | return bit_error; | |
438 | ||
439 | /* Read Total Bit Count */ | |
440 | rc = foo_read_u32(state, 0x51); | |
441 | if (rc < 0) | |
442 | return rc; | |
443 | ||
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; | |
448 | ||
449 | return 0; | |
450 | } | |
451 | ||
452 | If the driver doesn't provide a statistics available check bit | |
453 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
454 | ||
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. | |
458 | ||
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. | |
461 | ||
462 | On such drivers, a typical routine to get statistics would be like | |
463 | (adapted from dib8000 driver's logic):: | |
464 | ||
465 | struct foo_state { | |
466 | /* ... */ | |
467 | ||
468 | unsigned long per_jiffies_stats; | |
469 | } | |
470 | ||
471 | static int foo_get_pre_ber(struct dvb_frontend *fe) | |
472 | { | |
473 | struct foo_state *state = fe->demodulator_priv; | |
474 | struct dtv_frontend_properties *c = &fe->dtv_property_cache; | |
475 | int rc, bit_error; | |
476 | u64 bits; | |
477 | ||
478 | /* Check if time for stats was elapsed */ | |
479 | if (!time_after(jiffies, state->per_jiffies_stats)) | |
480 | return 0; | |
481 | ||
482 | /* Next stat should be collected in 1000 ms */ | |
483 | state->per_jiffies_stats = jiffies + msecs_to_jiffies(1000); | |
484 | ||
485 | /* Read Bit Error Count */ | |
486 | bit_error = foo_read_u32(state, 0x55); | |
487 | if (bit_error < 0) | |
488 | return bit_error; | |
489 | ||
490 | /* | |
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 | |
494 | */ | |
495 | bits = get_number_of_bits_per_1000ms(fe); | |
496 | ||
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; | |
501 | ||
502 | return 0; | |
503 | } | |
504 | ||
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). | |
509 | ||
510 | That warrants that we won't miss to collect a counter and increment the | |
511 | monotonic stats at the right time. | |
512 | ||
513 | Digital TV Frontend functions and types | |
514 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
515 | ||
684ffa2d MCC |
516 | .. kernel-doc:: drivers/media/dvb-core/dvb_frontend.h |
517 | ||
518 | ||
519 | Digital TV Demux kABI | |
520 | --------------------- | |
521 | ||
522 | Digital TV Demux | |
523 | ~~~~~~~~~~~~~~~~ | |
524 | ||
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. | |
530 | ||
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. | |
535 | ||
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. | |
540 | ||
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. | |
544 | ||
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 | |
d2f01985 | 550 | function pointer before calling the function: the value of ``NULL`` means |
684ffa2d MCC |
551 | that the function is not available. |
552 | ||
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. | |
556 | ||
557 | Note that functions called from a bottom half context must not sleep. | |
d2f01985 | 558 | Even a simple memory allocation without using ``GFP_ATOMIC`` can result in a |
684ffa2d MCC |
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. | |
563 | ||
564 | ||
565 | ||
566 | Demux Callback API | |
567 | ------------------ | |
568 | ||
569 | Demux Callback | |
570 | ~~~~~~~~~~~~~~ | |
571 | ||
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. | |
575 | ||
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. | |
581 | ||
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. | |
588 | ||
1b81f010 | 589 | This mechanism is implemented by :c:func:`dmx_ts_cb()` and :c:func:`dmx_section_cb()` |
684ffa2d MCC |
590 | callbacks. |
591 | ||
684ffa2d MCC |
592 | .. kernel-doc:: drivers/media/dvb-core/demux.h |
593 | ||
684ffa2d MCC |
594 | Digital TV Conditional Access kABI |
595 | ---------------------------------- | |
596 | ||
597 | .. kernel-doc:: drivers/media/dvb-core/dvb_ca_en50221.h |