[PATCH 1/6] media: dvb/intro.rst: Use verbatim font where needed

[PATCH 1/6] media: dvb/intro.rst: Use verbatim font where needed

[Mauro Carvalho Chehab]

The device numbering for DVB uses "M" and "N" as vars for the
number of the device, but sometimes this is printed using normal
font instead of verbatim.

While here, remove an extra space after quotation marks.

This is a minor cleanup with no changes at the text.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/uapi/dvb/intro.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/media/uapi/dvb/intro.rst b/Documentation/media/uapi/dvb/intro.rst
index 652c4aacd2c6..20bd7aec2665 100644
--- a/Documentation/media/uapi/dvb/intro.rst
+++ b/Documentation/media/uapi/dvb/intro.rst
@@ -137,9 +137,9 @@ individual devices are called:
 
 -  ``/dev/dvb/adapterN/caM``,
 
-where N enumerates the DVB PCI cards in a system starting from 0, and M
+where ``N`` enumerates the DVB PCI cards in a system starting from 0, and ``M``
 enumerates the devices of each type within each adapter, starting
-from 0, too. We will omit the “ ``/dev/dvb/adapterN/``\ ” in the further
+from 0, too. We will omit the “``/dev/dvb/adapterN/``\ ” in the further
 discussion of these devices.
 
 More details about the data structures and function calls of all the
-- 
2.13.3

[PATCH 2/6] media: frontend.rst: fix supported delivery systems

[Mauro Carvalho Chehab]

The introduction for the frontend chapter is not quite
correct:
  - it tells that it supports only three types of
    delivery systems, in opposite to three *groups*;
  - It adds ISDB-C to the list of supported systems,
    but, this is not true.

Fix it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/uapi/dvb/frontend.rst | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/media/uapi/dvb/frontend.rst b/Documentation/media/uapi/dvb/frontend.rst
index e051a9012540..313f46a4c6a6 100644
--- a/Documentation/media/uapi/dvb/frontend.rst
+++ b/Documentation/media/uapi/dvb/frontend.rst
@@ -5,13 +5,15 @@
 ################
 DVB Frontend API
 ################
-The DVB frontend API was designed to support three types of delivery
-systems:
+
+The DVB frontend API was designed to support three groups of delivery
+systems: Terrestrial, cable and Satellite. Currently, the following
+delivery systems are supported:
 
 -  Terrestrial systems: DVB-T, DVB-T2, ATSC, ATSC M/H, ISDB-T, DVB-H,
    DTMB, CMMB
 
--  Cable systems: DVB-C Annex A/C, ClearQAM (DVB-C Annex B), ISDB-C
+-  Cable systems: DVB-C Annex A/C, ClearQAM (DVB-C Annex B)
 
 -  Satellite systems: DVB-S, DVB-S2, DVB Turbo, ISDB-S, DSS
 
-- 
2.13.3

[PATCH 3/6] media: frontend.rst: convert SEC note into footnote

[Mauro Carvalho Chehab]

The description of what SEC means fits well as a footnote.
That makes the need of saying that SEC is only for Satellite
when it was mentioned, as the footnote already says that.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/uapi/dvb/frontend.rst | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

diff --git a/Documentation/media/uapi/dvb/frontend.rst b/Documentation/media/uapi/dvb/frontend.rst
index 313f46a4c6a6..0bfade2b72cf 100644
--- a/Documentation/media/uapi/dvb/frontend.rst
+++ b/Documentation/media/uapi/dvb/frontend.rst
@@ -25,7 +25,7 @@ The DVB frontend controls several sub-devices including:
 
 -  Low noise amplifier (LNA)
 
--  Satellite Equipment Control (SEC) hardware (only for Satellite).
+-  Satellite Equipment Control (SEC) [#f1]_.
 
 The frontend can be accessed through ``/dev/dvb/adapter?/frontend?``.
 Data types and ioctl definitions can be accessed by including
@@ -36,13 +36,16 @@ Data types and ioctl definitions can be accessed by including
    Transmission via the internet (DVB-IP) is not yet handled by this
    API but a future extension is possible.
 
-On Satellite systems, the API support for the Satellite Equipment
-Control (SEC) allows to power control and to send/receive signals to
-control the antenna subsystem, selecting the polarization and choosing
-the Intermediate Frequency IF) of the Low Noise Block Converter Feed
-Horn (LNBf). It supports the DiSEqC and V-SEC protocols. The DiSEqC
-(digital SEC) specification is available at
-`Eutelsat <http://www.eutelsat.com/satellites/4_5_5.html>`__.
+
+.. [#f1]
+
+   On Satellite systems, the API support for the Satellite Equipment
+   Control (SEC) allows to power control and to send/receive signals to
+   control the antenna subsystem, selecting the polarization and choosing
+   the Intermediate Frequency IF) of the Low Noise Block Converter Feed
+   Horn (LNBf). It supports the DiSEqC and V-SEC protocols. The DiSEqC
+   (digital SEC) specification is available at
+   `Eutelsat <http://www.eutelsat.com/satellites/4_5_5.html>`__.
 
 
 .. toctree::
-- 
2.13.3

[PATCH 4/6] media: frontend.rst: mention MMT at the documentation

[Mauro Carvalho Chehab]

The ATSC 3.0 uses MPEG Media Transport, with is not currently
supported. Yet, we'll need to implement it sooner or later.
So, mention about it at the specs.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/uapi/dvb/frontend.rst | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/Documentation/media/uapi/dvb/frontend.rst b/Documentation/media/uapi/dvb/frontend.rst
index 0bfade2b72cf..40adcd0da2dc 100644
--- a/Documentation/media/uapi/dvb/frontend.rst
+++ b/Documentation/media/uapi/dvb/frontend.rst
@@ -33,9 +33,8 @@ Data types and ioctl definitions can be accessed by including
 
 .. note::
 
