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