1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 3.. _tuner: 4 5********************* 6Tuners and Modulators 7********************* 8 9 10Tuners 11====== 12 13Video input devices can have one or more tuners demodulating a RF 14signal. Each tuner is associated with one or more video inputs, 15depending on the number of RF connectors on the tuner. The ``type`` 16field of the respective struct :c:type:`v4l2_input` 17returned by the :ref:`VIDIOC_ENUMINPUT` ioctl is 18set to ``V4L2_INPUT_TYPE_TUNER`` and its ``tuner`` field contains the 19index number of the tuner. 20 21Radio input devices have exactly one tuner with index zero, no video 22inputs. 23 24To query and change tuner properties applications use the 25:ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` and 26:ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` ioctls, respectively. The 27struct :c:type:`v4l2_tuner` returned by :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` 28also contains signal status information applicable when the tuner of the 29current video or radio input is queried. 30 31.. note:: 32 33 :ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` does not switch the 34 current tuner, when there is more than one. The tuner is solely 35 determined by the current video input. Drivers must support both ioctls 36 and set the ``V4L2_CAP_TUNER`` flag in the struct :c:type:`v4l2_capability` 37 returned by the :ref:`VIDIOC_QUERYCAP` ioctl when the 38 device has one or more tuners. 39 40 41Modulators 42========== 43 44Video output devices can have one or more modulators, that modulate a 45video signal for radiation or connection to the antenna input of a TV 46set or video recorder. Each modulator is associated with one or more 47video outputs, depending on the number of RF connectors on the 48modulator. The ``type`` field of the respective struct 49:c:type:`v4l2_output` returned by the 50:ref:`VIDIOC_ENUMOUTPUT` ioctl is set to 51``V4L2_OUTPUT_TYPE_MODULATOR`` and its ``modulator`` field contains the 52index number of the modulator. 53 54Radio output devices have exactly one modulator with index zero, no 55video outputs. 56 57A video or radio device cannot support both a tuner and a modulator. Two 58separate device nodes will have to be used for such hardware, one that 59supports the tuner functionality and one that supports the modulator 60functionality. The reason is a limitation with the 61:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl where you 62cannot specify whether the frequency is for a tuner or a modulator. 63 64To query and change modulator properties applications use the 65:ref:`VIDIOC_G_MODULATOR <VIDIOC_G_MODULATOR>` and 66:ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl. Note that 67:ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` does not switch the current modulator, when there 68is more than one at all. The modulator is solely determined by the 69current video output. Drivers must support both ioctls and set the 70``V4L2_CAP_MODULATOR`` flag in the struct 71:c:type:`v4l2_capability` returned by the 72:ref:`VIDIOC_QUERYCAP` ioctl when the device has 73one or more modulators. 74 75 76Radio Frequency 77=============== 78 79To get and set the tuner or modulator radio frequency applications use 80the :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and 81:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl which both take 82a pointer to a struct :c:type:`v4l2_frequency`. These 83ioctls are used for TV and radio devices alike. Drivers must support 84both ioctls when the tuner or modulator ioctls are supported, or when 85the device is a radio device. 86