| <refentry id="vidioc-g-tuner"> |
| <refmeta> |
| <refentrytitle>ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER</refentrytitle> |
| &manvol; |
| </refmeta> |
| |
| <refnamediv> |
| <refname>VIDIOC_G_TUNER</refname> |
| <refname>VIDIOC_S_TUNER</refname> |
| <refpurpose>Get or set tuner attributes</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <funcsynopsis> |
| <funcprototype> |
| <funcdef>int <function>ioctl</function></funcdef> |
| <paramdef>int <parameter>fd</parameter></paramdef> |
| <paramdef>int <parameter>request</parameter></paramdef> |
| <paramdef>struct v4l2_tuner |
| *<parameter>argp</parameter></paramdef> |
| </funcprototype> |
| </funcsynopsis> |
| <funcsynopsis> |
| <funcprototype> |
| <funcdef>int <function>ioctl</function></funcdef> |
| <paramdef>int <parameter>fd</parameter></paramdef> |
| <paramdef>int <parameter>request</parameter></paramdef> |
| <paramdef>const struct v4l2_tuner |
| *<parameter>argp</parameter></paramdef> |
| </funcprototype> |
| </funcsynopsis> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Arguments</title> |
| |
| <variablelist> |
| <varlistentry> |
| <term><parameter>fd</parameter></term> |
| <listitem> |
| <para>&fd;</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><parameter>request</parameter></term> |
| <listitem> |
| <para>VIDIOC_G_TUNER, VIDIOC_S_TUNER</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><parameter>argp</parameter></term> |
| <listitem> |
| <para></para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect1> |
| |
| <refsect1> |
| <title>Description</title> |
| |
| <para>To query the attributes of a tuner applications initialize the |
| <structfield>index</structfield> field and zero out the |
| <structfield>reserved</structfield> array of a &v4l2-tuner; and call the |
| <constant>VIDIOC_G_TUNER</constant> ioctl with a pointer to this |
| structure. Drivers fill the rest of the structure or return an |
| &EINVAL; when the index is out of bounds. To enumerate all tuners |
| applications shall begin at index zero, incrementing by one until the |
| driver returns <errorcode>EINVAL</errorcode>.</para> |
| |
| <para>Tuners have two writable properties, the audio mode and |
| the radio frequency. To change the audio mode, applications initialize |
| the <structfield>index</structfield>, |
| <structfield>audmode</structfield> and |
| <structfield>reserved</structfield> fields and call the |
| <constant>VIDIOC_S_TUNER</constant> ioctl. This will |
| <emphasis>not</emphasis> change the current tuner, which is determined |
| by the current video input. Drivers may choose a different audio mode |
| if the requested mode is invalid or unsupported. Since this is a |
| <!-- FIXME -->write-only ioctl, it does not return the actually |
| selected audio mode.</para> |
| |
| <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl |
| is available.</para> |
| |
| <table pgwide="1" frame="none" id="v4l2-tuner"> |
| <title>struct <structname>v4l2_tuner</structname></title> |
| <tgroup cols="3"> |
| <colspec colname="c1" colwidth="1*" /> |
| <colspec colname="c2" colwidth="1*" /> |
| <colspec colname="c3" colwidth="1*" /> |
| <colspec colname="c4" colwidth="1*" /> |
| <spanspec spanname="hspan" namest="c3" nameend="c4" /> |
| <tbody valign="top"> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>index</structfield></entry> |
| <entry spanname="hspan">Identifies the tuner, set by the |
| application.</entry> |
| </row> |
| <row> |
| <entry>__u8</entry> |
| <entry><structfield>name</structfield>[32]</entry> |
| <entry spanname="hspan"><para>Name of the tuner, a |
| NUL-terminated ASCII string. This information is intended for the |
| user.<!-- FIXME Video inputs already have a name, the purpose of this |
| field is not quite clear.--></para></entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>type</structfield></entry> |
| <entry spanname="hspan">Type of the tuner, see <xref |
| linkend="v4l2-tuner-type" />.</entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>capability</structfield></entry> |
| <entry spanname="hspan"><para>Tuner capability flags, see |
| <xref linkend="tuner-capability" />. Audio flags indicate the ability |
| to decode audio subprograms. They will <emphasis>not</emphasis> |
| change, for example with the current video standard.</para><para>When |
| the structure refers to a radio tuner the |
| <constant>V4L2_TUNER_CAP_LANG1</constant>, |
| <constant>V4L2_TUNER_CAP_LANG2</constant> and |
| <constant>V4L2_TUNER_CAP_NORM</constant> flags can't be used.</para> |
| <para>If multiple frequency bands are supported, then |
| <structfield>capability</structfield> is the union of all |
| <structfield>capability</structfield> fields of each &v4l2-frequency-band;. |
| </para></entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>rangelow</structfield></entry> |
| <entry spanname="hspan">The lowest tunable frequency in |
| units of 62.5 kHz, or if the <structfield>capability</structfield> |
| flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 |
| Hz. If multiple frequency bands are supported, then |
| <structfield>rangelow</structfield> is the lowest frequency |
| of all the frequency bands.</entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>rangehigh</structfield></entry> |
| <entry spanname="hspan">The highest tunable frequency in |
| units of 62.5 kHz, or if the <structfield>capability</structfield> |
| flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 |
| Hz. If multiple frequency bands are supported, then |
| <structfield>rangehigh</structfield> is the highest frequency |
| of all the frequency bands.</entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>rxsubchans</structfield></entry> |
| <entry spanname="hspan"><para>Some tuners or audio |
| decoders can determine the received audio subprograms by analyzing |
| audio carriers, pilot tones or other indicators. To pass this |
| information drivers set flags defined in <xref |
| linkend="tuner-rxsubchans" /> in this field. For |
| example:</para></entry> |
| </row> |
| <row> |
| <entry></entry> |
| <entry></entry> |
| <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry> |
| <entry>receiving mono audio</entry> |
| </row> |
| <row> |
| <entry></entry> |
| <entry></entry> |
| <entry><constant>STEREO | SAP</constant></entry> |
| <entry>receiving stereo audio and a secondary audio |
| program</entry> |
| </row> |
| <row> |
| <entry></entry> |
| <entry></entry> |
| <entry><constant>MONO | STEREO</constant></entry> |
| <entry>receiving mono or stereo audio, the hardware cannot |
| distinguish</entry> |
| </row> |
| <row> |
| <entry></entry> |
| <entry></entry> |
| <entry><constant>LANG1 | LANG2</constant></entry> |
| <entry>receiving bilingual audio</entry> |
| </row> |
| <row> |
| <entry></entry> |
| <entry></entry> |
| <entry><constant>MONO | STEREO | LANG1 | LANG2</constant></entry> |
| <entry>receiving mono, stereo or bilingual |
| audio</entry> |
| </row> |
| <row> |
| <entry></entry> |
| <entry></entry> |
| <entry spanname="hspan"><para>When the |
| <constant>V4L2_TUNER_CAP_STEREO</constant>, |
| <constant>_LANG1</constant>, <constant>_LANG2</constant> or |
| <constant>_SAP</constant> flag is cleared in the |
| <structfield>capability</structfield> field, the corresponding |
| <constant>V4L2_TUNER_SUB_</constant> flag must not be set |
| here.</para><para>This field is valid only if this is the tuner of the |
| current video input, or when the structure refers to a radio |
| tuner.</para></entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>audmode</structfield></entry> |
| <entry spanname="hspan"><para>The selected audio mode, see |
| <xref linkend="tuner-audmode" /> for valid values. The audio mode does |
| not affect audio subprogram detection, and like a <link |
| linkend="control">control</link> it does not automatically change |
| unless the requested mode is invalid or unsupported. See <xref |
| linkend="tuner-matrix" /> for possible results when |
| the selected and received audio programs do not |
| match.</para><para>Currently this is the only field of struct |
| <structname>v4l2_tuner</structname> applications can |
| change.</para></entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>signal</structfield></entry> |
| <entry spanname="hspan">The signal strength if known, ranging |
| from 0 to 65535. Higher values indicate a better signal.</entry> |
| </row> |
| <row> |
| <entry>__s32</entry> |
| <entry><structfield>afc</structfield></entry> |
| <entry spanname="hspan">Automatic frequency control: When the |
| <structfield>afc</structfield> value is negative, the frequency is too |
| low, when positive too high.<!-- FIXME need example what to do when it never |
| settles at zero, &ie; range is what? --></entry> |
| </row> |
| <row> |
| <entry>__u32</entry> |
| <entry><structfield>reserved</structfield>[4]</entry> |
| <entry spanname="hspan">Reserved for future extensions. Drivers and |
| applications must set the array to zero.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <table pgwide="1" frame="none" id="v4l2-tuner-type"> |
| <title>enum v4l2_tuner_type</title> |
| <tgroup cols="3"> |
| &cs-def; |
| <tbody valign="top"> |
| <row> |
| <entry><constant>V4L2_TUNER_RADIO</constant></entry> |
| <entry>1</entry> |
| <entry></entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_ANALOG_TV</constant></entry> |
| <entry>2</entry> |
| <entry></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <table pgwide="1" frame="none" id="tuner-capability"> |
| <title>Tuner and Modulator Capability Flags</title> |
| <tgroup cols="3"> |
| &cs-def; |
| <tbody valign="top"> |
| <row> |
| <entry><constant>V4L2_TUNER_CAP_LOW</constant></entry> |
| <entry>0x0001</entry> |
| <entry>When set, tuning frequencies are expressed in units of |
| 62.5 Hz, otherwise in units of 62.5 kHz.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_CAP_NORM</constant></entry> |
| <entry>0x0002</entry> |
| <entry>This is a multi-standard tuner; the video standard |
| can or must be switched. (B/G PAL tuners for example are typically not |
| considered multi-standard because the video standard is automatically |
| determined from the frequency band.) The set of supported video |
| standards is available from the &v4l2-input; pointing to this tuner, |
| see the description of ioctl &VIDIOC-ENUMINPUT; for details. Only |
| <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_CAP_HWSEEK_BOUNDED</constant></entry> |
| <entry>0x0004</entry> |
| <entry>If set, then this tuner supports the hardware seek functionality |
| where the seek stops when it reaches the end of the frequency range.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_CAP_HWSEEK_WRAP</constant></entry> |
| <entry>0x0008</entry> |
| <entry>If set, then this tuner supports the hardware seek functionality |
| where the seek wraps around when it reaches the end of the frequency range.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_CAP_STEREO</constant></entry> |
| <entry>0x0010</entry> |
| <entry>Stereo audio reception is supported.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_CAP_LANG1</constant></entry> |
| <entry>0x0040</entry> |
| <entry>Reception of the primary language of a bilingual |
| audio program is supported. Bilingual audio is a feature of |
| two-channel systems, transmitting the primary language monaural on the |
| main audio carrier and a secondary language monaural on a second |
| carrier. Only |
| <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_CAP_LANG2</constant></entry> |
| <entry>0x0020</entry> |
| <entry>Reception of the secondary language of a bilingual |
| audio program is supported. Only |
| <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_CAP_SAP</constant></entry> |
| <entry>0x0020</entry> |
| <entry><para>Reception of a secondary audio program is |
| supported. This is a feature of the BTSC system which accompanies the |
| NTSC video standard. Two audio carriers are available for mono or |
| stereo transmissions of a primary language, and an independent third |
| carrier for a monaural secondary language. Only |
| <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</para><para>Note the |
| <constant>V4L2_TUNER_CAP_LANG2</constant> and |
| <constant>V4L2_TUNER_CAP_SAP</constant> flags are synonyms. |
| <constant>V4L2_TUNER_CAP_SAP</constant> applies when the tuner |
| supports the <constant>V4L2_STD_NTSC_M</constant> video |
| standard.</para><!-- FIXME what if PAL+NTSC and Bi but not SAP? --></entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_CAP_RDS</constant></entry> |
| <entry>0x0080</entry> |
| <entry>RDS capture is supported. This capability is only valid for |
| radio tuners.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant></entry> |
| <entry>0x0100</entry> |
| <entry>The RDS data is passed as unparsed RDS blocks.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant></entry> |
| <entry>0x0200</entry> |
| <entry>The RDS data is parsed by the hardware and set via controls.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_CAP_FREQ_BANDS</constant></entry> |
| <entry>0x0400</entry> |
| <entry>The &VIDIOC-ENUM-FREQ-BANDS; ioctl can be used to enumerate |
| the available frequency bands.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <table pgwide="1" frame="none" id="tuner-rxsubchans"> |
| <title>Tuner Audio Reception Flags</title> |
| <tgroup cols="3"> |
| &cs-def; |
| <tbody valign="top"> |
| <row> |
| <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry> |
| <entry>0x0001</entry> |
| <entry>The tuner receives a mono audio signal.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_SUB_STEREO</constant></entry> |
| <entry>0x0002</entry> |
| <entry>The tuner receives a stereo audio signal.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_SUB_LANG1</constant></entry> |
| <entry>0x0008</entry> |
| <entry>The tuner receives the primary language of a |
| bilingual audio signal. Drivers must clear this flag when the current |
| video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry> |
| <entry>0x0004</entry> |
| <entry>The tuner receives the secondary language of a |
| bilingual audio signal (or a second audio program).</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_SUB_SAP</constant></entry> |
| <entry>0x0004</entry> |
| <entry>The tuner receives a Second Audio Program. Note the |
| <constant>V4L2_TUNER_SUB_LANG2</constant> and |
| <constant>V4L2_TUNER_SUB_SAP</constant> flags are synonyms. The |
| <constant>V4L2_TUNER_SUB_SAP</constant> flag applies when the |
| current video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry> |
| <entry>0x0010</entry> |
| <entry>The tuner receives an RDS channel.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <table pgwide="1" frame="none" id="tuner-audmode"> |
| <title>Tuner Audio Modes</title> |
| <tgroup cols="3"> |
| &cs-def; |
| <tbody valign="top"> |
| <row> |
| <entry><constant>V4L2_TUNER_MODE_MONO</constant></entry> |
| <entry>0</entry> |
| <entry>Play mono audio. When the tuner receives a stereo |
| signal this a down-mix of the left and right channel. When the tuner |
| receives a bilingual or SAP signal this mode selects the primary |
| language.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_MODE_STEREO</constant></entry> |
| <entry>1</entry> |
| <entry><para>Play stereo audio. When the tuner receives |
| bilingual audio it may play different languages on the left and right |
| channel or the primary language is played on both channels.</para><para>Playing |
| different languages in this mode is |
| deprecated. New drivers should do this only in |
| <constant>MODE_LANG1_LANG2</constant>.</para><para>When the tuner |
| receives no stereo signal or does not support stereo reception the |
| driver shall fall back to <constant>MODE_MONO</constant>.</para></entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_MODE_LANG1</constant></entry> |
| <entry>3</entry> |
| <entry>Play the primary language, mono or stereo. Only |
| <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this |
| mode.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_MODE_LANG2</constant></entry> |
| <entry>2</entry> |
| <entry>Play the secondary language, mono. When the tuner |
| receives no bilingual audio or SAP, or their reception is not |
| supported the driver shall fall back to mono or stereo mode. Only |
| <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this |
| mode.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_MODE_SAP</constant></entry> |
| <entry>2</entry> |
| <entry>Play the Second Audio Program. When the tuner |
| receives no bilingual audio or SAP, or their reception is not |
| supported the driver shall fall back to mono or stereo mode. Only |
| <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this mode. |
| Note the <constant>V4L2_TUNER_MODE_LANG2</constant> and |
| <constant>V4L2_TUNER_MODE_SAP</constant> are synonyms.</entry> |
| </row> |
| <row> |
| <entry><constant>V4L2_TUNER_MODE_LANG1_LANG2</constant></entry> |
| <entry>4</entry> |
| <entry>Play the primary language on the left channel, the |
| secondary language on the right channel. When the tuner receives no |
| bilingual audio or SAP, it shall fall back to |
| <constant>MODE_LANG1</constant> or <constant>MODE_MONO</constant>. |
| Only <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this |
| mode.</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| |
| <table pgwide="1" frame="all" id="tuner-matrix"> |
| <title>Tuner Audio Matrix</title> |
| <tgroup cols="6" align="center"> |
| <colspec align="left" /> |
| <colspec colname="c2" colwidth="1*" /> |
| <colspec colwidth="1*" /> |
| <colspec colwidth="1*" /> |
| <colspec colnum="6" colname="c6" colwidth="1*" /> |
| <spanspec namest="c2" nameend="c6" spanname="hspan" align="center" /> |
| <thead> |
| <row> |
| <entry></entry> |
| <entry spanname="hspan">Selected |
| <constant>V4L2_TUNER_MODE_</constant></entry> |
| </row> |
| <row> |
| <entry>Received <constant>V4L2_TUNER_SUB_</constant></entry> |
| <entry><constant>MONO</constant></entry> |
| <entry><constant>STEREO</constant></entry> |
| <entry><constant>LANG1</constant></entry> |
| <entry><constant>LANG2 = SAP</constant></entry> |
| <entry><constant>LANG1_LANG2</constant><footnote><para>This |
| mode has been added in Linux 2.6.17 and may not be supported by older |
| drivers.</para></footnote></entry> |
| </row> |
| </thead> |
| <tbody valign="top"> |
| <row> |
| <entry><constant>MONO</constant></entry> |
| <entry>Mono</entry> |
| <entry>Mono/Mono</entry> |
| <entry>Mono</entry> |
| <entry>Mono</entry> |
| <entry>Mono/Mono</entry> |
| </row> |
| <row> |
| <entry><constant>MONO | SAP</constant></entry> |
| <entry>Mono</entry> |
| <entry>Mono/Mono</entry> |
| <entry>Mono</entry> |
| <entry>SAP</entry> |
| <entry>Mono/SAP (preferred) or Mono/Mono</entry> |
| </row> |
| <row> |
| <entry><constant>STEREO</constant></entry> |
| <entry>L+R</entry> |
| <entry>L/R</entry> |
| <entry>Stereo L/R (preferred) or Mono L+R</entry> |
| <entry>Stereo L/R (preferred) or Mono L+R</entry> |
| <entry>L/R (preferred) or L+R/L+R</entry> |
| </row> |
| <row> |
| <entry><constant>STEREO | SAP</constant></entry> |
| <entry>L+R</entry> |
| <entry>L/R</entry> |
| <entry>Stereo L/R (preferred) or Mono L+R</entry> |
| <entry>SAP</entry> |
| <entry>L+R/SAP (preferred) or L/R or L+R/L+R</entry> |
| </row> |
| <row> |
| <entry><constant>LANG1 | LANG2</constant></entry> |
| <entry>Language 1</entry> |
| <entry>Lang1/Lang2 (deprecated<footnote><para>Playback of |
| both languages in <constant>MODE_STEREO</constant> is deprecated. In |
| the future drivers should produce only the primary language in this |
| mode. Applications should request |
| <constant>MODE_LANG1_LANG2</constant> to record both languages or a |
| stereo signal.</para></footnote>) or |
| Lang1/Lang1</entry> |
| <entry>Language 1</entry> |
| <entry>Language 2</entry> |
| <entry>Lang1/Lang2 (preferred) or Lang1/Lang1</entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| </refsect1> |
| |
| <refsect1> |
| &return-value; |
| |
| <variablelist> |
| <varlistentry> |
| <term><errorcode>EINVAL</errorcode></term> |
| <listitem> |
| <para>The &v4l2-tuner; <structfield>index</structfield> is |
| out of bounds.</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect1> |
| </refentry> |