summaryrefslogtreecommitdiff
path: root/Documentation/media/uapi/dvb/dvbproperty.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/media/uapi/dvb/dvbproperty.rst')
-rw-r--r--Documentation/media/uapi/dvb/dvbproperty.rst90
1 files changed, 49 insertions, 41 deletions
diff --git a/Documentation/media/uapi/dvb/dvbproperty.rst b/Documentation/media/uapi/dvb/dvbproperty.rst
index dd2d71ce43fa..1a56c1724e59 100644
--- a/Documentation/media/uapi/dvb/dvbproperty.rst
+++ b/Documentation/media/uapi/dvb/dvbproperty.rst
@@ -2,63 +2,76 @@
.. _frontend-properties:
-DVB Frontend properties
-=======================
+**************
+Property types
+**************
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, 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 - DVBv3), 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. On such approach,
+:ref:`FE_GET_PROPERTY and FE_SET_PROPERTY <FE_GET_PROPERTY>` are used
+to setup the frontend and read its status.
+
+The actual action is determined by a set of dtv_property cmd/data pairs.
+With one single ioctl, is possible to get/set up to 64 properties.
+
+This section describes the new and recommended way to set the frontend,
+with supports 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.
-
-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
+ 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 API version 5 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**: 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`.
-.. _dtv-prop-example:
-
-Example: Setting digital TV frontend properties
-===============================================
-
.. code-block:: c
+ :caption: Example: Setting digital TV frontend properties
+ :name: dtv-prop-example
#include <stdio.h>
#include <fcntl.h>
@@ -102,17 +115,12 @@ Example: Setting digital TV frontend properties
provides methods for usual operations like program scanning and to
read/write channel descriptor files.
-
.. toctree::
:maxdepth: 1
- dtv-stats
- dtv-fe-stats
- dtv-property
- dtv-properties
- dvbproperty-006
fe_property_parameters
frontend-stat-properties
frontend-property-terrestrial-systems
frontend-property-cable-systems
frontend-property-satellite-systems
+ frontend-header