Documentation/media/uapi/v4l/tuner.rst

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