| 1 |
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
| 2 |
|
| 3 |
.. _dvb_introduction: |
| 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``. |