Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 1 | .. -*- coding: utf-8; mode: rst -*- |
| 2 | |
| 3 | .. _dvb_introdution: |
| 4 | |
| 5 | ************ |
| 6 | Introduction |
| 7 | ************ |
| 8 | |
| 9 | |
| 10 | .. _requisites: |
| 11 | |
| 12 | What you need to know |
| 13 | ===================== |
| 14 | |
| 15 | The reader of this document is required to have some knowledge in the |
| 16 | area of digital video broadcasting (DVB) and should be familiar with |
| 17 | part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e |
| 18 | you should know what a program/transport stream (PS/TS) is and what is |
| 19 | meant by a packetized elementary stream (PES) or an I-frame. |
| 20 | |
| 21 | Various DVB standards documents are available from http://www.dvb.org |
| 22 | and/or http://www.etsi.org. |
| 23 | |
| 24 | It is also necessary to know how to access unix/linux devices and how to |
| 25 | use ioctl calls. This also includes the knowledge of C or C++. |
| 26 | |
| 27 | |
| 28 | .. _history: |
| 29 | |
| 30 | History |
| 31 | ======= |
| 32 | |
| 33 | The first API for DVB cards we used at Convergence in late 1999 was an |
| 34 | extension of the Video4Linux API which was primarily developed for frame |
| 35 | grabber cards. As such it was not really well suited to be used for DVB |
| 36 | cards and their new features like recording MPEG streams and filtering |
| 37 | several section and PES data streams at the same time. |
| 38 | |
| 39 | In early 2000, we were approached by Nokia with a proposal for a new |
| 40 | standard Linux DVB API. As a commitment to the development of terminals |
| 41 | based on open standards, Nokia and Convergence made it available to all |
| 42 | Linux developers and published it on https://linuxtv.org in September |
| 43 | 2000. Convergence is the maintainer of the Linux DVB API. Together with |
| 44 | the LinuxTV community (i.e. you, the reader of this document), the Linux |
| 45 | DVB API will be constantly reviewed and improved. With the Linux driver |
| 46 | for the Siemens/Hauppauge DVB PCI card Convergence provides a first |
| 47 | implementation of the Linux DVB API. |
| 48 | |
| 49 | |
| 50 | .. _overview: |
| 51 | |
| 52 | Overview |
| 53 | ======== |
| 54 | |
| 55 | |
| 56 | .. _stb_components: |
| 57 | |
| 58 | .. figure:: intro_files/dvbstb.* |
| 59 | :alt: dvbstb.pdf / dvbstb.png |
| 60 | :align: center |
| 61 | |
| 62 | Components of a DVB card/STB |
| 63 | |
| 64 | A DVB PCI card or DVB set-top-box (STB) usually consists of the |
| 65 | following main hardware components: |
| 66 | |
| 67 | - Frontend consisting of tuner and DVB demodulator |
| 68 | |
| 69 | Here the raw signal reaches the DVB hardware from a satellite dish or |
| 70 | antenna or directly from cable. The frontend down-converts and |
| 71 | demodulates this signal into an MPEG transport stream (TS). In case |
| 72 | of a satellite frontend, this includes a facility for satellite |
| 73 | equipment control (SEC), which allows control of LNB polarization, |
| 74 | multi feed switches or dish rotors. |
| 75 | |
| 76 | - Conditional Access (CA) hardware like CI adapters and smartcard slots |
| 77 | |
| 78 | The complete TS is passed through the CA hardware. Programs to which |
| 79 | the user has access (controlled by the smart card) are decoded in |
| 80 | real time and re-inserted into the TS. |
| 81 | |
| 82 | - Demultiplexer which filters the incoming DVB stream |
| 83 | |
| 84 | The demultiplexer splits the TS into its components like audio and |
| 85 | video streams. Besides usually several of such audio and video |
| 86 | streams it also contains data streams with information about the |
| 87 | programs offered in this or other streams of the same provider. |
| 88 | |
| 89 | - MPEG2 audio and video decoder |
| 90 | |
| 91 | The main targets of the demultiplexer are the MPEG2 audio and video |
| 92 | decoders. After decoding they pass on the uncompressed audio and |
| 93 | video to the computer screen or (through a PAL/NTSC encoder) to a TV |
| 94 | set. |
| 95 | |
| 96 | :ref:`stb_components` shows a crude schematic of the control and data |
| 97 | flow between those components. |
| 98 | |
| 99 | On a DVB PCI card not all of these have to be present since some |
| 100 | functionality can be provided by the main CPU of the PC (e.g. MPEG |
| 101 | picture and sound decoding) or is not needed (e.g. for data-only uses |
| 102 | like “internet over satellite”). Also not every card or STB provides |
| 103 | conditional access hardware. |
| 104 | |
| 105 | |
| 106 | .. _dvb_devices: |
| 107 | |
| 108 | Linux DVB Devices |
| 109 | ================= |
| 110 | |
| 111 | The Linux DVB API lets you control these hardware components through |
| 112 | currently six Unix-style character devices for video, audio, frontend, |
| 113 | demux, CA and IP-over-DVB networking. The video and audio devices |
| 114 | control the MPEG2 decoder hardware, the frontend device the tuner and |
| 115 | the DVB demodulator. The demux device gives you control over the PES and |
| 116 | section filters of the hardware. If the hardware does not support |
| 117 | filtering these filters can be implemented in software. Finally, the CA |
| 118 | device controls all the conditional access capabilities of the hardware. |
| 119 | It can depend on the individual security requirements of the platform, |
| 120 | if and how many of the CA functions are made available to the |
| 121 | application through this device. |
| 122 | |
| 123 | All devices can be found in the ``/dev`` tree under ``/dev/dvb``. The |
| 124 | individual devices are called: |
| 125 | |
| 126 | - ``/dev/dvb/adapterN/audioM``, |
| 127 | |
| 128 | - ``/dev/dvb/adapterN/videoM``, |
| 129 | |
| 130 | - ``/dev/dvb/adapterN/frontendM``, |
| 131 | |
| 132 | - ``/dev/dvb/adapterN/netM``, |
| 133 | |
| 134 | - ``/dev/dvb/adapterN/demuxM``, |
| 135 | |
| 136 | - ``/dev/dvb/adapterN/dvrM``, |
| 137 | |
| 138 | - ``/dev/dvb/adapterN/caM``, |
| 139 | |
| 140 | where N enumerates the DVB PCI cards in a system starting from 0, and M |
| 141 | enumerates the devices of each type within each adapter, starting |
| 142 | from 0, too. We will omit the “ ``/dev/dvb/adapterN/``\ ” in the further |
| 143 | discussion of these devices. |
| 144 | |
| 145 | More details about the data structures and function calls of all the |
| 146 | devices are described in the following chapters. |
| 147 | |
| 148 | |
| 149 | .. _include_files: |
| 150 | |
| 151 | API include files |
| 152 | ================= |
| 153 | |
| 154 | For each of the DVB devices a corresponding include file exists. The DVB |
| 155 | API include files should be included in application sources with a |
| 156 | partial path like: |
| 157 | |
| 158 | |
| 159 | .. code-block:: c |
| 160 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame] | 161 | #include <linux/dvb/ca.h> |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 162 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame] | 163 | #include <linux/dvb/dmx.h> |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 164 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame] | 165 | #include <linux/dvb/frontend.h> |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 166 | |
Mauro Carvalho Chehab | 0579e6e | 2016-07-04 16:25:48 -0300 | [diff] [blame] | 167 | #include <linux/dvb/net.h> |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 168 | |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 169 | |
| 170 | To enable applications to support different API version, an additional |
| 171 | include file ``linux/dvb/version.h`` exists, which defines the constant |
| 172 | ``DVB_API_VERSION``. This document describes ``DVB_API_VERSION 5.10``. |