forked from Minki/linux
c7c1d5a5de
Add SDR specific notes to G_MODULATOR / S_MODULATOR documentation. Signed-off-by: Antti Palosaari <crope@iki.fi> [hans.verkuil@cisco.com: add quotes in "The term 'modulator'"] Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
253 lines
9.5 KiB
XML
253 lines
9.5 KiB
XML
<refentry id="vidioc-g-modulator">
|
|
<refmeta>
|
|
<refentrytitle>ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</refentrytitle>
|
|
&manvol;
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>VIDIOC_G_MODULATOR</refname>
|
|
<refname>VIDIOC_S_MODULATOR</refname>
|
|
<refpurpose>Get or set modulator 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_modulator
|
|
*<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_modulator
|
|
*<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_MODULATOR, VIDIOC_S_MODULATOR</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 modulator applications initialize
|
|
the <structfield>index</structfield> field and zero out the
|
|
<structfield>reserved</structfield> array of a &v4l2-modulator; and
|
|
call the <constant>VIDIOC_G_MODULATOR</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 modulators
|
|
applications shall begin at index zero, incrementing by one until the
|
|
driver returns <errorcode>EINVAL</errorcode>.</para>
|
|
|
|
<para>Modulators have two writable properties, an audio
|
|
modulation set and the radio frequency. To change the modulated audio
|
|
subprograms, applications initialize the <structfield>index
|
|
</structfield> and <structfield>txsubchans</structfield> fields and the
|
|
<structfield>reserved</structfield> array and call the
|
|
<constant>VIDIOC_S_MODULATOR</constant> ioctl. Drivers may choose a
|
|
different audio modulation if the request cannot be satisfied. However
|
|
this is a write-only ioctl, it does not return the actual audio
|
|
modulation selected.</para>
|
|
|
|
<para><link linkend="sdr">SDR</link> specific modulator types are
|
|
<constant>V4L2_TUNER_SDR</constant> and <constant>V4L2_TUNER_RF</constant>.
|
|
For SDR devices <structfield>txsubchans</structfield> field must be
|
|
initialized to zero.
|
|
The term 'modulator' means SDR transmitter 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-modulator">
|
|
<title>struct <structname>v4l2_modulator</structname></title>
|
|
<tgroup cols="3">
|
|
&cs-str;
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>index</structfield></entry>
|
|
<entry>Identifies the modulator, set by the
|
|
application.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>__u8</entry>
|
|
<entry><structfield>name</structfield>[32]</entry>
|
|
<entry>Name of the modulator, a NUL-terminated ASCII
|
|
string. This information is intended for the user.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>capability</structfield></entry>
|
|
<entry>Modulator capability flags. No flags are defined
|
|
for this field, the tuner flags in &v4l2-tuner;
|
|
are used accordingly. The audio flags indicate the ability
|
|
to encode audio subprograms. They will <emphasis>not</emphasis>
|
|
change for example with the current video standard.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>rangelow</structfield></entry>
|
|
<entry>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.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>rangehigh</structfield></entry>
|
|
<entry>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.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>txsubchans</structfield></entry>
|
|
<entry>With this field applications can determine how
|
|
audio sub-carriers shall be modulated. It contains a set of flags as
|
|
defined in <xref linkend="modulator-txsubchans" />. Note the tuner
|
|
<structfield>rxsubchans</structfield> flags are reused, but the
|
|
semantics are different. Video output devices are assumed to have an
|
|
analog or PCM audio input with 1-3 channels. The
|
|
<structfield>txsubchans</structfield> flags select one or more
|
|
channels for modulation, together with some audio subprogram
|
|
indicator, for example a stereo pilot tone.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>type</structfield></entry>
|
|
<entry spanname="hspan">Type of the modulator, see <xref
|
|
linkend="v4l2-tuner-type" />.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>reserved</structfield>[3]</entry>
|
|
<entry>Reserved for future extensions. Drivers and
|
|
applications must set the array to zero.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<table pgwide="1" frame="none" id="modulator-txsubchans">
|
|
<title>Modulator Audio Transmission Flags</title>
|
|
<tgroup cols="3">
|
|
&cs-def;
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry><constant>V4L2_TUNER_SUB_MONO</constant></entry>
|
|
<entry>0x0001</entry>
|
|
<entry>Modulate channel 1 as mono audio, when the input
|
|
has more channels, a down-mix of channel 1 and 2. This flag does not
|
|
combine with <constant>V4L2_TUNER_SUB_STEREO</constant> or
|
|
<constant>V4L2_TUNER_SUB_LANG1</constant>.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>V4L2_TUNER_SUB_STEREO</constant></entry>
|
|
<entry>0x0002</entry>
|
|
<entry>Modulate channel 1 and 2 as left and right
|
|
channel of a stereo audio signal. When the input has only one channel
|
|
or two channels and <constant>V4L2_TUNER_SUB_SAP</constant> is also
|
|
set, channel 1 is encoded as left and right channel. This flag does
|
|
not combine with <constant>V4L2_TUNER_SUB_MONO</constant> or
|
|
<constant>V4L2_TUNER_SUB_LANG1</constant>. When the driver does not
|
|
support stereo audio it shall fall back to mono.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>V4L2_TUNER_SUB_LANG1</constant></entry>
|
|
<entry>0x0008</entry>
|
|
<entry>Modulate channel 1 and 2 as primary and secondary
|
|
language of a bilingual audio signal. When the input has only one
|
|
channel it is used for both languages. It is not possible to encode
|
|
the primary or secondary language only. This flag does not combine
|
|
with <constant>V4L2_TUNER_SUB_MONO</constant>,
|
|
<constant>V4L2_TUNER_SUB_STEREO</constant> or
|
|
<constant>V4L2_TUNER_SUB_SAP</constant>. If the hardware does not
|
|
support the respective audio matrix, or the current video standard
|
|
does not permit bilingual audio the
|
|
<constant>VIDIOC_S_MODULATOR</constant> ioctl shall return an &EINVAL;
|
|
and the driver shall fall back to mono or stereo mode.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry>
|
|
<entry>0x0004</entry>
|
|
<entry>Same effect as
|
|
<constant>V4L2_TUNER_SUB_SAP</constant>.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>V4L2_TUNER_SUB_SAP</constant></entry>
|
|
<entry>0x0004</entry>
|
|
<entry>When combined with <constant>V4L2_TUNER_SUB_MONO
|
|
</constant> the first channel is encoded as mono audio, the last
|
|
channel as Second Audio Program. When the input has only one channel
|
|
it is used for both audio tracks. When the input has three channels
|
|
the mono track is a down-mix of channel 1 and 2. When combined with
|
|
<constant>V4L2_TUNER_SUB_STEREO</constant> channel 1 and 2 are
|
|
encoded as left and right stereo audio, channel 3 as Second Audio
|
|
Program. When the input has only two channels, the first is encoded as
|
|
left and right channel and the second as SAP. When the input has only
|
|
one channel it is used for all audio tracks. It is not possible to
|
|
encode a Second Audio Program only. This flag must combine with
|
|
<constant>V4L2_TUNER_SUB_MONO</constant> or
|
|
<constant>V4L2_TUNER_SUB_STEREO</constant>. If the hardware does not
|
|
support the respective audio matrix, or the current video standard
|
|
does not permit SAP the <constant>VIDIOC_S_MODULATOR</constant> ioctl
|
|
shall return an &EINVAL; and driver shall fall back to mono or stereo
|
|
mode.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>V4L2_TUNER_SUB_RDS</constant></entry>
|
|
<entry>0x0010</entry>
|
|
<entry>Enable the RDS encoder for a radio FM transmitter.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
&return-value;
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><errorcode>EINVAL</errorcode></term>
|
|
<listitem>
|
|
<para>The &v4l2-modulator;
|
|
<structfield>index</structfield> is out of bounds.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
</refentry>
|