1/*
2 * Copyright (c) 2014 - Mauro Carvalho Chehab <mchehab@kernel.org>
3 *
4 * This program is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU General Public License
6 * as published by the Free Software Foundation version 2
7 * of the License.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17 * Or, point your browser to http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
18 *
19 */
20
21/**
22@mainpage The libdvbv5 API documentation
23@copyright GNU General Public License version 2 (GPLv2)
24@author Mauro Carvalho Chehab <mchehab@kernel.org>
25@par Source code
26The source code for libdvbv5 is available together with v4l-utils source
27code, at: http://git.linuxtv.org/cgit.cgi/v4l-utils.git/
28
29@see For DVBv5 Kernel API specification, see
30     http://linuxtv.org/downloads/v4l-dvb-apis/dvbapi.html.
31
32@par Bug Report
33Please submit bug report and patches to linux-media@vger.kernel.org
34
35@section intro Introduction
36
37This is a library that provides access to DVB adapter cards using the
38Linux DVB API version 5, as defined at
39http://linuxtv.org/downloads/v4l-dvb-apis/dvbapi.html.
40
41It also provides backward compatibility to a a driver that supports only the
42legacy DVBv3 API.
43
44@note	The DVBv3 API was deprecated at the Linux Kernel. Any Kernel since
45	version 3.3 supports the DVBv5 API.
46
47The DVBv3 API was replaced because its support is limited to just 4
48standards, without covering their innovations: ATSC, DVB-C, DVB-T and
49DVB-S.
50
51The DVBv5 API was originally introduced to support DVB-S2 (also called as
52DVB S2API, at the time it was merged), and were designed in a way that it
53can easily support any newer standards. So, extensions were added to support
54other standards, like ATSC-MH, DVB-T2, DVB-S2, ISDB, CMDB, etc.
55
56Most of those standards are supported by libdvbv5.
57
58As the libdvbv5 API is maintained by the same people that maintains the
59Linux DVB drivers, and it is used as the reference library, together with
60the dvbv5 applications, all new improvements at the Linux DVB API gets merged,
61the corresponding support at libdvbv5 is also included.
62
63@section feature Features provided by libdvbv5
64
65The libdvbv5 provides the following features:
66
67- It uses the latest DVBv5 API speck to talk with the Digital TV devices on
68  Linux, falling back to older versions of it, up to the latest version of
69  the DVBv3 API;
70
71- It supports several Satellite Equipment Control (SEC) types and systems;
72
73- It supports SCR/Unicable setups for Satellite;
74
75- It supports several DiSEqC satellite system configurations;
76
77- It provides a standard way to scan for DVB channels for several different
78  types of standards: DVB-S, DVB-S2, DVB-S Turbo, DVB-C DVB-T, DVB-T2, ATSC
79  and ISDB-T;
80
81- It is flexible enough to be extended to support newer standards and newer
82  features;
83
84- It provides a way to activate/deactivate the Low Noise Amplifier (LNA) on
85  devices that support such feature;
86
87- It parses the MPEG-TS main tables found on Digital TV systems, like
88  PAT, PMT, SDT, TVCT, CVCT, NIT, EIT, MGT and CAT;
89
90- Provides enhanced statistics indication about the Quality of Service
91  provided by a tuned transponder.
92
93@section dvbv5_intro Introduction to DVBv5 key value properties
94
95@subsection dvbv5_props DVBv5 and libdvbv5 properties
96
97The deprecated DVBv3 frontend API used to declare an union that contains 4
98structs inside, one for each of the supported standards (ATSC and DVB-T/C/S).
99
100This gives no flexibility to extend, as adding more structs at the union
101would change the size of the struct, breaking the Kernelspace to userspace
102API, and causing all DVB applications to break.
103
104So, instead of keeping using this approach, the DVBv5 API came with a
105different way: it passes a series of values using key/value properties.
106
107Those values feed a in-Kernel cache. There are two special properties:
108- DTV_CLEAR - clears the Kernel cache
109- DTV_TUNE - sends the cache for the DTV driver to tune into a transponder.
110
111See http://linuxtv.org/downloads/v4l-dvb-apis/FE_GET_SET_PROPERTY.html for
112more details.
113
114The same way as DVBv5, the libdvbv5 API also works with a set of key/value
115properties.
116
117Inside libdvbv5, there are two types of properties:
118
119- The ones defined at the Kernel's frontent API, that are found at
120  /usr/include/linux/dvb/frontend.h (actually, it uses a local copy
121  of that file, stored at ./include/linux/dvb/frontend.h);
122
123- Some extra properties used by libdvbv5. Those can be found at
124  lib/include/libdvbv5/dvb-v5-std.h and start at DTV_USER_COMMAND_START.
125
126Those extra properties allow to control other parameters that are visible
127only on userspace, like the Service ID that will be used, and the corresponding
128audio and video program IDs.
129
130@subsection dvbv5_stats DVBv5 and libdvbv5 statistics
131
132Just like what happens with DVBv3 frontend setting, the statistics provided
133by DVBv3 has several issues.
134
135On DVBv3, there are a number of special ioctls designed to get the
136statistics from a DTV device.
137
138Those DVBv3 statistics are not flexible, and they lack the scales that
139are provided by each call. So, for example, a FE_READ_SNR ioctl returns
140a number from 0 to 65535, but there's no way to know if this number is
141a value in dB (or a submultiple) or if it is just a relative quality number
142related to the Signal/Noise ratio.
143
144Also, some delivery systems like ISDB provide up to 4 statistics for each
145parameter, because it allows to set different modulation parameters to the
146several different layers of the stream.
147
148Starting with DVBv5 version 5.10 (added on Kernel 3.8), there's now a new
149mechanism to retrieve the statistics. This mechanism provides a way to
150discover the scale used internally by the Kernel, allowing the userspace
151applications to properly present the statistics.
152
153It also allows to obtain per-layer statistics, plus a global ponderated
154mean statistics for the transponder as a whole, on standards like ISDB.
155
156Just like the DTV properties, the stats are cached. That warrants that
157all stats are got at the same time, when dvb_fe_get_stats() is called.
158The Kernel drivers internally also warrant that those stats are also
159obtained for the same period of time, making them more coherent.
160
161The libdvbv5 automatically detects if the Digital TV driver in usage
162provides the DVBv5 version 5.10 statistics mechanism. If it doesn't,
163it falls back to DVBv3 way.
164
165If DVB version 5.10 is supported, it also provides an extra Quality of
166service indicator that tells if a received transponder has Poor, OK or
167Good quality.
168*/
169
170/**
171@page dvbv5-tools DVBv5 Tools
172@brief Set of DVBv5 tools, bundled together with libdvbv5
173
174DVBv5 Tools  is a small set of command line utilities that was developed
175to be compliant with the newer features provided by version 5 of the DVB API.
176The tools should also be backward compatible with the older v3 DVB API.
177They were written using libdvbv5.
178
179It is composed of 4 tools:
180
181- dvbv5-scan - Scans the channel transponders and gets the services available
182  there;
183- dvbv5-zap - Locks into a channel (zap), allowing other applications to get
184  the stream at the dvr devices or to monitor the stream;
185- dvb-fe-tool - Lists frontend properties and allow to manually set the DVB
186  frontend
187- dvb-format-convert - Converts from/to other formats used by DVBv3 apps into
188  the dvbv5 format.
189
190The DVBv5 default file format is formed by a channel name, followed by a series
191of key/value properties. Those tools also support the legacy formats used by
192dvb-apps.
193
194For example, this is a channel file with one DVB-C channel on it:
195@code{.unparsed}
196[CHANNEL]
197	DELIVERY_SYSTEM = DVBC/ANNEX_A
198	FREQUENCY = 573000000
199	SYMBOL_RATE = 5217000
200	INNER_FEC = NONE
201	MODULATION = QAM/256
202	INVERSION = AUTO
203@endcode
204And this is (part of) a service (zap) file, produced from the above channel
205definition using dvbv5-scan:
206
207@code{.unparsed}
208[SBT]
209	SERVICE_ID = 4
210	VIDEO_PID = 42
211	AUDIO_PID = 257
212	PID_f1 = 768
213	FREQUENCY = 573000000
214	MODULATION = QAM/256
215	INVERSION = AUTO
216	SYMBOL_RATE = 5217000
217	INNER_FEC = NONE
218	DELIVERY_SYSTEM = DVBC/ANNEX_A
219
220[TNT]
221	SERVICE_ID = 48
222	VIDEO_PID = 336
223	AUDIO_PID = 337 338 849
224	PID_86 = 816
225	FREQUENCY = 573000000
226	MODULATION = QAM/256
227	INVERSION = AUTO
228	SYMBOL_RATE = 5217000
229	INNER_FEC = NONE
230	DELIVERY_SYSTEM = DVBC/ANNEX_A
231@endcode
232
233@example dvbv5-scan.c
234@example dvbv5-zap.c
235@example dvb-fe-tool.c
236@example dvb-format-convert.c
237
238@defgroup dvb_device Digital TV device enumeration
239@defgroup frontend Digital TV frontend control
240@defgroup frontend_scan Digital TV frontend scan
241@defgroup satellite Satellite Equipment Control
242@defgroup ancillary Ancillary functions and macros
243@defgroup dvb_table Digital TV table parsing
244@defgroup descriptors Parsers for several MPEG-TS descriptors
245@defgroup demux Digital TV demux
246@defgroup file Channel and transponder file read/write
247 */
248