summaryrefslogtreecommitdiff
path: root/v4l2-spec
diff options
context:
space:
mode:
Diffstat (limited to 'v4l2-spec')
-rw-r--r--v4l2-spec/biblio.sgml65
-rw-r--r--v4l2-spec/common.sgml2
-rw-r--r--v4l2-spec/compat.sgml17
-rw-r--r--v4l2-spec/dev-radio.sgml14
-rw-r--r--v4l2-spec/dev-rds.sgml182
-rw-r--r--v4l2-spec/pixfmt.sgml5
-rw-r--r--v4l2-spec/v4l2.sgml8
-rw-r--r--v4l2-spec/vidioc-g-modulator.sgml5
-rw-r--r--v4l2-spec/vidioc-g-tuner.sgml17
-rw-r--r--v4l2-spec/vidioc-querycap.sgml16
10 files changed, 237 insertions, 94 deletions
diff --git a/v4l2-spec/biblio.sgml b/v4l2-spec/biblio.sgml
index b013ece1d..afc8a0dd2 100644
--- a/v4l2-spec/biblio.sgml
+++ b/v4l2-spec/biblio.sgml
@@ -158,54 +158,23 @@ Signal - NTSC for Studio Applications"</title>
1125-Line High-Definition Production"</title>
</biblioentry>
- <biblioentry id="v4l">
- <abbrev>V4L</abbrev>
- <authorgroup>
- <author>
- <firstname>Alan</firstname>
- <surname>Cox</surname>
- <affiliation>
- <orgname>Red Hat, Inc.</orgname>
- <address>
- <email>alan@redhat.com</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
- <title>Video4Linux API Specification</title>
- <abstract>
- <para>This file is part of the Linux kernel sources under
-<filename>Documentation/video4linux</filename>.</para>
- </abstract>
- </biblioentry>
-
- <biblioentry id="v4lprog">
- <abbrev>V4LPROG</abbrev>
- <authorgroup>
- <author>
- <firstname>Alan</firstname>
- <surname>Cox</surname>
- <affiliation>
- <orgname>Red Hat, Inc.</orgname>
- <address>
- <email>alan@redhat.com</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
- <title>Video4Linux Programming (a.k.a. The Video4Linux
-Book)</title>
- <abstract>
- <para>About V4L <emphasis>driver</emphasis> programming. This
-book is part of the Linux kernel DocBook documentation, for example at
-<ulink url="http://kernelnewbies.org/documents/">
-http://kernelnewbies.org/documents/</ulink>. SGML sources are included
-in the kernel sources.</para>
- </abstract>
- <copyright>
- <year>2000</year>
- <holder>Alan Cox</holder>
- </copyright>
+ <biblioentry id="en50067">
+ <abbrev>EN&nbsp;50067</abbrev>
+ <authorgroup>
+ <corpauthor>European Committee for Electrotechnical Standardization
+(<ulink url="http://www.cenelec.eu">http://www.cenelec.eu</ulink>)</corpauthor>
+ </authorgroup>
+ <title>Specification of the radio data system (RDS) for VHF/FM sound broadcasting
+in the frequency range from 87,5 to 108,0 MHz</title>
+ </biblioentry>
+
+ <biblioentry id="nrsc4">
+ <abbrev>NRSC-4</abbrev>
+ <authorgroup>
+ <corpauthor>National Radio Systems Committee
+(<ulink url="http://www.nrscstandards.org">http://www.nrscstandards.org</ulink>)</corpauthor>
+ </authorgroup>
+ <title>NTSC-4: United States RBDS Standard</title>
</biblioentry>
</bibliography>
diff --git a/v4l2-spec/common.sgml b/v4l2-spec/common.sgml
index ff595960b..75c7141e3 100644
--- a/v4l2-spec/common.sgml
+++ b/v4l2-spec/common.sgml
@@ -491,7 +491,7 @@ the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that
<constant>VIDIOC_S_MODULATOR</constant> does not switch the current
modulator, when there is more than one at all. The modulator is solely
determined by the current video output. Drivers must support both
-ioctls and set the <constant>V4L2_CAP_TUNER</constant> (sic) flag in
+ioctls and set the <constant>V4L2_CAP_MODULATOR</constant> flag in
the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the
device has one or more modulators.</para>
</section>
diff --git a/v4l2-spec/compat.sgml b/v4l2-spec/compat.sgml
index 94713023d..bcc372c18 100644
--- a/v4l2-spec/compat.sgml
+++ b/v4l2-spec/compat.sgml
@@ -1273,9 +1273,8 @@ also the size of the structure changed, which is encoded in the ioctl
request code, thus older V4L2 devices will respond with an &EINVAL; to
the new &VIDIOC-QUERYCAP; ioctl.</para>
- <para>There are new fields to identify the driver, a new (as
-of yet unspecified) device function
-<constant>V4L2_CAP_RDS_CAPTURE</constant>, the
+ <para>There are new fields to identify the driver, a new RDS
+device function <constant>V4L2_CAP_RDS_CAPTURE</constant>, the
<constant>V4L2_CAP_AUDIO</constant> flag indicates if the device has
any audio connectors, another I/O capability
<constant>V4L2_CAP_ASYNCIO</constant> can be flagged. In response to
@@ -2294,6 +2293,18 @@ was renamed to <structname id=v4l2-chip-ident-old>v4l2_chip_ident_old</structnam
</listitem>
</orderedlist>
</section>
+ <section>
+ <title>V4L2 in Linux 2.6.32</title>
+ <orderedlist>
+ <listitem>
+ <para>Finalized the RDS capture API. See <xref linkend="rds"> for
+more information.</para>
+ </listitem>
+ <listitem>
+ <para>Added new capabilities for modulators and RDS encoders.</para>
+ </listitem>
+ </orderedlist>
+ </section>
</section>
<section id="other">
diff --git a/v4l2-spec/dev-radio.sgml b/v4l2-spec/dev-radio.sgml
index ae8367219..4d521d2a8 100644
--- a/v4l2-spec/dev-radio.sgml
+++ b/v4l2-spec/dev-radio.sgml
@@ -1,7 +1,7 @@
<title>Radio Interface</title>
<para>This interface is intended for AM and FM (analog) radio
-receivers.</para>
+receivers and transmitters.</para>
<para>Conventionally V4L2 radio devices are accessed through
character device special files named <filename>/dev/radio</filename>
@@ -14,7 +14,8 @@ numbers 64 to 127.</para>
<para>Devices supporting the radio interface set the
<constant>V4L2_CAP_RADIO</constant> and
-<constant>V4L2_CAP_TUNER</constant> flag in the
+<constant>V4L2_CAP_TUNER</constant> or
+<constant>V4L2_CAP_MODULATOR</constant> flag in the
<structfield>capabilities</structfield> field of &v4l2-capability;
returned by the &VIDIOC-QUERYCAP; ioctl. Other combinations of
capability flags are reserved for future extensions.</para>
@@ -25,7 +26,7 @@ capability flags are reserved for future extensions.</para>
<para>Radio devices can support <link
linkend="control">controls</link>, and must support the <link
-linkend="tuner">tuner</link> ioctls.</para>
+linkend="tuner">tuner or modulator</link> ioctls.</para>
<para>They do not support the video input or output, audio input
or output, video standard, cropping and scaling, compression and
@@ -38,11 +39,12 @@ methods are reserved for future extensions.</para>
<para>Radio devices may have a couple audio controls (as discussed
in <xref linkend="control">) such as a volume control, possibly custom
-controls. Further all radio devices have one tuner (these are
+controls. Further all radio devices have one tuner or modulator (these are
discussed in <xref linkend="tuner">) with index number zero to select
the radio frequency and to determine if a monaural or FM stereo
-program is received. Drivers switch automatically between AM and FM
-depending on the selected frequency. The &VIDIOC-G-TUNER; ioctl
+program is received/emitted. Drivers switch automatically between AM and FM
+depending on the selected frequency. The &VIDIOC-G-TUNER; or
+&VIDIOC-G-MODULATOR; ioctl
reports the supported frequency range.</para>
</section>
diff --git a/v4l2-spec/dev-rds.sgml b/v4l2-spec/dev-rds.sgml
index 07bfd4c65..9d59d0cb0 100644
--- a/v4l2-spec/dev-rds.sgml
+++ b/v4l2-spec/dev-rds.sgml
@@ -2,38 +2,162 @@
<para>The Radio Data System transmits supplementary
information in binary format, for example the station name or travel
-information, on a inaudible audio subcarrier of a radio program. This
-interface aims at devices capable of receiving and decoding RDS
+information, on an inaudible audio subcarrier of a radio program. This
+interface is aimed at devices capable of receiving and decoding RDS
information.</para>
- <para>The V4L API defines its RDS API as follows.</para>
-
- <para>From radio devices supporting it, RDS data can be read
-with the &func-read; function. The data is packed in groups of three,
-as follows:<orderedlist>
- <listitem>
- <para>First Octet Least Significant Byte of RDS Block</para>
- </listitem>
- <listitem>
- <para>Second Octet Most Significant Byte of RDS Block</para>
- </listitem>
- <listitem>
- <para>Third Octet Bit 7: Error bit. Indicates that an
-uncorrectable error occurred during reception of this block. Bit 6:
-Corrected bit. Indicates that an error was corrected for this data
-block. Bits 5-3: Received Offset. Indicates the offset received by the
-sync system. Bits 2-0: Offset Name. Indicates the offset applied to
-this data.</para>
- </listitem>
- </orderedlist></para>
-
- <para>It was argued <!-- video4linux-list@redhat.com
-on 12 Nov 2002, subject "RDS/RBDS" --> the RDS API should be
-extended before integration into V4L2, no new API has been devised yet.
-Please write to the linux-media mailing list for discussion: &v4l-ml;.
-Meanwhile no V4L2 driver should set the
-<constant>V4L2_CAP_RDS_CAPTURE</constant> capability flag.</para>
+ <para>For more information see the core RDS standard <xref linkend="en50067">
+and the RBDS standard <xref linkend="nrsc4">.</para>
+ <para>Note that the RBDS standard as is used in the USA is almost identical
+to the RDS standard. Any RDS decoder can also handle RBDS. Only some of the fields
+have slightly different meanings. See the RBDS standard for more information.</para>
+
+ <para>The RBDS standard also specifies support for MMBS (Modified Mobile Search).
+This is a proprietary format which seems to be discontinued. The RDS interface does not
+support this format. Should support for MMBS (or the so-called 'E blocks' in general)
+be needed, then please contact the linux-media mailing list: &v4l-ml;.</para>
+
+ <section>
+ <title>Querying Capabilities</title>
+
+ <para>Devices supporting the RDS capturing API
+set the <constant>V4L2_CAP_RDS_CAPTURE</constant> flag in
+the <structfield>capabilities</structfield> field of &v4l2-capability;
+returned by the &VIDIOC-QUERYCAP; ioctl.
+Any tuner that supports RDS will set the
+<constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield>
+field of &v4l2-tuner;.
+Whether an RDS signal is present can be detected by looking at
+the <structfield>rxsubchans</structfield> field of &v4l2-tuner;: the
+<constant>V4L2_TUNER_SUB_RDS</constant> will be set if RDS data was detected.</para>
+
+ <para>Devices supporting the RDS output API
+set the <constant>V4L2_CAP_RDS_OUTPUT</constant> flag in
+the <structfield>capabilities</structfield> field of &v4l2-capability;
+returned by the &VIDIOC-QUERYCAP; ioctl.
+Any modulator that supports RDS will set the
+<constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield>
+field of &v4l2-modulator;.
+In order to enable the RDS transmission one must set the <constant>V4L2_TUNER_SUB_RDS</constant>
+bit in the <structfield>txsubchans</structfield> field of &v4l2-modulator;.</para>
+
+ </section>
+
+ <section>
+ <title>Reading RDS data</title>
+
+ <para>RDS data can be read from the radio device
+with the &func-read; function. The data is packed in groups of three bytes,
+as follows:</para>
+ <table frame="none" pgwide="1" id="v4l2-rds-data">
+ <title>struct
+<structname>v4l2_rds_data</structname></title>
+ <tgroup cols="3">
+ <colspec colname="c1" colwidth="1*">
+ <colspec colname="c2" colwidth="1*">
+ <colspec colname="c3" colwidth="5*">
+ <tbody valign="top">
+ <row>
+ <entry>__u8</entry>
+ <entry><structfield>lsb</structfield></entry>
+ <entry>Least Significant Byte of RDS Block</entry>
+ </row>
+ <row>
+ <entry>__u8</entry>
+ <entry><structfield>msb</structfield></entry>
+ <entry>Most Significant Byte of RDS Block</entry>
+ </row>
+ <row>
+ <entry>__u8</entry>
+ <entry><structfield>block</structfield></entry>
+ <entry>Block description</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table frame="none" pgwide="1" id="v4l2-rds-block">
+ <title>Block description</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colwidth="1*">
+ <colspec colname="c2" colwidth="5*">
+ <tbody valign="top">
+ <row>
+ <entry>Bits 0-2</entry>
+ <entry>Block (aka offset) of the received data.</entry>
+ </row>
+ <row>
+ <entry>Bits 3-5</entry>
+ <entry>Deprecated. Currently identical to bits 0-2. Do not use these bits.</entry>
+ </row>
+ <row>
+ <entry>Bit 6</entry>
+ <entry>Corrected bit. Indicates that an error was corrected for this data block.</entry>
+ </row>
+ <row>
+ <entry>Bit 7</entry>
+ <entry>Error bit. Indicates that an uncorrectable error occurred during reception of this block.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table frame="none" pgwide="1" id="v4l2-rds-block-codes">
+ <title>Block defines</title>
+ <tgroup cols="3">
+ <colspec colname="c1" colwidth="1*">
+ <colspec colname="c2" colwidth="1*">
+ <colspec colname="c3" colwidth="5*">
+ <tbody valign="top">
+ <row>
+ <entry>V4L2_RDS_BLOCK_MSK</entry>
+ <entry>7</entry>
+ <entry>Mask for bits 0-2 to get the block ID.</entry>
+ </row>
+ <row>
+ <entry>V4L2_RDS_BLOCK_A</entry>
+ <entry>0</entry>
+ <entry>Block A.</entry>
+ </row>
+ <row>
+ <entry>V4L2_RDS_BLOCK_B</entry>
+ <entry>1</entry>
+ <entry>Block B.</entry>
+ </row>
+ <row>
+ <entry>V4L2_RDS_BLOCK_C</entry>
+ <entry>2</entry>
+ <entry>Block C.</entry>
+ </row>
+ <row>
+ <entry>V4L2_RDS_BLOCK_D</entry>
+ <entry>3</entry>
+ <entry>Block D.</entry>
+ </row>
+ <row>
+ <entry>V4L2_RDS_BLOCK_C_ALT</entry>
+ <entry>4</entry>
+ <entry>Block C'.</entry>
+ </row>
+ <row>
+ <entry>V4L2_RDS_BLOCK_INVALID</entry>
+ <entry>7</entry>
+ <entry>An invalid block.</entry>
+ </row>
+ <row>
+ <entry>V4L2_RDS_BLOCK_CORRECTED</entry>
+ <entry>0x40</entry>
+ <entry>A bit error was detected but corrected.</entry>
+ </row>
+ <row>
+ <entry>V4L2_RDS_BLOCK_ERROR</entry>
+ <entry>0x80</entry>
+ <entry>An incorrectable error occurred.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
<!--
Local Variables:
diff --git a/v4l2-spec/pixfmt.sgml b/v4l2-spec/pixfmt.sgml
index 1be70eea0..9e6bebeb4 100644
--- a/v4l2-spec/pixfmt.sgml
+++ b/v4l2-spec/pixfmt.sgml
@@ -765,6 +765,11 @@ kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm
<entry>'S910'</entry>
<entry>Compressed format of the SN9C102 driver.</entry>
</row>
+ <row id="V4L2-PIX-FMT-SN9C20X-I420">
+ <entry><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></entry>
+ <entry>'S920'</entry>
+ <entry>YUV 4:2:0 format of the gspca sn9c20x driver.</entry>
+ </row>
<row id="V4L2-PIX-FMT-WNVA">
<entry><constant>V4L2_PIX_FMT_WNVA</constant></entry>
<entry>'WNVA'</entry>
diff --git a/v4l2-spec/v4l2.sgml b/v4l2-spec/v4l2.sgml
index 470793d29..bae7eb441 100644
--- a/v4l2-spec/v4l2.sgml
+++ b/v4l2-spec/v4l2.sgml
@@ -131,6 +131,14 @@ structs, ioctls) must be noted in more detail in the history chapter
applications. -->
<revision>
+ <revnumber>0.26</revnumber>
+ <date>2009-06-15</date>
+ <authorinitials>hv</authorinitials>
+ <revremark>Finalized the RDS capture API. Added modulator and RDS encoder
+capabilities.</revremark>
+ </revision>
+
+ <revision>
<revnumber>0.25</revnumber>
<date>2009-01-18</date>
<authorinitials>hv</authorinitials>
diff --git a/v4l2-spec/vidioc-g-modulator.sgml b/v4l2-spec/vidioc-g-modulator.sgml
index a3ea5ef8a..945147f90 100644
--- a/v4l2-spec/vidioc-g-modulator.sgml
+++ b/v4l2-spec/vidioc-g-modulator.sgml
@@ -212,6 +212,11 @@ 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>
diff --git a/v4l2-spec/vidioc-g-tuner.sgml b/v4l2-spec/vidioc-g-tuner.sgml
index d5d379838..eb0b89e9a 100644
--- a/v4l2-spec/vidioc-g-tuner.sgml
+++ b/v4l2-spec/vidioc-g-tuner.sgml
@@ -120,9 +120,9 @@ field is not quite clear.--></para></entry>
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> and
-<constant>V4L2_TUNER_CAP_STEREO</constant> flags can be
-set.</para></entry>
+<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>
@@ -312,6 +312,12 @@ carrier for a monaural secondary language. Only
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>
@@ -353,6 +359,11 @@ bilingual audio signal (or a second audio program).</entry>
<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>
diff --git a/v4l2-spec/vidioc-querycap.sgml b/v4l2-spec/vidioc-querycap.sgml
index 2715289d8..fa12ae738 100644
--- a/v4l2-spec/vidioc-querycap.sgml
+++ b/v4l2-spec/vidioc-querycap.sgml
@@ -184,7 +184,7 @@ data.</entry>
<row>
<entry><constant>V4L2_CAP_RDS_CAPTURE</constant></entry>
<entry>0x00000100</entry>
- <entry>[to be defined]</entry>
+ <entry>The device supports the <link linkend="rds">RDS</link> interface.</entry>
</row>
<row>
<entry><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant></entry>
@@ -208,9 +208,9 @@ hardware frequency seeking.</entry>
<row>
<entry><constant>V4L2_CAP_TUNER</constant></entry>
<entry>0x00010000</entry>
- <entry>The device has some sort of tuner or modulator to
-receive or emit RF-modulated video signals. For more information about
-tuner and modulator programming see
+ <entry>The device has some sort of tuner to
+receive RF-modulated video signals. For more information about
+tuner programming see
<xref linkend="tuner">.</entry>
</row>
<row>
@@ -228,6 +228,14 @@ interface. For more information on audio inputs and outputs see <xref
<entry>This is a radio receiver.</entry>
</row>
<row>
+ <entry><constant>V4L2_CAP_MODULATOR</constant></entry>
+ <entry>0x00080000</entry>
+ <entry>The device has some sort of modulator to
+emit RF-modulated video/audio signals. For more information about
+modulator programming see
+<xref linkend="tuner">.</entry>
+ </row>
+ <row>
<entry><constant>V4L2_CAP_READWRITE</constant></entry>
<entry>0x01000000</entry>
<entry>The device supports the <link
generated by cgit v1.2.3 (git 2.25.1) at 2025-05-18 18:15:39 +0000