1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 3.. _VIDIOC_G_MODULATOR: 4 5******************************************** 6ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR 7******************************************** 8 9Name 10==== 11 12VIDIOC_G_MODULATOR - VIDIOC_S_MODULATOR - Get or set modulator attributes 13 14 15Synopsis 16======== 17 18.. c:function:: int ioctl( int fd, VIDIOC_G_MODULATOR, struct v4l2_modulator *argp ) 19 :name: VIDIOC_G_MODULATOR 20 21.. c:function:: int ioctl( int fd, VIDIOC_S_MODULATOR, const struct v4l2_modulator *argp ) 22 :name: VIDIOC_S_MODULATOR 23 24 25Arguments 26========= 27 28``fd`` 29 File descriptor returned by :ref:`open() <func-open>`. 30 31``argp`` 32 Pointer to struct :c:type:`v4l2_modulator`. 33 34 35Description 36=========== 37 38To query the attributes of a modulator applications initialize the 39``index`` field and zero out the ``reserved`` array of a struct 40:c:type:`v4l2_modulator` and call the 41:ref:`VIDIOC_G_MODULATOR <VIDIOC_G_MODULATOR>` ioctl with a pointer to this structure. Drivers 42fill the rest of the structure or return an ``EINVAL`` error code when the 43index is out of bounds. To enumerate all modulators applications shall 44begin at index zero, incrementing by one until the driver returns 45EINVAL. 46 47Modulators have two writable properties, an audio modulation set and the 48radio frequency. To change the modulated audio subprograms, applications 49initialize the ``index`` and ``txsubchans`` fields and the ``reserved`` 50array and call the :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl. Drivers may choose a 51different audio modulation if the request cannot be satisfied. However 52this is a write-only ioctl, it does not return the actual audio 53modulation selected. 54 55:ref:`SDR <sdr>` specific modulator types are ``V4L2_TUNER_SDR`` and 56``V4L2_TUNER_RF``. For SDR devices ``txsubchans`` field must be 57initialized to zero. The term 'modulator' means SDR transmitter in this 58context. 59 60To change the radio frequency the 61:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available. 62 63 64.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{3.0cm}| 65 66.. c:type:: v4l2_modulator 67 68.. flat-table:: struct v4l2_modulator 69 :header-rows: 0 70 :stub-columns: 0 71 :widths: 1 1 2 1 1 72 73 * - __u32 74 - ``index`` 75 - Identifies the modulator, set by the application. 76 * - __u8 77 - ``name``\ [32] 78 - Name of the modulator, a NUL-terminated ASCII string. 79 80 This information is intended for the user. 81 * - __u32 82 - ``capability`` 83 - Modulator capability flags. No flags are defined for this field, 84 the tuner flags in struct :c:type:`v4l2_tuner` are 85 used accordingly. The audio flags indicate the ability to encode 86 audio subprograms. They will *not* change for example with the 87 current video standard. 88 * - __u32 89 - ``rangelow`` 90 - The lowest tunable frequency in units of 62.5 KHz, or if the 91 ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units of 92 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is 93 set, in units of 1 Hz. 94 * - __u32 95 - ``rangehigh`` 96 - The highest tunable frequency in units of 62.5 KHz, or if the 97 ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units of 98 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is 99 set, in units of 1 Hz. 100 * - __u32 101 - ``txsubchans`` 102 - With this field applications can determine how audio sub-carriers 103 shall be modulated. It contains a set of flags as defined in 104 :ref:`modulator-txsubchans`. 105 106 .. note:: 107 108 The tuner ``rxsubchans`` flags are reused, but the 109 semantics are different. Video output devices 110 are assumed to have an analog or PCM audio input with 1-3 111 channels. The ``txsubchans`` flags select one or more channels 112 for modulation, together with some audio subprogram indicator, 113 for example, a stereo pilot tone. 114 * - __u32 115 - ``type`` 116 - :cspan:`2` Type of the modulator, see :c:type:`v4l2_tuner_type`. 117 * - __u32 118 - ``reserved``\ [3] 119 - Reserved for future extensions. 120 121 Drivers and applications must set the array to zero. 122 123 124 125.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| 126 127.. _modulator-txsubchans: 128 129.. flat-table:: Modulator Audio Transmission Flags 130 :header-rows: 0 131 :stub-columns: 0 132 :widths: 3 1 4 133 134 * - ``V4L2_TUNER_SUB_MONO`` 135 - 0x0001 136 - Modulate channel 1 as mono audio, when the input has more 137 channels, a down-mix of channel 1 and 2. This flag does not 138 combine with ``V4L2_TUNER_SUB_STEREO`` or 139 ``V4L2_TUNER_SUB_LANG1``. 140 * - ``V4L2_TUNER_SUB_STEREO`` 141 - 0x0002 142 - Modulate channel 1 and 2 as left and right channel of a stereo 143 audio signal. When the input has only one channel or two channels 144 and ``V4L2_TUNER_SUB_SAP`` is also set, channel 1 is encoded as 145 left and right channel. This flag does not combine with 146 ``V4L2_TUNER_SUB_MONO`` or ``V4L2_TUNER_SUB_LANG1``. When the 147 driver does not support stereo audio it shall fall back to mono. 148 * - ``V4L2_TUNER_SUB_LANG1`` 149 - 0x0008 150 - Modulate channel 1 and 2 as primary and secondary language of a 151 bilingual audio signal. When the input has only one channel it is 152 used for both languages. It is not possible to encode the primary 153 or secondary language only. This flag does not combine with 154 ``V4L2_TUNER_SUB_MONO``, ``V4L2_TUNER_SUB_STEREO`` or 155 ``V4L2_TUNER_SUB_SAP``. If the hardware does not support the 156 respective audio matrix, or the current video standard does not 157 permit bilingual audio the :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl shall 158 return an ``EINVAL`` error code and the driver shall fall back to mono 159 or stereo mode. 160 * - ``V4L2_TUNER_SUB_LANG2`` 161 - 0x0004 162 - Same effect as ``V4L2_TUNER_SUB_SAP``. 163 * - ``V4L2_TUNER_SUB_SAP`` 164 - 0x0004 165 - When combined with ``V4L2_TUNER_SUB_MONO`` the first channel is 166 encoded as mono audio, the last channel as Second Audio Program. 167 When the input has only one channel it is used for both audio 168 tracks. When the input has three channels the mono track is a 169 down-mix of channel 1 and 2. When combined with 170 ``V4L2_TUNER_SUB_STEREO`` channel 1 and 2 are encoded as left and 171 right stereo audio, channel 3 as Second Audio Program. When the 172 input has only two channels, the first is encoded as left and 173 right channel and the second as SAP. When the input has only one 174 channel it is used for all audio tracks. It is not possible to 175 encode a Second Audio Program only. This flag must combine with 176 ``V4L2_TUNER_SUB_MONO`` or ``V4L2_TUNER_SUB_STEREO``. If the 177 hardware does not support the respective audio matrix, or the 178 current video standard does not permit SAP the 179 :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl shall return an ``EINVAL`` error code and 180 driver shall fall back to mono or stereo mode. 181 * - ``V4L2_TUNER_SUB_RDS`` 182 - 0x0010 183 - Enable the RDS encoder for a radio FM transmitter. 184 185 186Return Value 187============ 188 189On success 0 is returned, on error -1 and the ``errno`` variable is set 190appropriately. The generic error codes are described at the 191:ref:`Generic Error Codes <gen-errors>` chapter. 192 193EINVAL 194 The struct :c:type:`v4l2_modulator` ``index`` is 195 out of bounds. 196