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