From fd2d424f8382868593e4e08cf303585b1c1bbe5b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 11 Sep 2014 15:50:43 -0300 Subject: [PATCH] libdvbv5: Add a mainpage to the documentation Let's add a mainpage to the documentation, and do some cleanup on other pages. Signed-off-by: Mauro Carvalho Chehab --- doc/libdvbv5-index.doc | 169 +++++++++++++++++++++++++++++++++++++ doxygen_libdvbv5.cfg | 5 +- lib/include/libdvbv5/crc32.h | 8 +- lib/include/libdvbv5/descriptors.h | 6 +- lib/include/libdvbv5/dvb-demux.h | 3 +- lib/include/libdvbv5/dvb-fe.h | 3 +- lib/include/libdvbv5/dvb-file.h | 3 +- lib/include/libdvbv5/dvb-log.h | 3 +- lib/include/libdvbv5/dvb-sat.h | 3 +- lib/include/libdvbv5/dvb-scan.h | 3 +- lib/include/libdvbv5/dvb-v5-std.h | 3 +- lib/include/libdvbv5/eit.h | 10 +-- lib/include/libdvbv5/header.h | 2 +- lib/include/libdvbv5/nit.h | 7 +- lib/include/libdvbv5/pat.h | 10 +-- lib/include/libdvbv5/pmt.h | 10 +-- lib/include/libdvbv5/sdt.h | 10 +-- lib/include/libdvbv5/vct.h | 11 ++- 18 files changed, 221 insertions(+), 48 deletions(-) create mode 100644 doc/libdvbv5-index.doc diff --git a/doc/libdvbv5-index.doc b/doc/libdvbv5-index.doc new file mode 100644 index 0000000..ee31fdf --- /dev/null +++ b/doc/libdvbv5-index.doc @@ -0,0 +1,169 @@ +/* + * Copyright (c) 2014 - Mauro Carvalho Chehab + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation version 2 + * of the License. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + * Or, point your browser to http://www.gnu.org/licenses/old-licenses/gpl-2.0.html + * + */ + +/** +@mainpage The libdvbv5 API documentation +@copyright GNU General Public License version 2 (GPLv2) +@author Mauro Carvalho Chehab +@par Source code +The source code for libdvbv5 is available together with v4l-utils source +code, at: http://git.linuxtv.org/cgit.cgi/v4l-utils.git/ + +@see For DVBv5 Kernel API specification, see + http://linuxtv.org/downloads/v4l-dvb-apis/dvbapi.html. + +@par Bug Report +Please submit bug report and patches to linux-media@vger.kernel.org + +@section intro Introduction + +This is a library that provides access to DVB adapter cards using the +Linux DVB API version 5, as defined at +http://linuxtv.org/downloads/v4l-dvb-apis/dvbapi.html. + +It also provides backward compatibility to a a driver that supports only the +legacy DVBv3 API. + +@note The DVBv3 API was deprecated at the Linux Kernel. Any Kernel since + version 3.3 supports the DVBv5 API. + +The DVBv3 API was replaced because its support is limited to just 4 +standards, without covering their innovations: ATSC, DVB-C, DVB-T and +DVB-S. + +The DVBv5 API was originally introduced to support DVB-S2 (also called as +DVB S2API, at the time it was merged), and were designed in a way that it +can easily support any newer standards. So, extensions were added to support +other standards, like ATSC-MH, DVB-T2, DVB-S2, ISDB, CMDB, etc. + +Most of those standards are supported by libdvbv5. + +As the libdvbv5 API is maintained by the same people that maintains the +Linux DVB drivers, and it is used as the reference library, together with +the dvbv5 applications, all new improvements at the Linux DVB API gets merged, +the corresponding support at libdvbv5 is also included. + +@section feature Features provided by libdvbv5 + +The libdvbv5 provides the following features: + +- It uses the latest DVBv5 API speck to talk with the Digital TV devices on + Linux, falling back to older versions of it, up to the latest version of + the DVBv3 API; + +- It supports several Satellite Equipment Control (SEC) types and systems; + +- It supports SCR/Unicable setups for Satellite; + +- It supports several DiSEqC satellite system configurations; + +- It provides a standard way to scan for DVB channels for several different + types of standards: DVB-S, DVB-S2, DVB-S Turbo, DVB-C DVB-T, DVB-T2, ATSC + and ISDB-T; + +- It is flexible enough to be extended to support newer standards and newer + features; + +- It provides a way to activate/deactivate the Low Noise Amplifier (LNA) on + devices that support such feature; + +- It parses the MPEG-TS main tables found on Digital TV systems, like + PAT, PMT, SDT, TVCT, CVCT, NIT, EIT, MGT and CAT; + +- Provides enhanced statistics indication about the Quality of Service + provided by a tuned transponder. + +@section dvbv5_intro Introduction to DVBv5 key value properties + +@subsection dvbv5_props DVBv5 and libdvbv5 properties + +The deprecated DVBv3 frontend API used to declare an union that contains 4 +structs inside, one for each of the supported standards (ATSC and DVB-T/C/S). + +This gives no flexibility to extend, as adding more structs at the union +would change the size of the struct, breaking the Kernelspace to userspace +API, and causing all DVB applications to break. + +So, instead of keeping using this approach, the DVBv5 API came with a +different way: it passes a series of values using key/value properties. + +Those values feed a in-Kernel cache. There are two special properties: +- DTV_CLEAR - clears the Kernel cache +- DTV_TUNE - sends the cache for the DTV driver to tune into a transponder. + +See http://linuxtv.org/downloads/v4l-dvb-apis/FE_GET_SET_PROPERTY.html for +more details. + +The same way as DVBv5, the libdvbv5 API also works with a set of key/value +properties. + +Inside libdvbv5, there are two types of properties: + +- The ones defined at the Kernel's frontent API, that are found at + /usr/include/linux/dvb/frontend.h (actually, it uses a local copy + of that file, stored at ./include/linux/dvb/frontend.h); + +- Some extra properties used by libdvbv5. Those can be found at + lib/include/libdvbv5/dvb-v5-std.h and start at DTV_USER_COMMAND_START. + +Those extra properties allow to control other parameters that are visible +only on userspace, like the Service ID that will be used, and the corresponding +audio and video program IDs. + +@subsection dvbv5_stats DVBv5 and libdvbv5 statistics + +Just like what happens with DVBv3 frontend setting, the statistics provided +by DVBv3 has several issues. + +On DVBv3, there are a number of special ioctls designed to get the +statistics from a DTV device. + +Those DVBv3 statistics are not flexible, and they lack the scales that +are provided by each call. So, for example, a FE_READ_SNR ioctl returns +a number from 0 to 65535, but there's no way to know if this number is +a value in dB (or a submultiple) or if it is just a relative quality number +related to the Signal/Noise ratio. + +Also, some delivery systems like ISDB provide up to 4 statistics for each +parameter, because it allows to set different modulation parameters to the +several different layers of the stream. + +Starting with DVBv5 version 5.10 (added on Kernel 3.8), there's now a new +mechanism to retrieve the statistics. This mechanism provides a way to +discover the scale used internally by the Kernel, allowing the userspace +applications to properly present the statistics. + +It also allows to obtain per-layer statistics, plus a global ponderated +mean statistics for the transponder as a hole, on standards like ISDB. + +Just like the DTV properties, the stats are cached. That warrants that +all stats are got at the same time, when dvb_fe_get_stats() is called. +The Kernel drivers internally also warrant that those stats are also +obtained for the same period of time, making them more coherent. + +The libdvbv5 automatically detects if the Digital TV driver in usage +provides the DVBv5 version 5.10 statistics mechanism. If it doesn't, +it falls back to DVBv3 way. + +If DVB version 5.10 is supported, it also provides an extra Quality of +service indicator that tells if a received transponder has Poor, OK or +Good quality. + + */ diff --git a/doxygen_libdvbv5.cfg b/doxygen_libdvbv5.cfg index cbe0df3..c717625 100644 --- a/doxygen_libdvbv5.cfg +++ b/doxygen_libdvbv5.cfg @@ -44,7 +44,7 @@ PROJECT_NUMBER = $(VERSION) # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = "Library to work with Digital TV streams" +PROJECT_BRIEF = "Library to work with Digital TV devices on Linux" # With the PROJECT_LOGO tag one can specify an logo or icon that is included in # the documentation. The maximum height of the logo should not exceed 55 pixels @@ -743,7 +743,8 @@ WARN_LOGFILE = # spaces. # Note: If this tag is empty the current directory is searched. -INPUT = $(SRCDIR)/lib/include/libdvbv5/dvb-demux.h \ +INPUT = $(SRCDIR)/doc/libdvbv5-index.doc \ + $(SRCDIR)/lib/include/libdvbv5/dvb-demux.h \ $(SRCDIR)/lib/include/libdvbv5/dvb-fe.h \ $(SRCDIR)/lib/include/libdvbv5/dvb-file.h \ $(SRCDIR)/lib/include/libdvbv5/dvb-log.h \ diff --git a/lib/include/libdvbv5/crc32.h b/lib/include/libdvbv5/crc32.h index 350df52..a533f4e 100644 --- a/lib/include/libdvbv5/crc32.h +++ b/lib/include/libdvbv5/crc32.h @@ -27,13 +27,7 @@ * @author Andre Roth * * @par Bug Report - * Please submit bug report and patches to linux-media@vger.kernel.org - * - * @par Descriptors - * The descriptors herein are defined on: - * - ISO/IEC 13818-1 - * - * @see http://www.etherguidesystems.com/help/sdos/mpeg/syntax/tablesections/pat.aspx + * Please submit bug reports and patches to linux-media@vger.kernel.org */ #ifndef _CRC32_H diff --git a/lib/include/libdvbv5/descriptors.h b/lib/include/libdvbv5/descriptors.h index 255b9de..78de968 100644 --- a/lib/include/libdvbv5/descriptors.h +++ b/lib/include/libdvbv5/descriptors.h @@ -26,7 +26,8 @@ * @author Mauro Carvalho Chehab * @author Andre Roth * - * The descriptors are defined on: + * @par Relevant specs + * The descriptors herein are defined on the following specs: * - ISO/IEC 13818-1 * - ETSI EN 300 468 V1.11.1 (2010-04) * - SCTE 35 2004 @@ -35,7 +36,8 @@ * - ABNT NBR 15603-1 2007 * - ATSC A/65:2009 spec * - * Please submit bug report and patches to linux-media@vger.kernel.org + * @par Bug Report + * Please submit bug reports and patches to linux-media@vger.kernel.org */ diff --git a/lib/include/libdvbv5/dvb-demux.h b/lib/include/libdvbv5/dvb-demux.h index 5be3947..6badac4 100644 --- a/lib/include/libdvbv5/dvb-demux.h +++ b/lib/include/libdvbv5/dvb-demux.h @@ -26,7 +26,8 @@ * @copyright GNU General Public License version 2 (GPLv2) * @author Mauro Carvalho Chehab * - * Please submit bug report and patches to linux-media@vger.kernel.org + * @par Bug Report + * Please submit bug reports and patches to linux-media@vger.kernel.org */ #ifndef _DVB_DEMUX_H diff --git a/lib/include/libdvbv5/dvb-fe.h b/lib/include/libdvbv5/dvb-fe.h index bf01ed6..8a39c07 100644 --- a/lib/include/libdvbv5/dvb-fe.h +++ b/lib/include/libdvbv5/dvb-fe.h @@ -52,7 +52,8 @@ * Just like the DTV properties, the stats are cached. That warrants that * all stats are got at the same time, when dvb_fe_get_stats() is called. * - * Please submit bug report and patches to linux-media@vger.kernel.org + * @par Bug Report + * Please submit bug reports and patches to linux-media@vger.kernel.org */ /** diff --git a/lib/include/libdvbv5/dvb-file.h b/lib/include/libdvbv5/dvb-file.h index 07abd6b..a39f719 100644 --- a/lib/include/libdvbv5/dvb-file.h +++ b/lib/include/libdvbv5/dvb-file.h @@ -33,7 +33,8 @@ * The purpose of the functions and structures defined herein is to provide * support to read and write to those different formats. * - * Please submit bug report and patches to linux-media@vger.kernel.org + * @par Bug Report + * Please submit bug reports and patches to linux-media@vger.kernel.org */ /* diff --git a/lib/include/libdvbv5/dvb-log.h b/lib/include/libdvbv5/dvb-log.h index 90085e0..481e9e6 100644 --- a/lib/include/libdvbv5/dvb-log.h +++ b/lib/include/libdvbv5/dvb-log.h @@ -31,7 +31,8 @@ * @author Mauro Carvalho Chehab * @author Andre Roth * - * Please submit bug report and patches to linux-media@vger.kernel.org + * @par Bug Report + * Please submit bug reports and patches to linux-media@vger.kernel.org */ /** diff --git a/lib/include/libdvbv5/dvb-sat.h b/lib/include/libdvbv5/dvb-sat.h index f1bb119..af3e210 100644 --- a/lib/include/libdvbv5/dvb-sat.h +++ b/lib/include/libdvbv5/dvb-sat.h @@ -27,7 +27,8 @@ * @copyright GNU General Public License version 2 (GPLv2) * @author Mauro Carvalho Chehab * - * Please submit bug report and patches to linux-media@vger.kernel.org + * @par Bug Report + * Please submit bug reports and patches to linux-media@vger.kernel.org */ /* diff --git a/lib/include/libdvbv5/dvb-scan.h b/lib/include/libdvbv5/dvb-scan.h index 27042d9..778d3a7 100644 --- a/lib/include/libdvbv5/dvb-scan.h +++ b/lib/include/libdvbv5/dvb-scan.h @@ -30,7 +30,8 @@ * @copyright GNU General Public License version 2 (GPLv2) * @author Mauro Carvalho Chehab * - * Please submit bug report and patches to linux-media@vger.kernel.org + * @par Bug Report + * Please submit bug reports and patches to linux-media@vger.kernel.org */ /* According with ISO/IEC 13818-1:2007 */ diff --git a/lib/include/libdvbv5/dvb-v5-std.h b/lib/include/libdvbv5/dvb-v5-std.h index a78c919..8f23c7d 100644 --- a/lib/include/libdvbv5/dvb-v5-std.h +++ b/lib/include/libdvbv5/dvb-v5-std.h @@ -32,7 +32,8 @@ * @copyright GNU General Public License version 2 (GPLv2) * @author Mauro Carvalho Chehab * - * Please submit bug report and patches to linux-media@vger.kernel.org + * @par Bug Report + * Please submit bug reports and patches to linux-media@vger.kernel.org */ /* diff --git a/lib/include/libdvbv5/eit.h b/lib/include/libdvbv5/eit.h index 1f8fa95..8f824e7 100644 --- a/lib/include/libdvbv5/eit.h +++ b/lib/include/libdvbv5/eit.h @@ -26,12 +26,12 @@ * @author Mauro Carvalho Chehab * @author Andre Roth * - * @par Bug Report - * Please submit bug report and patches to linux-media@vger.kernel.org - * * @par Relevant specs - * The table described herein is defined on: + * The table described herein is defined at: * - ETSI EN 300 468 + * + * @par Bug Report + * Please submit bug reports and patches to linux-media@vger.kernel.org */ #ifndef _EIT_H @@ -150,7 +150,7 @@ struct dvb_table_eit { struct dvb_v5_fe_parms; -/** @brief Converts a running_status fielt into string */ +/** @brief Converts a running_status field into string */ extern const char *dvb_eit_running_status_name[8]; #ifdef __cplusplus diff --git a/lib/include/libdvbv5/header.h b/lib/include/libdvbv5/header.h index 0da38d8..ed4d6ee 100644 --- a/lib/include/libdvbv5/header.h +++ b/lib/include/libdvbv5/header.h @@ -34,7 +34,7 @@ * @author Andre Roth * * @par Bug Report - * Please submit bug report and patches to linux-media@vger.kernel.org + * Please submit bug reports and patches to linux-media@vger.kernel.org */ /** diff --git a/lib/include/libdvbv5/nit.h b/lib/include/libdvbv5/nit.h index 71a3061..f2eb4cb 100644 --- a/lib/include/libdvbv5/nit.h +++ b/lib/include/libdvbv5/nit.h @@ -38,12 +38,13 @@ * @par Bug Report * Please submit bug report and patches to linux-media@vger.kernel.org * - * @par Descriptors - * The descriptors herein are defined on: + * @par Relevant specs + * The table described herein is defined at: * - ISO/IEC 13818-1 * - ETSI EN 300 468 * - * @see http://www.etherguidesystems.com/Help/SDOs/dvb/syntax/tablesections/NIT.aspx + * @par Bug Report + * Please submit bug reports and patches to linux-media@vger.kernel.org */ /** diff --git a/lib/include/libdvbv5/pat.h b/lib/include/libdvbv5/pat.h index 47f7e3b..84c2761 100644 --- a/lib/include/libdvbv5/pat.h +++ b/lib/include/libdvbv5/pat.h @@ -26,14 +26,14 @@ * @author Mauro Carvalho Chehab * @author Andre Roth * - * @par Bug Report - * Please submit bug report and patches to linux-media@vger.kernel.org - * - * @par Descriptors - * The descriptors herein are defined on: + * @par Relevant specs + * The table described herein is defined at: * - ISO/IEC 13818-1 * * @see http://www.etherguidesystems.com/help/sdos/mpeg/syntax/tablesections/pat.aspx + * + * @par Bug Report + * Please submit bug reports and patches to linux-media@vger.kernel.org */ #ifndef _PAT_H diff --git a/lib/include/libdvbv5/pmt.h b/lib/include/libdvbv5/pmt.h index f4a84e7..0167dff 100644 --- a/lib/include/libdvbv5/pmt.h +++ b/lib/include/libdvbv5/pmt.h @@ -26,14 +26,14 @@ * @author Mauro Carvalho Chehab * @author Andre Roth * - * @par Bug Report - * Please submit bug report and patches to linux-media@vger.kernel.org - * - * @par Descriptors - * The descriptors herein are defined on: + * @par Relevant specs + * The table described herein is defined at: * - ISO/IEC 13818-1 * * @see http://www.etherguidesystems.com/help/sdos/mpeg/syntax/tablesections/pmts.aspx + * + * @par Bug Report + * Please submit bug reports and patches to linux-media@vger.kernel.org */ #ifndef _PMT_H diff --git a/lib/include/libdvbv5/sdt.h b/lib/include/libdvbv5/sdt.h index 21e63bc..9710136 100644 --- a/lib/include/libdvbv5/sdt.h +++ b/lib/include/libdvbv5/sdt.h @@ -29,14 +29,14 @@ * @author Mauro Carvalho Chehab * @author Andre Roth * - * @par Bug Report - * Please submit bug report and patches to linux-media@vger.kernel.org - * - * @par Descriptors - * The descriptors herein are defined on: + * @par Relevant specs + * The table described herein is defined at: * - ISO/IEC 13818-1 * * @see http://www.etherguidesystems.com/Help/SDOs/dvb/syntax/tablesections/SDT.aspx + * + * @par Bug Report + * Please submit bug reports and patches to linux-media@vger.kernel.org */ #include diff --git a/lib/include/libdvbv5/vct.h b/lib/include/libdvbv5/vct.h index 0042f18..9b69aa0 100644 --- a/lib/include/libdvbv5/vct.h +++ b/lib/include/libdvbv5/vct.h @@ -26,18 +26,17 @@ * @author Mauro Carvalho Chehab * @author Andre Roth * - * @par Bug Report - * Please submit bug report and patches to linux-media@vger.kernel.org - * - * @par Descriptors - * The descriptors herein are defined on: + * @par Relevant specs + * The table described herein is defined at: * - ATSC A/65:2009 spec * * @see http://www.etherguidesystems.com/help/sdos/atsc/syntax/tablesections/TVCT.aspx * @see http://www.etherguidesystems.com/help/sdos/atsc/syntax/tablesections/CVCT.aspx + * + * @par Bug Report + * Please submit bug reports and patches to linux-media@vger.kernel.org */ - #ifndef _VCT_H #define _VCT_H -- 2.7.4