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