0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 Digital TV Demux kABI
0004 ---------------------
0005
0006 Digital TV Demux
0007 ~~~~~~~~~~~~~~~~
0008
0009 The Kernel Digital TV Demux kABI defines a driver-internal interface for
0010 registering low-level, hardware specific driver to a hardware independent
0011 demux layer. It is only of interest for Digital TV device driver writers.
0012 The header file for this kABI is named ``demux.h`` and located in
0013 ``include/media``.
0014
0015 The demux kABI should be implemented for each demux in the system. It is
0016 used to select the TS source of a demux and to manage the demux resources.
0017 When the demux client allocates a resource via the demux kABI, it receives
0018 a pointer to the kABI of that resource.
0019
0020 Each demux receives its TS input from a DVB front-end or from memory, as
0021 set via this demux kABI. In a system with more than one front-end, the kABI
0022 can be used to select one of the DVB front-ends as a TS source for a demux,
0023 unless this is fixed in the HW platform.
0024
0025 The demux kABI only controls front-ends regarding to their connections with
0026 demuxes; the kABI used to set the other front-end parameters, such as
0027 tuning, are devined via the Digital TV Frontend kABI.
0028
0029 The functions that implement the abstract interface demux should be defined
0030 static or module private and registered to the Demux core for external
0031 access. It is not necessary to implement every function in the struct
0032 :c:type:`dmx_demux`. For example, a demux interface might support Section filtering,
0033 but not PES filtering. The kABI client is expected to check the value of any
0034 function pointer before calling the function: the value of ``NULL`` means
0035 that the function is not available.
0036
0037 Whenever the functions of the demux API modify shared data, the
0038 possibilities of lost update and race condition problems should be
0039 addressed, e.g. by protecting parts of code with mutexes.
0040
0041 Note that functions called from a bottom half context must not sleep.
0042 Even a simple memory allocation without using ``GFP_ATOMIC`` can result in a
0043 kernel thread being put to sleep if swapping is needed. For example, the
0044 Linux Kernel calls the functions of a network device interface from a
0045 bottom half context. Thus, if a demux kABI function is called from network
0046 device code, the function must not sleep.
0047
0048 Demux Callback API
0049 ~~~~~~~~~~~~~~~~~~
0050
0051 This kernel-space API comprises the callback functions that deliver filtered
0052 data to the demux client. Unlike the other DVB kABIs, these functions are
0053 provided by the client and called from the demux code.
0054
0055 The function pointers of this abstract interface are not packed into a
0056 structure as in the other demux APIs, because the callback functions are
0057 registered and used independent of each other. As an example, it is possible
0058 for the API client to provide several callback functions for receiving TS
0059 packets and no callbacks for PES packets or sections.
0060
0061 The functions that implement the callback API need not be re-entrant: when
0062 a demux driver calls one of these functions, the driver is not allowed to
0063 call the function again before the original call returns. If a callback is
0064 triggered by a hardware interrupt, it is recommended to use the Linux
0065 bottom half mechanism or start a tasklet instead of making the callback
0066 function call directly from a hardware interrupt.
0067
0068 This mechanism is implemented by :c:func:`dmx_ts_cb()` and :c:func:`dmx_section_cb()`
0069 callbacks.
0070
0071 Digital TV Demux device registration functions and data structures
0072 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0073
0074 .. kernel-doc:: include/media/dmxdev.h
0075
0076 High-level Digital TV demux interface
0077 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0078
0079 .. kernel-doc:: include/media/dvb_demux.h
0080
0081 Driver-internal low-level hardware specific driver demux interface
0082 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0083
0084 .. kernel-doc:: include/media/demux.h
