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