0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002
0003 .. _tuner:
0004
0005 *********************
0006 Tuners and Modulators
0007 *********************
0008
0009
0010 Tuners
0011 ======
0012
0013 Video input devices can have one or more tuners demodulating a RF
0014 signal. Each tuner is associated with one or more video inputs,
0015 depending on the number of RF connectors on the tuner. The ``type``
0016 field of the respective struct :c:type:`v4l2_input`
0017 returned by the :ref:`VIDIOC_ENUMINPUT` ioctl is
0018 set to ``V4L2_INPUT_TYPE_TUNER`` and its ``tuner`` field contains the
0019 index number of the tuner.
0020
0021 Radio input devices have exactly one tuner with index zero, no video
0022 inputs.
0023
0024 To query and change tuner properties applications use the
0025 :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` and
0026 :ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` ioctls, respectively. The
0027 struct :c:type:`v4l2_tuner` returned by :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>`
0028 also contains signal status information applicable when the tuner of the
0029 current video or radio input is queried.
0030
0031 .. note::
0032
0033 :ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` does not switch the
0034 current tuner, when there is more than one. The tuner is solely
0035 determined by the current video input. Drivers must support both ioctls
0036 and set the ``V4L2_CAP_TUNER`` flag in the struct :c:type:`v4l2_capability`
0037 returned by the :ref:`VIDIOC_QUERYCAP` ioctl when the
0038 device has one or more tuners.
0039
0040
0041 Modulators
0042 ==========
0043
0044 Video output devices can have one or more modulators, that modulate a
0045 video signal for radiation or connection to the antenna input of a TV
0046 set or video recorder. Each modulator is associated with one or more
0047 video outputs, depending on the number of RF connectors on the
0048 modulator. The ``type`` field of the respective struct
0049 :c:type:`v4l2_output` returned by the
0050 :ref:`VIDIOC_ENUMOUTPUT` ioctl is set to
0051 ``V4L2_OUTPUT_TYPE_MODULATOR`` and its ``modulator`` field contains the
0052 index number of the modulator.
0053
0054 Radio output devices have exactly one modulator with index zero, no
0055 video outputs.
0056
0057 A video or radio device cannot support both a tuner and a modulator. Two
0058 separate device nodes will have to be used for such hardware, one that
0059 supports the tuner functionality and one that supports the modulator
0060 functionality. The reason is a limitation with the
0061 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl where you
0062 cannot specify whether the frequency is for a tuner or a modulator.
0063
0064 To query and change modulator properties applications use the
0065 :ref:`VIDIOC_G_MODULATOR <VIDIOC_G_MODULATOR>` and
0066 :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl. Note that
0067 :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` does not switch the current modulator, when there
0068 is more than one at all. The modulator is solely determined by the
0069 current video output. Drivers must support both ioctls and set the
0070 ``V4L2_CAP_MODULATOR`` flag in the struct
0071 :c:type:`v4l2_capability` returned by the
0072 :ref:`VIDIOC_QUERYCAP` ioctl when the device has
0073 one or more modulators.
0074
0075
0076 Radio Frequency
0077 ===============
0078
0079 To get and set the tuner or modulator radio frequency applications use
0080 the :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and
0081 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl which both take
0082 a pointer to a struct :c:type:`v4l2_frequency`. These
0083 ioctls are used for TV and radio devices alike. Drivers must support
0084 both ioctls when the tuner or modulator ioctls are supported, or when
0085 the device is a radio device.
