1.. SPDX-License-Identifier: GPL-2.0
2
3Digital TV Demux kABI
4---------------------
5
6Digital TV Demux
7~~~~~~~~~~~~~~~~
8
9The Kernel Digital TV Demux kABI defines a driver-internal interface for
10registering low-level, hardware specific driver to a hardware independent
11demux layer. It is only of interest for Digital TV device driver writers.
12The header file for this kABI is named ``demux.h`` and located in
13``include/media``.
14
15The demux kABI should be implemented for each demux in the system. It is
16used to select the TS source of a demux and to manage the demux resources.
17When the demux client allocates a resource via the demux kABI, it receives
18a pointer to the kABI of that resource.
19
20Each demux receives its TS input from a DVB front-end or from memory, as
21set via this demux kABI. In a system with more than one front-end, the kABI
22can be used to select one of the DVB front-ends as a TS source for a demux,
23unless this is fixed in the HW platform.
24
25The demux kABI only controls front-ends regarding to their connections with
26demuxes; the kABI used to set the other front-end parameters, such as
27tuning, are defined via the Digital TV Frontend kABI.
28
29The functions that implement the abstract interface demux should be defined
30static or module private and registered to the Demux core for external
31access. It is not necessary to implement every function in the struct
32:c:type:`dmx_demux`. For example, a demux interface might support Section filtering,
33but not PES filtering. The kABI client is expected to check the value of any
34function pointer before calling the function: the value of ``NULL`` means
35that the function is not available.
36
37Whenever the functions of the demux API modify shared data, the
38possibilities of lost update and race condition problems should be
39addressed, e.g. by protecting parts of code with mutexes.
40
41Note that functions called from a bottom half context must not sleep.
42Even a simple memory allocation without using ``GFP_ATOMIC`` can result in a
43kernel thread being put to sleep if swapping is needed. For example, the
44Linux Kernel calls the functions of a network device interface from a
45bottom half context. Thus, if a demux kABI function is called from network
46device code, the function must not sleep.
47
48Demux Callback API
49~~~~~~~~~~~~~~~~~~
50
51This kernel-space API comprises the callback functions that deliver filtered
52data to the demux client. Unlike the other DVB kABIs, these functions are
53provided by the client and called from the demux code.
54
55The function pointers of this abstract interface are not packed into a
56structure as in the other demux APIs, because the callback functions are
57registered and used independent of each other. As an example, it is possible
58for the API client to provide several callback functions for receiving TS
59packets and no callbacks for PES packets or sections.
60
61The functions that implement the callback API need not be re-entrant: when
62a demux driver calls one of these functions, the driver is not allowed to
63call the function again before the original call returns. If a callback is
64triggered by a hardware interrupt, it is recommended to use the Linux
65bottom half mechanism or start a tasklet instead of making the callback
66function call directly from a hardware interrupt.
67
68This mechanism is implemented by :c:func:`dmx_ts_cb()` and :c:func:`dmx_section_cb()`
69callbacks.
70
71Digital TV Demux device registration functions and data structures
72~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
73
74.. kernel-doc:: include/media/dmxdev.h
75
76High-level Digital TV demux interface
77~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
78
79.. kernel-doc:: include/media/dvb_demux.h
80
81Driver-internal low-level hardware specific driver demux interface
82~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
83
84.. kernel-doc:: include/media/demux.h
85