1Digital TV (DVB) devices 2------------------------ 3 4Digital TV Common functions 5--------------------------- 6 7.. kernel-doc:: drivers/media/dvb-core/dvb_math.h 8 9.. kernel-doc:: drivers/media/dvb-core/dvbdev.h 10 11 12 13.. kernel-doc:: drivers/media/dvb-core/dvb_math.h 14 :export: drivers/media/dvb-core/dvb_math.c 15 16.. kernel-doc:: drivers/media/dvb-core/dvbdev.h 17 :export: drivers/media/dvb-core/dvbdev.c 18 19Digital TV Ring buffer 20---------------------- 21 22Those routines implement ring buffers used to handle digital TV data and 23copy it from/to userspace. 24 25.. note:: 26 27 1) For performance reasons read and write routines don't check buffer sizes 28 and/or number of bytes free/available. This has to be done before these 29 routines are called. For example: 30 31 .. code-block:: c 32 33 /* write @buflen: bytes */ 34 free = dvb_ringbuffer_free(rbuf); 35 if (free >= buflen) 36 count = dvb_ringbuffer_write(rbuf, buffer, buflen); 37 else 38 /* do something */ 39 40 /* read min. 1000, max. @bufsize: bytes */ 41 avail = dvb_ringbuffer_avail(rbuf); 42 if (avail >= 1000) 43 count = dvb_ringbuffer_read(rbuf, buffer, min(avail, bufsize)); 44 else 45 /* do something */ 46 47 2) If there is exactly one reader and one writer, there is no need 48 to lock read or write operations. 49 Two or more readers must be locked against each other. 50 Flushing the buffer counts as a read operation. 51 Resetting the buffer counts as a read and write operation. 52 Two or more writers must be locked against each other. 53 54.. kernel-doc:: drivers/media/dvb-core/dvb_ringbuffer.h 55 56 57Digital TV Frontend kABI 58------------------------ 59 60Digital TV Frontend 61~~~~~~~~~~~~~~~~~~~ 62 63The Digital TV Frontend kABI defines a driver-internal interface for 64registering low-level, hardware specific driver to a hardware independent 65frontend layer. It is only of interest for Digital TV device driver writers. 66The header file for this API is named dvb_frontend.h and located in 67drivers/media/dvb-core. 68 69Before using the Digital TV frontend core, the bridge driver should attach 70the frontend demod, tuner and SEC devices and call 71:c:func:`dvb_register_frontend()`, 72in order to register the new frontend at the subsystem. At device 73detach/removal, the bridge driver should call 74:c:func:`dvb_unregister_frontend()` to 75remove the frontend from the core and then :c:func:`dvb_frontend_detach()` 76to free the memory allocated by the frontend drivers. 77 78The drivers should also call :c:func:`dvb_frontend_suspend()` as part of 79their handler for the :c:type:`device_driver`.\ ``suspend()``, and 80:c:func:`dvb_frontend_resume()` as 81part of their handler for :c:type:`device_driver`.\ ``resume()``. 82 83A few other optional functions are provided to handle some special cases. 84 85.. kernel-doc:: drivers/media/dvb-core/dvb_frontend.h 86 87 88Digital TV Demux kABI 89--------------------- 90 91Digital TV Demux 92~~~~~~~~~~~~~~~~ 93 94The Kernel Digital TV Demux kABI defines a driver-internal interface for 95registering low-level, hardware specific driver to a hardware independent 96demux layer. It is only of interest for Digital TV device driver writers. 97The header file for this kABI is named demux.h and located in 98drivers/media/dvb-core. 99 100The demux kABI should be implemented for each demux in the system. It is 101used to select the TS source of a demux and to manage the demux resources. 102When the demux client allocates a resource via the demux kABI, it receives 103a pointer to the kABI of that resource. 104 105Each demux receives its TS input from a DVB front-end or from memory, as 106set via this demux kABI. In a system with more than one front-end, the kABI 107can be used to select one of the DVB front-ends as a TS source for a demux, 108unless this is fixed in the HW platform. 109 110The demux kABI only controls front-ends regarding to their connections with 111demuxes; the kABI used to set the other front-end parameters, such as 112tuning, are devined via the Digital TV Frontend kABI. 113 114The functions that implement the abstract interface demux should be defined 115static or module private and registered to the Demux core for external 116access. It is not necessary to implement every function in the struct 117&dmx_demux. For example, a demux interface might support Section filtering, 118but not PES filtering. The kABI client is expected to check the value of any 119function pointer before calling the function: the value of ``NULL`` means 120that the function is not available. 121 122Whenever the functions of the demux API modify shared data, the 123possibilities of lost update and race condition problems should be 124addressed, e.g. by protecting parts of code with mutexes. 125 126Note that functions called from a bottom half context must not sleep. 127Even a simple memory allocation without using ``GFP_ATOMIC`` can result in a 128kernel thread being put to sleep if swapping is needed. For example, the 129Linux Kernel calls the functions of a network device interface from a 130bottom half context. Thus, if a demux kABI function is called from network 131device code, the function must not sleep. 132 133 134 135Demux Callback API 136------------------ 137 138Demux Callback 139~~~~~~~~~~~~~~ 140 141This kernel-space API comprises the callback functions that deliver filtered 142data to the demux client. Unlike the other DVB kABIs, these functions are 143provided by the client and called from the demux code. 144 145The function pointers of this abstract interface are not packed into a 146structure as in the other demux APIs, because the callback functions are 147registered and used independent of each other. As an example, it is possible 148for the API client to provide several callback functions for receiving TS 149packets and no callbacks for PES packets or sections. 150 151The functions that implement the callback API need not be re-entrant: when 152a demux driver calls one of these functions, the driver is not allowed to 153call the function again before the original call returns. If a callback is 154triggered by a hardware interrupt, it is recommended to use the Linux 155bottom half mechanism or start a tasklet instead of making the callback 156function call directly from a hardware interrupt. 157 158This mechanism is implemented by :c:func:`dmx_ts_cb()` and :c:func:`dmx_section_cb()` 159callbacks. 160 161.. kernel-doc:: drivers/media/dvb-core/demux.h 162 163Digital TV Conditional Access kABI 164---------------------------------- 165 166.. kernel-doc:: drivers/media/dvb-core/dvb_ca_en50221.h 167