Documentation/media/uapi/dvb/intro.rst

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