0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002
0003 .. _frontend-properties:
0004
0005 **************
0006 Property types
0007 **************
0008
0009 Tuning into a Digital TV physical channel and starting decoding it
0010 requires changing a set of parameters, in order to control the tuner,
0011 the demodulator, the Linear Low-noise Amplifier (LNA) and to set the
0012 antenna subsystem via Satellite Equipment Control - SEC (on satellite
0013 systems). The actual parameters are specific to each particular digital
0014 TV standards, and may change as the digital TV specs evolves.
0015
0016 In the past (up to DVB API version 3 - DVBv3), the strategy used was to have a
0017 union with the parameters needed to tune for DVB-S, DVB-C, DVB-T and
0018 ATSC delivery systems grouped there. The problem is that, as the second
0019 generation standards appeared, the size of such union was not big
0020 enough to group the structs that would be required for those new
0021 standards. Also, extending it would break userspace.
0022
0023 So, the legacy union/struct based approach was deprecated, in favor
0024 of a properties set approach. On such approach,
0025 :ref:`FE_GET_PROPERTY and FE_SET_PROPERTY <FE_GET_PROPERTY>` are used
0026 to setup the frontend and read its status.
0027
0028 The actual action is determined by a set of dtv_property cmd/data pairs.
0029 With one single ioctl, is possible to get/set up to 64 properties.
0030
0031 This section describes the new and recommended way to set the frontend,
0032 with supports all digital TV delivery systems.
0033
0034 .. note::
0035
0036 1. On Linux DVB API version 3, setting a frontend was done via
0037 struct :c:type:`dvb_frontend_parameters`.
0038
0039 2. Don't use DVB API version 3 calls on hardware with supports
0040 newer standards. Such API provides no support or a very limited
0041 support to new standards and/or new hardware.
0042
0043 3. Nowadays, most frontends support multiple delivery systems.
0044 Only with DVB API version 5 calls it is possible to switch between
0045 the multiple delivery systems supported by a frontend.
0046
0047 4. DVB API version 5 is also called *S2API*, as the first
0048 new standard added to it was DVB-S2.
0049
0050 **Example**: in order to set the hardware to tune into a DVB-C channel
0051 at 651 kHz, modulated with 256-QAM, FEC 3/4 and symbol rate of 5.217
0052 Mbauds, those properties should be sent to
0053 :ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` ioctl:
0054
0055 :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` = SYS_DVBC_ANNEX_A
0056
0057 :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` = 651000000
0058
0059 :ref:`DTV_MODULATION <DTV-MODULATION>` = QAM_256
0060
0061 :ref:`DTV_INVERSION <DTV-INVERSION>` = INVERSION_AUTO
0062
0063 :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>` = 5217000
0064
0065 :ref:`DTV_INNER_FEC <DTV-INNER-FEC>` = FEC_3_4
0066
0067 :ref:`DTV_TUNE <DTV-TUNE>`
0068
0069 The code that would that would do the above is show in
0070 :ref:`dtv-prop-example`.
0071
0072 .. code-block:: c
0073 :caption: Example: Setting digital TV frontend properties
0074 :name: dtv-prop-example
0075
0076 #include <stdio.h>
0077 #include <fcntl.h>
0078 #include <sys/ioctl.h>
0079 #include <linux/dvb/frontend.h>
0080
0081 static struct dtv_property props[] = {
0082 { .cmd = DTV_DELIVERY_SYSTEM, .u.data = SYS_DVBC_ANNEX_A },
0083 { .cmd = DTV_FREQUENCY, .u.data = 651000000 },
0084 { .cmd = DTV_MODULATION, .u.data = QAM_256 },
0085 { .cmd = DTV_INVERSION, .u.data = INVERSION_AUTO },
0086 { .cmd = DTV_SYMBOL_RATE, .u.data = 5217000 },
0087 { .cmd = DTV_INNER_FEC, .u.data = FEC_3_4 },
0088 { .cmd = DTV_TUNE }
0089 };
0090
0091 static struct dtv_properties dtv_prop = {
0092 .num = 6, .props = props
0093 };
0094
0095 int main(void)
0096 {
0097 int fd = open("/dev/dvb/adapter0/frontend0", O_RDWR);
0098
0099 if (!fd) {
0100 perror ("open");
0101 return -1;
0102 }
0103 if (ioctl(fd, FE_SET_PROPERTY, &dtv_prop) == -1) {
0104 perror("ioctl");
0105 return -1;
0106 }
0107 printf("Frontend set\\n");
0108 return 0;
0109 }
0110
0111 .. attention:: While it is possible to directly call the Kernel code like the
0112 above example, it is strongly recommended to use
0113 `libdvbv5 <https://linuxtv.org/docs/libdvbv5/index.html>`__, as it
0114 provides abstraction to work with the supported digital TV standards and
0115 provides methods for usual operations like program scanning and to
0116 read/write channel descriptor files.
0117
0118 .. toctree::
0119 :maxdepth: 1
0120
0121 fe_property_parameters
0122 frontend-stat-properties
0123 frontend-property-terrestrial-systems
0124 frontend-property-cable-systems
0125 frontend-property-satellite-systems
0126 frontend-header
