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/dvb_ringbuffer.h
  10
  11 .. kernel-doc:: drivers/media/dvb-core/dvbdev.h
  12
  13
  14
  15 .. kernel-doc:: drivers/media/dvb-core/dvb_math.h
  16    :export: drivers/media/dvb-core/dvb_math.c
  17
  18 .. kernel-doc:: drivers/media/dvb-core/dvbdev.h
  19    :export: drivers/media/dvb-core/dvbdev.c
  20
  21
  22
  23 Digital TV Frontend kABI
  24 ------------------------
  25
  26 Digital TV Frontend
  27 ~~~~~~~~~~~~~~~~~~~
  28
  29 The Digital TV Frontend kABI defines a driver-internal interface for
  30 registering low-level, hardware specific driver to a hardware independent
  31 frontend layer. It is only of interest for Digital TV device driver writers.
  32 The header file for this API is named dvb_frontend.h and located in
  33 drivers/media/dvb-core.
  34
  35 Before using the Digital TV frontend core, the bridge driver should attach
  36 the frontend demod, tuner and SEC devices and call
  37 :c:func:`dvb_register_frontend()`,
  38 in order to register the new frontend at the subsystem. At device
  39 detach/removal, the bridge driver should call
  40 :c:func:`dvb_unregister_frontend()` to
  41 remove the frontend from the core and then :c:func:`dvb_frontend_detach()`
  42 to free the memory allocated by the frontend drivers.
  43
  44 The drivers should also call :c:func:`dvb_frontend_suspend()` as part of
  45 their handler for the :c:type:`device_driver`.\ ``suspend()``, and
  46 :c:func:`dvb_frontend_resume()` as
  47 part of their handler for :c:type:`device_driver`.\ ``resume()``.
  48
  49 A few other optional functions are provided to handle some special cases.
  50
  51 .. kernel-doc:: drivers/media/dvb-core/dvb_frontend.h
  52
  53
  54 Digital TV Demux kABI
  55 ---------------------
  56
  57 Digital TV Demux
  58 ~~~~~~~~~~~~~~~~
  59
  60 The Kernel Digital TV Demux kABI defines a driver-internal interface for
  61 registering low-level, hardware specific driver to a hardware independent
  62 demux layer. It is only of interest for Digital TV device driver writers.
  63 The header file for this kABI is named demux.h and located in
  64 drivers/media/dvb-core.
  65
  66 The demux kABI should be implemented for each demux in the system. It is
  67 used to select the TS source of a demux and to manage the demux resources.
  68 When the demux client allocates a resource via the demux kABI, it receives
  69 a pointer to the kABI of that resource.
  70
  71 Each demux receives its TS input from a DVB front-end or from memory, as
  72 set via this demux kABI. In a system with more than one front-end, the kABI
  73 can be used to select one of the DVB front-ends as a TS source for a demux,
  74 unless this is fixed in the HW platform.
  75
  76 The demux kABI only controls front-ends regarding to their connections with
  77 demuxes; the kABI used to set the other front-end parameters, such as
  78 tuning, are devined via the Digital TV Frontend kABI.
  79
  80 The functions that implement the abstract interface demux should be defined
  81 static or module private and registered to the Demux core for external
  82 access. It is not necessary to implement every function in the struct
  83 &dmx_demux. For example, a demux interface might support Section filtering,
  84 but not PES filtering. The kABI client is expected to check the value of any
  85 function pointer before calling the function: the value of ``NULL`` means
  86 that the function is not available.
  87
  88 Whenever the functions of the demux API modify shared data, the
  89 possibilities of lost update and race condition problems should be
  90 addressed, e.g. by protecting parts of code with mutexes.
  91
  92 Note that functions called from a bottom half context must not sleep.
  93 Even a simple memory allocation without using ``GFP_ATOMIC`` can result in a
  94 kernel thread being put to sleep if swapping is needed. For example, the
  95 Linux Kernel calls the functions of a network device interface from a
  96 bottom half context. Thus, if a demux kABI function is called from network
  97 device code, the function must not sleep.
  98
  99
 100
 101 Demux Callback API
 102 ------------------
 103
 104 Demux Callback
 105 ~~~~~~~~~~~~~~
 106
 107 This kernel-space API comprises the callback functions that deliver filtered
 108 data to the demux client. Unlike the other DVB kABIs, these functions are
 109 provided by the client and called from the demux code.
 110
 111 The function pointers of this abstract interface are not packed into a
 112 structure as in the other demux APIs, because the callback functions are
 113 registered and used independent of each other. As an example, it is possible
 114 for the API client to provide several callback functions for receiving TS
 115 packets and no callbacks for PES packets or sections.
 116
 117 The functions that implement the callback API need not be re-entrant: when
 118 a demux driver calls one of these functions, the driver is not allowed to
 119 call the function again before the original call returns. If a callback is
 120 triggered by a hardware interrupt, it is recommended to use the Linux
 121 bottom half mechanism or start a tasklet instead of making the callback
 122 function call directly from a hardware interrupt.
 123
 124 This mechanism is implemented by :c:func:`dmx_ts_cb()` and :cpp:func:`dmx_section_cb()`
 125 callbacks.
 126
 127 .. kernel-doc:: drivers/media/dvb-core/demux.h
 128
 129 Digital TV Conditional Access kABI
 130 ----------------------------------
 131
 132 .. kernel-doc:: drivers/media/dvb-core/dvb_ca_en50221.h