summaryrefslogtreecommitdiff
path: root/Documentation/DocBook/v4l/vidioc-g-tuner.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/v4l/vidioc-g-tuner.xml')
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-tuner.xml535
1 files changed, 535 insertions, 0 deletions
diff --git a/Documentation/DocBook/v4l/vidioc-g-tuner.xml b/Documentation/DocBook/v4l/vidioc-g-tuner.xml
new file mode 100644
index 000000000000..bd98c734c06b
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-g-tuner.xml
@@ -0,0 +1,535 @@
+<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&nbsp;Hz, otherwise in units of 62.5&nbsp;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&nbsp;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&nbsp;1</entry>
+ <entry>Language&nbsp;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:
+-->