0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002
0003 .. _dvb_introdution:
0004
0005 ************
0006 Introduction
0007 ************
0008
0009
0010 .. _requisites:
0011
0012 What you need to know
0013 =====================
0014
0015 The reader of this document is required to have some knowledge in the
0016 area of digital video broadcasting (Digital TV) and should be familiar with
0017 part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e
0018 you should know what a program/transport stream (PS/TS) is and what is
0019 meant by a packetized elementary stream (PES) or an I-frame.
0020
0021 Various Digital TV standards documents are available for download at:
0022
0023 - European standards (DVB): http://www.dvb.org and/or http://www.etsi.org.
0024 - American standards (ATSC): https://www.atsc.org/standards/
0025 - Japanese standards (ISDB): http://www.dibeg.org/
0026
0027 It is also necessary to know how to access Linux devices and how to
0028 use ioctl calls. This also includes the knowledge of C or C++.
0029
0030
0031 .. _history:
0032
0033 History
0034 =======
0035
0036 The first API for Digital TV cards we used at Convergence in late 1999 was an
0037 extension of the Video4Linux API which was primarily developed for frame
0038 grabber cards. As such it was not really well suited to be used for Digital
0039 TV cards and their new features like recording MPEG streams and filtering
0040 several section and PES data streams at the same time.
0041
0042 In early 2000, Convergence was approached by Nokia with a proposal for a new
0043 standard Linux Digital TV API. As a commitment to the development of terminals
0044 based on open standards, Nokia and Convergence made it available to all
0045 Linux developers and published it on https://linuxtv.org in September
0046 2000. With the Linux driver for the Siemens/Hauppauge DVB PCI card,
0047 Convergence provided a first implementation of the Linux Digital TV API.
0048 Convergence was the maintainer of the Linux Digital TV API in the early
0049 days.
0050
0051 Now, the API is maintained by the LinuxTV community (i.e. you, the reader
0052 of this document). The Linux Digital TV API is constantly reviewed and
0053 improved together with the improvements at the subsystem's core at the
0054 Kernel.
0055
0056
0057 .. _overview:
0058
0059 Overview
0060 ========
0061
0062
0063 .. _stb_components:
0064
0065 .. kernel-figure:: dvbstb.svg
0066 :alt: dvbstb.svg
0067 :align: center
0068
0069 Components of a Digital TV card/STB
0070
0071 A Digital TV card or set-top-box (STB) usually consists of the
0072 following main hardware components:
0073
0074 Frontend consisting of tuner and digital TV demodulator
0075 Here the raw signal reaches the digital TV hardware from a satellite dish or
0076 antenna or directly from cable. The frontend down-converts and
0077 demodulates this signal into an MPEG transport stream (TS). In case
0078 of a satellite frontend, this includes a facility for satellite
0079 equipment control (SEC), which allows control of LNB polarization,
0080 multi feed switches or dish rotors.
0081
0082 Conditional Access (CA) hardware like CI adapters and smartcard slots
0083 The complete TS is passed through the CA hardware. Programs to which
0084 the user has access (controlled by the smart card) are decoded in
0085 real time and re-inserted into the TS.
0086
0087 .. note::
0088
0089 Not every digital TV hardware provides conditional access hardware.
0090
0091 Demultiplexer which filters the incoming Digital TV MPEG-TS stream
0092 The demultiplexer splits the TS into its components like audio and
0093 video streams. Besides usually several of such audio and video
0094 streams it also contains data streams with information about the
0095 programs offered in this or other streams of the same provider.
0096
0097 Audio and video decoder
0098 The main targets of the demultiplexer are audio and video
0099 decoders. After decoding, they pass on the uncompressed audio and
0100 video to the computer screen or to a TV set.
0101
0102 .. note::
0103
0104 Modern hardware usually doesn't have a separate decoder hardware, as
0105 such functionality can be provided by the main CPU, by the graphics
0106 adapter of the system or by a signal processing hardware embedded on
0107 a Systems on a Chip (SoC) integrated circuit.
0108
0109 It may also not be needed for certain usages (e.g. for data-only
0110 uses like "internet over satellite").
0111
0112 :ref:`stb_components` shows a crude schematic of the control and data
0113 flow between those components.
0114
0115
0116
0117 .. _dvb_devices:
0118
0119 Linux Digital TV Devices
0120 ========================
0121
0122 The Linux Digital TV API lets you control these hardware components through
0123 currently six Unix-style character devices for video, audio, frontend,
0124 demux, CA and IP-over-DVB networking. The video and audio devices
0125 control the MPEG2 decoder hardware, the frontend device the tuner and
0126 the Digital TV demodulator. The demux device gives you control over the PES
0127 and section filters of the hardware. If the hardware does not support
0128 filtering these filters can be implemented in software. Finally, the CA
0129 device controls all the conditional access capabilities of the hardware.
0130 It can depend on the individual security requirements of the platform,
0131 if and how many of the CA functions are made available to the
0132 application through this device.
0133
0134 All devices can be found in the ``/dev`` tree under ``/dev/dvb``. The
0135 individual devices are called:
0136
0137 - ``/dev/dvb/adapterN/audioM``,
0138
0139 - ``/dev/dvb/adapterN/videoM``,
0140
0141 - ``/dev/dvb/adapterN/frontendM``,
0142
0143 - ``/dev/dvb/adapterN/netM``,
0144
0145 - ``/dev/dvb/adapterN/demuxM``,
0146
0147 - ``/dev/dvb/adapterN/dvrM``,
0148
0149 - ``/dev/dvb/adapterN/caM``,
0150
0151 where ``N`` enumerates the Digital TV cards in a system starting from 0, and
0152 ``M`` enumerates the devices of each type within each adapter, starting
0153 from 0, too. We will omit the "``/dev/dvb/adapterN/``\ " in the further
0154 discussion of these devices.
0155
0156 More details about the data structures and function calls of all the
0157 devices are described in the following chapters.
0158
0159
0160 .. _include_files:
0161
0162 API include files
0163 =================
0164
0165 For each of the Digital TV devices a corresponding include file exists. The
0166 Digital TV API include files should be included in application sources with a
0167 partial path like:
0168
0169
0170 .. code-block:: c
0171
0172 #include <linux/dvb/ca.h>
0173
0174 #include <linux/dvb/dmx.h>
0175
0176 #include <linux/dvb/frontend.h>
0177
0178 #include <linux/dvb/net.h>
0179
0180
0181 To enable applications to support different API version, an additional
0182 include file ``linux/dvb/version.h`` exists, which defines the constant
0183 ``DVB_API_VERSION``. This document describes ``DVB_API_VERSION 5.10``.
