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