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 (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 .. kernel-figure:: dvbstb.svg
  59     :alt:   dvbstb.svg
  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
 161         #include <linux/dvb/ca.h>
 162
 163         #include <linux/dvb/dmx.h>
 164
 165         #include <linux/dvb/frontend.h>
 166
 167         #include <linux/dvb/net.h>
 168
 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``.