127 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2 3.. _frontend-properties:4 5**************6Property types7**************8 9Tuning into a Digital TV physical channel and starting decoding it10requires changing a set of parameters, in order to control the tuner,11the demodulator, the Linear Low-noise Amplifier (LNA) and to set the12antenna subsystem via Satellite Equipment Control - SEC (on satellite13systems). The actual parameters are specific to each particular digital14TV standards, and may change as the digital TV specs evolves.15 16In the past (up to DVB API version 3 - DVBv3), the strategy used was to have a17union with the parameters needed to tune for DVB-S, DVB-C, DVB-T and18ATSC delivery systems grouped there. The problem is that, as the second19generation standards appeared, the size of such union was not big20enough to group the structs that would be required for those new21standards. Also, extending it would break userspace.22 23So, the legacy union/struct based approach was deprecated, in favor24of a properties set approach. On such approach,25:ref:`FE_GET_PROPERTY and FE_SET_PROPERTY <FE_GET_PROPERTY>` are used26to setup the frontend and read its status.27 28The actual action is determined by a set of dtv_property cmd/data pairs.29With one single ioctl, is possible to get/set up to 64 properties.30 31This section describes the new and recommended way to set the frontend,32with supports all digital TV delivery systems.33 34.. note::35 36 1. On Linux DVB API version 3, setting a frontend was done via37 struct :c:type:`dvb_frontend_parameters`.38 39 2. Don't use DVB API version 3 calls on hardware with supports40 newer standards. Such API provides no support or a very limited41 support to new standards and/or new hardware.42 43 3. Nowadays, most frontends support multiple delivery systems.44 Only with DVB API version 5 calls it is possible to switch between45 the multiple delivery systems supported by a frontend.46 47 4. DVB API version 5 is also called *S2API*, as the first48 new standard added to it was DVB-S2.49 50**Example**: in order to set the hardware to tune into a DVB-C channel51at 651 kHz, modulated with 256-QAM, FEC 3/4 and symbol rate of 5.21752Mbauds, those properties should be sent to53:ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` ioctl:54 55 :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` = SYS_DVBC_ANNEX_A56 57 :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` = 65100000058 59 :ref:`DTV_MODULATION <DTV-MODULATION>` = QAM_25660 61 :ref:`DTV_INVERSION <DTV-INVERSION>` = INVERSION_AUTO62 63 :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>` = 521700064 65 :ref:`DTV_INNER_FEC <DTV-INNER-FEC>` = FEC_3_466 67 :ref:`DTV_TUNE <DTV-TUNE>`68 69The code that would that would do the above is show in70:ref:`dtv-prop-example`.71 72.. code-block:: c73 :caption: Example: Setting digital TV frontend properties74 :name: dtv-prop-example75 76 #include <stdio.h>77 #include <fcntl.h>78 #include <sys/ioctl.h>79 #include <linux/dvb/frontend.h>80 81 static struct dtv_property props[] = {82 { .cmd = DTV_DELIVERY_SYSTEM, .u.data = SYS_DVBC_ANNEX_A },83 { .cmd = DTV_FREQUENCY, .u.data = 651000000 },84 { .cmd = DTV_MODULATION, .u.data = QAM_256 },85 { .cmd = DTV_INVERSION, .u.data = INVERSION_AUTO },86 { .cmd = DTV_SYMBOL_RATE, .u.data = 5217000 },87 { .cmd = DTV_INNER_FEC, .u.data = FEC_3_4 },88 { .cmd = DTV_TUNE }89 };90 91 static struct dtv_properties dtv_prop = {92 .num = 6, .props = props93 };94 95 int main(void)96 {97 int fd = open("/dev/dvb/adapter0/frontend0", O_RDWR);98 99 if (!fd) {100 perror ("open");101 return -1;102 }103 if (ioctl(fd, FE_SET_PROPERTY, &dtv_prop) == -1) {104 perror("ioctl");105 return -1;106 }107 printf("Frontend set\\n");108 return 0;109 }110 111.. attention:: While it is possible to directly call the Kernel code like the112 above example, it is strongly recommended to use113 `libdvbv5 <https://linuxtv.org/docs/libdvbv5/index.html>`__, as it114 provides abstraction to work with the supported digital TV standards and115 provides methods for usual operations like program scanning and to116 read/write channel descriptor files.117 118.. toctree::119 :maxdepth: 1120 121 fe_property_parameters122 frontend-stat-properties123 frontend-property-terrestrial-systems124 frontend-property-cable-systems125 frontend-property-satellite-systems126 frontend-header127