0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_G_MODULATOR:
0005
0006 ********************************************
0007 ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR
0008 ********************************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_G_MODULATOR - VIDIOC_S_MODULATOR - Get or set modulator attributes
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_G_MODULATOR
0019
0020 ``int ioctl(int fd, VIDIOC_G_MODULATOR, struct v4l2_modulator *argp)``
0021
0022 .. c:macro:: VIDIOC_S_MODULATOR
0023
0024 ``int ioctl(int fd, VIDIOC_S_MODULATOR, const struct v4l2_modulator *argp)``
0025
0026 Arguments
0027 =========
0028
0029 ``fd``
0030 File descriptor returned by :c:func:`open()`.
0031
0032 ``argp``
0033 Pointer to struct :c:type:`v4l2_modulator`.
0034
0035 Description
0036 ===========
0037
0038 To query the attributes of a modulator applications initialize the
0039 ``index`` field and zero out the ``reserved`` array of a struct
0040 :c:type:`v4l2_modulator` and call the
0041 :ref:`VIDIOC_G_MODULATOR <VIDIOC_G_MODULATOR>` ioctl with a pointer to this structure. Drivers
0042 fill the rest of the structure or return an ``EINVAL`` error code when the
0043 index is out of bounds. To enumerate all modulators applications shall
0044 begin at index zero, incrementing by one until the driver returns
0045 EINVAL.
0046
0047 Modulators have two writable properties, an audio modulation set and the
0048 radio frequency. To change the modulated audio subprograms, applications
0049 initialize the ``index`` and ``txsubchans`` fields and the ``reserved``
0050 array and call the :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl. Drivers may choose a
0051 different audio modulation if the request cannot be satisfied. However
0052 this is a write-only ioctl, it does not return the actual audio
0053 modulation selected.
0054
0055 :ref:`SDR <sdr>` specific modulator types are ``V4L2_TUNER_SDR`` and
0056 ``V4L2_TUNER_RF``. For SDR devices ``txsubchans`` field must be
0057 initialized to zero. The term 'modulator' means SDR transmitter in this
0058 context.
0059
0060 To change the radio frequency the
0061 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available.
0062
0063 .. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{2.4cm}|
0064
0065 .. c:type:: v4l2_modulator
0066
0067 .. flat-table:: struct v4l2_modulator
0068 :header-rows: 0
0069 :stub-columns: 0
0070 :widths: 1 1 2 1 1
0071
0072 * - __u32
0073 - ``index``
0074 - Identifies the modulator, set by the application.
0075 * - __u8
0076 - ``name``\ [32]
0077 - Name of the modulator, a NUL-terminated ASCII string.
0078
0079 This information is intended for the user.
0080 * - __u32
0081 - ``capability``
0082 - Modulator capability flags. No flags are defined for this field,
0083 the tuner flags in struct :c:type:`v4l2_tuner` are
0084 used accordingly. The audio flags indicate the ability to encode
0085 audio subprograms. They will *not* change for example with the
0086 current video standard.
0087 * - __u32
0088 - ``rangelow``
0089 - The lowest tunable frequency in units of 62.5 KHz, or if the
0090 ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units of
0091 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is
0092 set, in units of 1 Hz.
0093 * - __u32
0094 - ``rangehigh``
0095 - The highest tunable frequency in units of 62.5 KHz, or if the
0096 ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units of
0097 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is
0098 set, in units of 1 Hz.
0099 * - __u32
0100 - ``txsubchans``
0101 - With this field applications can determine how audio sub-carriers
0102 shall be modulated. It contains a set of flags as defined in
0103 :ref:`modulator-txsubchans`.
0104
0105 .. note::
0106
0107 The tuner ``rxsubchans`` flags are reused, but the
0108 semantics are different. Video output devices
0109 are assumed to have an analog or PCM audio input with 1-3
0110 channels. The ``txsubchans`` flags select one or more channels
0111 for modulation, together with some audio subprogram indicator,
0112 for example, a stereo pilot tone.
0113 * - __u32
0114 - ``type``
0115 - :cspan:`2` Type of the modulator, see :c:type:`v4l2_tuner_type`.
0116 * - __u32
0117 - ``reserved``\ [3]
0118 - Reserved for future extensions.
0119
0120 Drivers and applications must set the array to zero.
0121
0122 .. tabularcolumns:: |p{6.0cm}|p{2.0cm}|p{9.3cm}|
0123
0124 .. cssclass:: longtable
0125
0126 .. _modulator-txsubchans:
0127
0128 .. flat-table:: Modulator Audio Transmission Flags
0129 :header-rows: 0
0130 :stub-columns: 0
0131 :widths: 3 1 4
0132
0133 * - ``V4L2_TUNER_SUB_MONO``
0134 - 0x0001
0135 - Modulate channel 1 as mono audio, when the input has more
0136 channels, a down-mix of channel 1 and 2. This flag does not
0137 combine with ``V4L2_TUNER_SUB_STEREO`` or
0138 ``V4L2_TUNER_SUB_LANG1``.
0139 * - ``V4L2_TUNER_SUB_STEREO``
0140 - 0x0002
0141 - Modulate channel 1 and 2 as left and right channel of a stereo
0142 audio signal. When the input has only one channel or two channels
0143 and ``V4L2_TUNER_SUB_SAP`` is also set, channel 1 is encoded as
0144 left and right channel. This flag does not combine with
0145 ``V4L2_TUNER_SUB_MONO`` or ``V4L2_TUNER_SUB_LANG1``. When the
0146 driver does not support stereo audio it shall fall back to mono.
0147 * - ``V4L2_TUNER_SUB_LANG1``
0148 - 0x0008
0149 - Modulate channel 1 and 2 as primary and secondary language of a
0150 bilingual audio signal. When the input has only one channel it is
0151 used for both languages. It is not possible to encode the primary
0152 or secondary language only. This flag does not combine with
0153 ``V4L2_TUNER_SUB_MONO``, ``V4L2_TUNER_SUB_STEREO`` or
0154 ``V4L2_TUNER_SUB_SAP``. If the hardware does not support the
0155 respective audio matrix, or the current video standard does not
0156 permit bilingual audio the :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl shall
0157 return an ``EINVAL`` error code and the driver shall fall back to mono
0158 or stereo mode.
0159 * - ``V4L2_TUNER_SUB_LANG2``
0160 - 0x0004
0161 - Same effect as ``V4L2_TUNER_SUB_SAP``.
0162 * - ``V4L2_TUNER_SUB_SAP``
0163 - 0x0004
0164 - When combined with ``V4L2_TUNER_SUB_MONO`` the first channel is
0165 encoded as mono audio, the last channel as Second Audio Program.
0166 When the input has only one channel it is used for both audio
0167 tracks. When the input has three channels the mono track is a
0168 down-mix of channel 1 and 2. When combined with
0169 ``V4L2_TUNER_SUB_STEREO`` channel 1 and 2 are encoded as left and
0170 right stereo audio, channel 3 as Second Audio Program. When the
0171 input has only two channels, the first is encoded as left and
0172 right channel and the second as SAP. When the input has only one
0173 channel it is used for all audio tracks. It is not possible to
0174 encode a Second Audio Program only. This flag must combine with
0175 ``V4L2_TUNER_SUB_MONO`` or ``V4L2_TUNER_SUB_STEREO``. If the
0176 hardware does not support the respective audio matrix, or the
0177 current video standard does not permit SAP the
0178 :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl shall return an ``EINVAL`` error code and
0179 driver shall fall back to mono or stereo mode.
0180 * - ``V4L2_TUNER_SUB_RDS``
0181 - 0x0010
0182 - Enable the RDS encoder for a radio FM transmitter.
0183
0184 Return Value
0185 ============
0186
0187 On success 0 is returned, on error -1 and the ``errno`` variable is set
0188 appropriately. The generic error codes are described at the
0189 :ref:`Generic Error Codes <gen-errors>` chapter.
0190
0191 EINVAL
0192 The struct :c:type:`v4l2_modulator` ``index`` is
0193 out of bounds.
