85 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3Digital TV Demux kABI4---------------------5 6Digital TV Demux7~~~~~~~~~~~~~~~~8 9The Kernel Digital TV Demux kABI defines a driver-internal interface for10registering low-level, hardware specific driver to a hardware independent11demux layer. It is only of interest for Digital TV device driver writers.12The header file for this kABI is named ``demux.h`` and located in13``include/media``.14 15The demux kABI should be implemented for each demux in the system. It is16used 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 receives18a pointer to the kABI of that resource.19 20Each demux receives its TS input from a DVB front-end or from memory, as21set via this demux kABI. In a system with more than one front-end, the kABI22can 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 with26demuxes; the kABI used to set the other front-end parameters, such as27tuning, are defined via the Digital TV Frontend kABI.28 29The functions that implement the abstract interface demux should be defined30static or module private and registered to the Demux core for external31access. It is not necessary to implement every function in the struct32: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 any34function pointer before calling the function: the value of ``NULL`` means35that the function is not available.36 37Whenever the functions of the demux API modify shared data, the38possibilities of lost update and race condition problems should be39addressed, 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 a43kernel thread being put to sleep if swapping is needed. For example, the44Linux Kernel calls the functions of a network device interface from a45bottom half context. Thus, if a demux kABI function is called from network46device code, the function must not sleep.47 48Demux Callback API49~~~~~~~~~~~~~~~~~~50 51This kernel-space API comprises the callback functions that deliver filtered52data to the demux client. Unlike the other DVB kABIs, these functions are53provided by the client and called from the demux code.54 55The function pointers of this abstract interface are not packed into a56structure as in the other demux APIs, because the callback functions are57registered and used independent of each other. As an example, it is possible58for the API client to provide several callback functions for receiving TS59packets and no callbacks for PES packets or sections.60 61The functions that implement the callback API need not be re-entrant: when62a demux driver calls one of these functions, the driver is not allowed to63call the function again before the original call returns. If a callback is64triggered by a hardware interrupt, it is recommended to use the Linux65bottom half mechanism or start a tasklet instead of making the callback66function 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 structures72~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~73 74.. kernel-doc:: include/media/dmxdev.h75 76High-level Digital TV demux interface77~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~78 79.. kernel-doc:: include/media/dvb_demux.h80 81Driver-internal low-level hardware specific driver demux interface82~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~83 84.. kernel-doc:: include/media/demux.h85