-   Transmission via the internet (DVB-IP) is not yet handled by this
-   API but a future extension is possible.
-
+   Transmission via the internet (DVB-IP) and MMT (MPEG Media Transport)
+   is not yet handled by this API but a future extension is possible.
 
 .. [#f1]
 
-- 
2.13.3

[PATCH 5/6] media: dvbproperty.rst: improve notes about legacy frontend calls

[Mauro Carvalho Chehab]

The description of the DVBv5 API was written a long time ago,
where the API was still new, and there were not apps using it.

Now that the API is stable and used by new applications, clarify
that DVBv3 calls should not be used and why.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/uapi/dvb/dvbproperty.rst | 39 ++++++++++++++++++----------
 1 file changed, 25 insertions(+), 14 deletions(-)

diff --git a/Documentation/media/uapi/dvb/dvbproperty.rst b/Documentation/media/uapi/dvb/dvbproperty.rst
index dd2d71ce43fa..1e8fc75e469d 100644
--- a/Documentation/media/uapi/dvb/dvbproperty.rst
+++ b/Documentation/media/uapi/dvb/dvbproperty.rst
@@ -12,23 +12,34 @@ antenna subsystem via Satellite Equipment Control (SEC), on satellite
 systems. The actual parameters are specific to each particular digital
 TV standards, and may change as the digital TV specs evolves.
 
-In the past, the strategy used was to have a 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.
+In the past (up to DVB API version 3), the strategy used was to have a
+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, the size of such union was not big
+enough to group the structs that would be required for those new
+standards. Also, extending it would break userspace.
+
+So, the legacy union/struct based approach was deprecated, in favor
+of a properties set approach.
+
+This section describes the new and recommended way to set the frontend,
+with suppports all digital TV delivery systems.
 
 .. note::
 
-   On Linux DVB API version 3, setting a frontend were done via
-   struct :c:type:`dvb_frontend_parameters`.
-   This got replaced on version 5 (also called "S2API", as this API were
-   added originally_enabled to provide support for DVB-S2), because the
-   old API has a very limited support to new standards and new hardware.
-   This section describes the new and recommended way to set the frontend,
-   with suppports all digital TV delivery systems.
+   1. On Linux DVB API version 3, setting a frontend was done via
+      struct :c:type:`dvb_frontend_parameters`.
+
+   2. Don't use DVB API version 3 calls on hardware with supports
+      newer standards. Such API provides no suport or a very limited
+      support to new standards and/or new hardware.
+
+   3. Nowadays, most frontends support multiple delivery systems.
+      Only with DVB v5 calls it is possible to switch between
+      the multiple delivery systems supported by a frontend.
+
+   4. DVB API version 5 is also called *S2API*, as the first
+      new standard added to it was DVB-S2.
 
 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
-- 
2.13.3

[PATCH 6/6] media: dvbproperty.rst: minor editorial changes

[Mauro Carvalho Chehab]

Do some minor editorial changes to make this chapter visually
better, and the example a little bit clearer.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/uapi/dvb/dvbproperty.rst | 25 ++++++++++++-------------
 1 file changed, 12 insertions(+), 13 deletions(-)

diff --git a/Documentation/media/uapi/dvb/dvbproperty.rst b/Documentation/media/uapi/dvb/dvbproperty.rst
index 1e8fc75e469d..843f1d70aff0 100644
--- a/Documentation/media/uapi/dvb/dvbproperty.rst
+++ b/Documentation/media/uapi/dvb/dvbproperty.rst
@@ -8,8 +8,8 @@ DVB Frontend properties
 Tuning into a Digital TV physical channel and starting decoding it
 requires changing a set of parameters, in order to control the tuner,
 the demodulator, the Linear Low-noise Amplifier (LNA) and to set the
-antenna subsystem via Satellite Equipment Control (SEC), on satellite
-systems. The actual parameters are specific to each particular digital
+antenna subsystem via Satellite Equipment Control - SEC (on satellite
+systems). The actual parameters are specific to each particular digital
 TV standards, and may change as the digital TV specs evolves.
 
 In the past (up to DVB API version 3), the strategy used was to have a
@@ -41,25 +41,24 @@ with suppports all digital TV delivery systems.
    4. DVB API version 5 is also called *S2API*, as the first
       new standard added to it was DVB-S2.
 
-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
+**Example**: in order to set the hardware to tune into 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
 :ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` ioctl:
 
--  :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` =
-   SYS_DVBC_ANNEX_A
+  :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` = SYS_DVBC_ANNEX_A
 
--  :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` = 651000000
+  :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` = 651000000
 
--  :ref:`DTV_MODULATION <DTV-MODULATION>` = QAM_256
+  :ref:`DTV_MODULATION <DTV-MODULATION>` = QAM_256
 
--  :ref:`DTV_INVERSION <DTV-INVERSION>` = INVERSION_AUTO
+  :ref:`DTV_INVERSION <DTV-INVERSION>` = INVERSION_AUTO
 
--  :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>` = 5217000
+  :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>` = 5217000
 
--  :ref:`DTV_INNER_FEC <DTV-INNER-FEC>` = FEC_3_4
+  :ref:`DTV_INNER_FEC <DTV-INNER-FEC>` = FEC_3_4
 
--  :ref:`DTV_TUNE <DTV-TUNE>`
+  :ref:`DTV_TUNE <DTV-TUNE>`
 
 The code that would that would do the above is show in
 :ref:`dtv-prop-example`.
-- 
2.13.3