From e4aa18d33c3a05f9ac51a8c8c7863318c807650f Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Date: Tue, 26 May 2015 11:04:14 -0300
Subject: [media] DocBook: Improve the description of the properties API

Make the text clearer about what the properties API does.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
---
 Documentation/DocBook/media/dvb/dvbproperty.xml | 37 +++++++++++++++++++++----
 1 file changed, 32 insertions(+), 5 deletions(-)

(limited to 'Documentation/DocBook/media/dvb/dvbproperty.xml')

diff --git a/Documentation/DocBook/media/dvb/dvbproperty.xml b/Documentation/DocBook/media/dvb/dvbproperty.xml
index 28ea62067af6..c10ed0636d02 100644
--- a/Documentation/DocBook/media/dvb/dvbproperty.xml
+++ b/Documentation/DocBook/media/dvb/dvbproperty.xml
@@ -1,8 +1,35 @@
-<section id="FE_GET_SET_PROPERTY">
-<title><constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></title>
-<para>This section describes the DVB version 5 extension of the DVB-API, also
-called "S2API", as this API were added to provide support for DVB-S2. It was
-designed to be able to replace the old frontend API. Yet, the DISEQC and
+<section id="frontend-properties">
+<title>DVB Frontend properties</title>
+<para>Tuning into a Digital TV physical channel and starting decoding it
+    requires to change a set of parameters, in order to control the
+    tuner, the demodulator, the Linear Low-noise Amplifier (LNA) and to set the
+    antena subsystem via Satellite Equipment Control (SEC), on satellital
+    systems. The actual parameters are specific to each particular digital
+    TV standards, and may change as the digital TV specs evolutes.</para>
+<para>In the past, the strategy used were to have an union with the parameters
+    needed to tune for DVB-S, DVB-C, DVB-T and ATSC delivery systems grouped
+    there. The problem is that, as the second generation standards appeared,
+    those structs were not big enough to contain the additional parameters.
+    Also, the union didn't have any space left to be expanded without breaking
+    userspace. So, the decision was to deprecate the legacy union/struct based
+    approach, in favor of a properties set approach.</para>
+<para>By using a properties set, it is now possible to extend and support any
+    digital TV without needing to redesign the API</para>
+<para>Example: with the properties based approach, in order to set the tuner
+    to a DVB-C channel at 651 kHz, modulated with 256-QAM, FEC 3/4 and symbol
+    rate of 5.217 Mbauds, those properties should be sent to
+    <link linkend="FE_GET_PROPERTY"><constant>FE_SET_PROPERTY</constant></link> ioctl:</para>
+    <itemizedlist>
+	<listitem>DTV_FREQUENCY = 651000000</listitem>
+	<listitem>DTV_MODULATION = QAM_256</listitem>
+	<listitem>DTV_INVERSION = INVERSION_AUTO</listitem>
+	<listitem>DTV_SYMBOL_RATE = 5217000</listitem>
+	<listitem>DTV_INNER_FEC = FEC_3_4</listitem>
+	<listitem>DTV_TUNE</listitem>
+    </itemizedlist>
+<para>NOTE: This section describes the DVB version 5 extension of the DVB-API,
+also called "S2API", as this API were added to provide support for DVB-S2. It
+was designed to be able to replace the old frontend API. Yet, the DISEQC and
 the capability ioctls weren't implemented yet via the new way.</para>
 <para>The typical usage for the <constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant>
 API is to replace the ioctl's were the <link linkend="dvb-frontend-parameters">
-- 
cgit v1.2.3-59-g8ed1b