123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535 |
- <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>&v4l2-tuner-type;</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 only the
- <constant>V4L2_TUNER_CAP_LOW</constant>,
- <constant>V4L2_TUNER_CAP_STEREO</constant> and
- <constant>V4L2_TUNER_CAP_RDS</constant> flags can be set.</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.</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.</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_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>
- </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>
- <!--
- Local Variables:
- mode: sgml
- sgml-parent-document: "v4l2.sgml"
- indent-tabs-mode: nil
- End:
- -->
|