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