Documentation/media/kapi/dtv-core.rst

   1 Digital TV (DVB) devices
   2 ------------------------
   3
   4 Digital 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
  19 Digital TV Ring buffer
  20 ----------------------
  21
  22 Those routines implement ring buffers used to handle digital TV data and
  23 copy 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
  57 Digital TV Frontend kABI
  58 ------------------------
  59
  60 Digital TV Frontend
  61 ~~~~~~~~~~~~~~~~~~~
  62
  63 The Digital TV Frontend kABI defines a driver-internal interface for
  64 registering low-level, hardware specific driver to a hardware independent
  65 frontend layer. It is only of interest for Digital TV device driver writers.
  66 The header file for this API is named dvb_frontend.h and located in
  67 drivers/media/dvb-core.
  68
  69 Before using the Digital TV frontend core, the bridge driver should attach
  70 the frontend demod, tuner and SEC devices and call
  71 :c:func:`dvb_register_frontend()`,
  72 in order to register the new frontend at the subsystem. At device
  73 detach/removal, the bridge driver should call
  74 :c:func:`dvb_unregister_frontend()` to
  75 remove the frontend from the core and then :c:func:`dvb_frontend_detach()`
  76 to free the memory allocated by the frontend drivers.
  77
  78 The drivers should also call :c:func:`dvb_frontend_suspend()` as part of
  79 their handler for the :c:type:`device_driver`.\ ``suspend()``, and
  80 :c:func:`dvb_frontend_resume()` as
  81 part of their handler for :c:type:`device_driver`.\ ``resume()``.
  82
  83 A few other optional functions are provided to handle some special cases.
  84
  85 .. kernel-doc:: drivers/media/dvb-core/dvb_frontend.h
  86
  87
  88 Digital TV Demux kABI
  89 ---------------------
  90
  91 Digital TV Demux
  92 ~~~~~~~~~~~~~~~~
  93
  94 The Kernel Digital TV Demux kABI defines a driver-internal interface for
  95 registering low-level, hardware specific driver to a hardware independent
  96 demux layer. It is only of interest for Digital TV device driver writers.
  97 The header file for this kABI is named demux.h and located in
  98 drivers/media/dvb-core.
  99
 100 The demux kABI should be implemented for each demux in the system. It is
 101 used to select the TS source of a demux and to manage the demux resources.
 102 When the demux client allocates a resource via the demux kABI, it receives
 103 a pointer to the kABI of that resource.
 104
 105 Each demux receives its TS input from a DVB front-end or from memory, as
 106 set via this demux kABI. In a system with more than one front-end, the kABI
 107 can be used to select one of the DVB front-ends as a TS source for a demux,
 108 unless this is fixed in the HW platform.
 109
 110 The demux kABI only controls front-ends regarding to their connections with
 111 demuxes; the kABI used to set the other front-end parameters, such as
 112 tuning, are devined via the Digital TV Frontend kABI.
 113
 114 The functions that implement the abstract interface demux should be defined
 115 static or module private and registered to the Demux core for external
 116 access. It is not necessary to implement every function in the struct
 117 &dmx_demux. For example, a demux interface might support Section filtering,
 118 but not PES filtering. The kABI client is expected to check the value of any
 119 function pointer before calling the function: the value of ``NULL`` means
 120 that the function is not available.
 121
 122 Whenever the functions of the demux API modify shared data, the
 123 possibilities of lost update and race condition problems should be
 124 addressed, e.g. by protecting parts of code with mutexes.
 125
 126 Note that functions called from a bottom half context must not sleep.
 127 Even a simple memory allocation without using ``GFP_ATOMIC`` can result in a
 128 kernel thread being put to sleep if swapping is needed. For example, the
 129 Linux Kernel calls the functions of a network device interface from a
 130 bottom half context. Thus, if a demux kABI function is called from network
 131 device code, the function must not sleep.
 132
 133
 134
 135 Demux Callback API
 136 ------------------
 137
 138 Demux Callback
 139 ~~~~~~~~~~~~~~
 140
 141 This kernel-space API comprises the callback functions that deliver filtered
 142 data to the demux client. Unlike the other DVB kABIs, these functions are
 143 provided by the client and called from the demux code.
 144
 145 The function pointers of this abstract interface are not packed into a
 146 structure as in the other demux APIs, because the callback functions are
 147 registered and used independent of each other. As an example, it is possible
 148 for the API client to provide several callback functions for receiving TS
 149 packets and no callbacks for PES packets or sections.
 150
 151 The functions that implement the callback API need not be re-entrant: when
 152 a demux driver calls one of these functions, the driver is not allowed to
 153 call the function again before the original call returns. If a callback is
 154 triggered by a hardware interrupt, it is recommended to use the Linux
 155 bottom half mechanism or start a tasklet instead of making the callback
 156 function call directly from a hardware interrupt.
 157
 158 This mechanism is implemented by :c:func:`dmx_ts_cb()` and :c:func:`dmx_section_cb()`
 159 callbacks.
 160
 161 .. kernel-doc:: drivers/media/dvb-core/demux.h
 162
 163 Digital TV Conditional Access kABI
 164 ----------------------------------
 165
 166 .. kernel-doc:: drivers/media/dvb-core/dvb_ca_en50221.h