1<refentry id="vidioc-g-modulator"> 2 <refmeta> 3 <refentrytitle>ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</refentrytitle> 4 &manvol; 5 </refmeta> 6 7 <refnamediv> 8 <refname>VIDIOC_G_MODULATOR</refname> 9 <refname>VIDIOC_S_MODULATOR</refname> 10 <refpurpose>Get or set modulator attributes</refpurpose> 11 </refnamediv> 12 13 <refsynopsisdiv> 14 <funcsynopsis> 15 <funcprototype> 16 <funcdef>int <function>ioctl</function></funcdef> 17 <paramdef>int <parameter>fd</parameter></paramdef> 18 <paramdef>int <parameter>request</parameter></paramdef> 19 <paramdef>struct v4l2_modulator 20*<parameter>argp</parameter></paramdef> 21 </funcprototype> 22 </funcsynopsis> 23 <funcsynopsis> 24 <funcprototype> 25 <funcdef>int <function>ioctl</function></funcdef> 26 <paramdef>int <parameter>fd</parameter></paramdef> 27 <paramdef>int <parameter>request</parameter></paramdef> 28 <paramdef>const struct v4l2_modulator 29*<parameter>argp</parameter></paramdef> 30 </funcprototype> 31 </funcsynopsis> 32 </refsynopsisdiv> 33 34 <refsect1> 35 <title>Arguments</title> 36 37 <variablelist> 38 <varlistentry> 39 <term><parameter>fd</parameter></term> 40 <listitem> 41 <para>&fd;</para> 42 </listitem> 43 </varlistentry> 44 <varlistentry> 45 <term><parameter>request</parameter></term> 46 <listitem> 47 <para>VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</para> 48 </listitem> 49 </varlistentry> 50 <varlistentry> 51 <term><parameter>argp</parameter></term> 52 <listitem> 53 <para></para> 54 </listitem> 55 </varlistentry> 56 </variablelist> 57 </refsect1> 58 59 <refsect1> 60 <title>Description</title> 61 62 <para>To query the attributes of a modulator applications initialize 63the <structfield>index</structfield> field and zero out the 64<structfield>reserved</structfield> array of a &v4l2-modulator; and 65call the <constant>VIDIOC_G_MODULATOR</constant> ioctl with a pointer 66to this structure. Drivers fill the rest of the structure or return an 67&EINVAL; when the index is out of bounds. To enumerate all modulators 68applications shall begin at index zero, incrementing by one until the 69driver returns <errorcode>EINVAL</errorcode>.</para> 70 71 <para>Modulators have two writable properties, an audio 72modulation set and the radio frequency. To change the modulated audio 73subprograms, applications initialize the <structfield>index 74</structfield> and <structfield>txsubchans</structfield> fields and the 75<structfield>reserved</structfield> array and call the 76<constant>VIDIOC_S_MODULATOR</constant> ioctl. Drivers may choose a 77different audio modulation if the request cannot be satisfied. However 78this is a write-only ioctl, it does not return the actual audio 79modulation selected.</para> 80 81 <para><link linkend="sdr">SDR</link> specific modulator types are 82<constant>V4L2_TUNER_SDR</constant> and <constant>V4L2_TUNER_RF</constant>. 83For SDR devices <structfield>txsubchans</structfield> field must be 84initialized to zero. 85The term 'modulator' means SDR transmitter in this context.</para> 86 87 <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl 88is available.</para> 89 90 <table pgwide="1" frame="none" id="v4l2-modulator"> 91 <title>struct <structname>v4l2_modulator</structname></title> 92 <tgroup cols="3"> 93 &cs-str; 94 <tbody valign="top"> 95 <row> 96 <entry>__u32</entry> 97 <entry><structfield>index</structfield></entry> 98 <entry>Identifies the modulator, set by the 99application.</entry> 100 </row> 101 <row> 102 <entry>__u8</entry> 103 <entry><structfield>name</structfield>[32]</entry> 104 <entry>Name of the modulator, a NUL-terminated ASCII 105string. This information is intended for the user.</entry> 106 </row> 107 <row> 108 <entry>__u32</entry> 109 <entry><structfield>capability</structfield></entry> 110 <entry>Modulator capability flags. No flags are defined 111for this field, the tuner flags in &v4l2-tuner; 112are used accordingly. The audio flags indicate the ability 113to encode audio subprograms. They will <emphasis>not</emphasis> 114change for example with the current video standard.</entry> 115 </row> 116 <row> 117 <entry>__u32</entry> 118 <entry><structfield>rangelow</structfield></entry> 119 <entry>The lowest tunable frequency in units of 62.5 120KHz, or if the <structfield>capability</structfield> flag 121<constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 122Hz, or if the <structfield>capability</structfield> flag 123<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 Hz.</entry> 124 </row> 125 <row> 126 <entry>__u32</entry> 127 <entry><structfield>rangehigh</structfield></entry> 128 <entry>The highest tunable frequency in units of 62.5 129KHz, or if the <structfield>capability</structfield> flag 130<constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 131Hz, or if the <structfield>capability</structfield> flag 132<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 Hz.</entry> 133 </row> 134 <row> 135 <entry>__u32</entry> 136 <entry><structfield>txsubchans</structfield></entry> 137 <entry>With this field applications can determine how 138audio sub-carriers shall be modulated. It contains a set of flags as 139defined in <xref linkend="modulator-txsubchans" />. Note the tuner 140<structfield>rxsubchans</structfield> flags are reused, but the 141semantics are different. Video output devices are assumed to have an 142analog or PCM audio input with 1-3 channels. The 143<structfield>txsubchans</structfield> flags select one or more 144channels for modulation, together with some audio subprogram 145indicator, for example a stereo pilot tone.</entry> 146 </row> 147 <row> 148 <entry>__u32</entry> 149 <entry><structfield>type</structfield></entry> 150 <entry spanname="hspan">Type of the modulator, see <xref 151 linkend="v4l2-tuner-type" />.</entry> 152 </row> 153 <row> 154 <entry>__u32</entry> 155 <entry><structfield>reserved</structfield>[3]</entry> 156 <entry>Reserved for future extensions. Drivers and 157applications must set the array to zero.</entry> 158 </row> 159 </tbody> 160 </tgroup> 161 </table> 162 163 <table pgwide="1" frame="none" id="modulator-txsubchans"> 164 <title>Modulator Audio Transmission Flags</title> 165 <tgroup cols="3"> 166 &cs-def; 167 <tbody valign="top"> 168 <row> 169 <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry> 170 <entry>0x0001</entry> 171 <entry>Modulate channel 1 as mono audio, when the input 172has more channels, a down-mix of channel 1 and 2. This flag does not 173combine with <constant>V4L2_TUNER_SUB_STEREO</constant> or 174<constant>V4L2_TUNER_SUB_LANG1</constant>.</entry> 175 </row> 176 <row> 177 <entry><constant>V4L2_TUNER_SUB_STEREO</constant></entry> 178 <entry>0x0002</entry> 179 <entry>Modulate channel 1 and 2 as left and right 180channel of a stereo audio signal. When the input has only one channel 181or two channels and <constant>V4L2_TUNER_SUB_SAP</constant> is also 182set, channel 1 is encoded as left and right channel. This flag does 183not combine with <constant>V4L2_TUNER_SUB_MONO</constant> or 184<constant>V4L2_TUNER_SUB_LANG1</constant>. When the driver does not 185support stereo audio it shall fall back to mono.</entry> 186 </row> 187 <row> 188 <entry><constant>V4L2_TUNER_SUB_LANG1</constant></entry> 189 <entry>0x0008</entry> 190 <entry>Modulate channel 1 and 2 as primary and secondary 191language of a bilingual audio signal. When the input has only one 192channel it is used for both languages. It is not possible to encode 193the primary or secondary language only. This flag does not combine 194with <constant>V4L2_TUNER_SUB_MONO</constant>, 195<constant>V4L2_TUNER_SUB_STEREO</constant> or 196<constant>V4L2_TUNER_SUB_SAP</constant>. If the hardware does not 197support the respective audio matrix, or the current video standard 198does not permit bilingual audio the 199<constant>VIDIOC_S_MODULATOR</constant> ioctl shall return an &EINVAL; 200and the driver shall fall back to mono or stereo mode.</entry> 201 </row> 202 <row> 203 <entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry> 204 <entry>0x0004</entry> 205 <entry>Same effect as 206<constant>V4L2_TUNER_SUB_SAP</constant>.</entry> 207 </row> 208 <row> 209 <entry><constant>V4L2_TUNER_SUB_SAP</constant></entry> 210 <entry>0x0004</entry> 211 <entry>When combined with <constant>V4L2_TUNER_SUB_MONO 212</constant> the first channel is encoded as mono audio, the last 213channel as Second Audio Program. When the input has only one channel 214it is used for both audio tracks. When the input has three channels 215the mono track is a down-mix of channel 1 and 2. When combined with 216<constant>V4L2_TUNER_SUB_STEREO</constant> channel 1 and 2 are 217encoded as left and right stereo audio, channel 3 as Second Audio 218Program. When the input has only two channels, the first is encoded as 219left and right channel and the second as SAP. When the input has only 220one channel it is used for all audio tracks. It is not possible to 221encode a Second Audio Program only. This flag must combine with 222<constant>V4L2_TUNER_SUB_MONO</constant> or 223<constant>V4L2_TUNER_SUB_STEREO</constant>. If the hardware does not 224support the respective audio matrix, or the current video standard 225does not permit SAP the <constant>VIDIOC_S_MODULATOR</constant> ioctl 226shall return an &EINVAL; and driver shall fall back to mono or stereo 227mode.</entry> 228 </row> 229 <row> 230 <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry> 231 <entry>0x0010</entry> 232 <entry>Enable the RDS encoder for a radio FM transmitter.</entry> 233 </row> 234 </tbody> 235 </tgroup> 236 </table> 237 </refsect1> 238 239 <refsect1> 240 &return-value; 241 242 <variablelist> 243 <varlistentry> 244 <term><errorcode>EINVAL</errorcode></term> 245 <listitem> 246 <para>The &v4l2-modulator; 247<structfield>index</structfield> is out of bounds.</para> 248 </listitem> 249 </varlistentry> 250 </variablelist> 251 </refsect1> 252</refentry> 253