diff options
Diffstat (limited to 'Documentation/DocBook/media/v4l/vidioc-g-tuner.xml')
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-g-tuner.xml | 594 |
1 files changed, 0 insertions, 594 deletions
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml deleted file mode 100644 index 459b7e561f3c..000000000000 --- a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml +++ /dev/null @@ -1,594 +0,0 @@ -<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><link linkend="sdr">SDR</link> specific tuner types are -<constant>V4L2_TUNER_SDR</constant> and <constant>V4L2_TUNER_RF</constant>. -For SDR devices <structfield>audmode</structfield> field must be -initialized to zero. -The term 'tuner' means SDR receiver in this context.</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, or if the <structfield>capability</structfield> flag -<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 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, or if the <structfield>capability</structfield> flag -<constant>V4L2_TUNER_CAP_1HZ</constant> is set, in units of 1 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> - <row> - <entry><constant>V4L2_TUNER_SDR</constant></entry> - <entry>4</entry> - <entry></entry> - </row> - <row> - <entry><constant>V4L2_TUNER_RF</constant></entry> - <entry>5</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 instead 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> - <row> - <entry><constant>V4L2_TUNER_CAP_HWSEEK_PROG_LIM</constant></entry> - <entry>0x0800</entry> - <entry>The range to search when using the hardware seek functionality - is programmable, see &VIDIOC-S-HW-FREQ-SEEK; for details.</entry> - </row> - <row> - <entry><constant>V4L2_TUNER_CAP_1HZ</constant></entry> - <entry>0x1000</entry> - <entry>When set, tuning frequencies are expressed in units of 1 Hz instead of 62.5 kHz.</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> |