Document V4L2 SDR interface.
Cc: Hans Verkuil <hverkuil@xxxxxxxxx>
Signed-off-by: Antti Palosaari <crope@xxxxxx>
---
Documentation/DocBook/media/v4l/compat.xml | 10 +++
Documentation/DocBook/media/v4l/dev-sdr.xml | 99 ++++++++++++++++++++++++
Documentation/DocBook/media/v4l/io.xml | 6 ++
Documentation/DocBook/media/v4l/v4l2.xml | 1 +
Documentation/DocBook/media/v4l/vidioc-g-fmt.xml | 6 ++
5 files changed, 122 insertions(+)
create mode 100644 Documentation/DocBook/media/v4l/dev-sdr.xml
diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml
index 0c7195e..85fb864 100644
--- a/Documentation/DocBook/media/v4l/compat.xml
+++ b/Documentation/DocBook/media/v4l/compat.xml
@@ -2523,6 +2523,16 @@ that used it. It was originally scheduled for removal in 2.6.35.
</orderedlist>
</section>
+ <section>
+ <title>V4L2 in Linux 3.14</title>
+ <orderedlist>
+ <listitem>
+ <para>Added Software Defined Radio (SDR) Interface.
+ </para>
+ </listitem>
+ </orderedlist>
+ </section>
+
<section id="other">
<title>Relation of V4L2 to other Linux multimedia APIs</title>
diff --git a/Documentation/DocBook/media/v4l/dev-sdr.xml b/Documentation/DocBook/media/v4l/dev-sdr.xml
new file mode 100644
index 0000000..3caf44d
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/dev-sdr.xml
@@ -0,0 +1,99 @@
+ <title>Software Defined Radio Interface (SDR)</title>
+
+ <para>
+SDR is an abbreviation of Software Defined Radio, the radio device
+which uses application software for modulation or demodulation. That interface
+is intended for controlling and data streaming of such devices.
+ </para>
+
+ <para>
+SDR devices are accessed through character device special files named
+<filename>/dev/swradio0</filename> to <filename>/dev/swradio255</filename>
+with major number 81 and dynamically allocated minor numbers 0 to 255.
+ </para>
+
+ <section>
+ <title>Querying Capabilities</title>
+
+ <para>
+Devices supporting the SDR receiver interface set the
+<constant>V4L2_CAP_SDR_CAPTURE</constant> and
+<constant>V4L2_CAP_TUNER</constant> flag in the
+<structfield>capabilities</structfield> field of &v4l2-capability;
+returned by the &VIDIOC-QUERYCAP; ioctl. That flag means device has
+Analog to Digital Converter (ADC), which is mandatory element for SDR receiver.
+At least one of the read/write, streaming or asynchronous I/O methods must
+be supported.
+ </para>
+ </section>
+
+ <section>
+ <title>Supplemental Functions</title>
+
+ <para>
+SDR devices can support <link linkend="control">controls</link>, and must
+support the <link linkend="tuner">tuner</link> ioctls. Tuner ioctls are used
+for setting ADC sampling rate (sampling frequency) and possible RF tuner
+frequency.
+ </para>
+
+ <para>
+<constant>V4L2_TUNER_ADC</constant> is used as a tuner type when ADC is in
+question and <constant>V4L2_TUNER_RF</constant> is used as a tuner type when
+RF tuner is in question. Possible RF tuner index number is always next one
+from the ADC index number. Normally ADC tuner is #0 and RF tuner is #1.
+ </para>
+
+ <para>
+<constant>VIDIOC_S_HW_FREQ_SEEK</constant> ioctl is not supported.
+ </para>
+ </section>
+
+ <section>
+ <title>Data Format Negotiation</title>
+
+ <para>
+SDR capture device uses <link linkend="format">format</link> ioctls to select
+capture format. Both sampling resolution and data streaming format are bind
+to that selectable format. In addition to basic
+<link linkend="format">format</link> ioctls, the
+<constant>VIDIOC_ENUM_FMT</constant> ioctl must be supported too.
+ </para>
+
+ <para>
+To use <link linkend="format">format</link> ioctls applications set the
+<structfield>type</structfield> field of a &v4l2-format; to
+<constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant> and use the &v4l2-format-sdr;
+<structfield>sdr</structfield> member of the <structfield>fmt</structfield>
+union as needed per desired operation.
+Currently there is only <structfield>pixelformat</structfield> field of
+&v4l2-format-sdr; used. Content of that field is data format V4L2 fourcc code.
+ </para>
+
+ <table pgwide="1" frame="none" id="v4l2-format-sdr">
+ <title>struct <structname>v4l2_format_sdr</structname></title>
+ <tgroup cols="3">
+ &cs-str;
+ <tbody valign="top">
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>pixelformat</structfield></entry>
+ <entry>little endian four character code (fourcc)</entry>
+ </row>
+ <row>
+ <entry>__u8</entry>
+ <entry><structfield>reserved[28]</structfield></entry>
+ <entry>This array is reserved for future extensions.
+Drivers and applications must set it to zero.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+A SDR device may support <link linkend="rw">read/write</link>
+and/or streaming (<link linkend="mmap">memory mapping</link>
+or <link linkend="userp">user pointer</link>) I/O.
+ </para>
+
+ </section>
diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml
index 2c4c068..1fb11e8 100644
--- a/Documentation/DocBook/media/v4l/io.xml
+++ b/Documentation/DocBook/media/v4l/io.xml
@@ -1005,6 +1005,12 @@ should set this to 0.</entry>
<entry>Buffer for video output overlay (OSD), see <xref
linkend="osd" />.</entry>
</row>
+ <row>
+ <entry><constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant></entry>
+ <entry>11</entry>
+ <entry>Buffer for Software Defined Radio (SDR), see <xref
+ linkend="sdr" />.</entry>
+ </row>
</tbody>
</tgroup>
</table>
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml
index 8469fe1..a27fcae 100644
--- a/Documentation/DocBook/media/v4l/v4l2.xml
+++ b/Documentation/DocBook/media/v4l/v4l2.xml
@@ -529,6 +529,7 @@ and discussions on the V4L mailing list.</revremark>
<section id="ttx"> &sub-dev-teletext; </section>
<section id="radio"> &sub-dev-radio; </section>
<section id="rds"> &sub-dev-rds; </section>
+ <section id="sdr"> &sub-dev-sdr; </section>
<section id="event"> &sub-dev-event; </section>
<section id="subdev"> &sub-dev-subdev; </section>
</chapter>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml
index ee8f56e..60bf9b2 100644
--- a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml
@@ -172,6 +172,12 @@ capture and output devices.</entry>
</row>
<row>
<entry></entry>
+ <entry>&v4l2-format-sdr;</entry>
+ <entry><structfield>sdr</structfield></entry>
+ <entry>Definition of an SDR format.</entry>
+ </row>
+ <row>
+ <entry></entry>
<entry>__u8</entry>
<entry><structfield>raw_data</structfield>[200]</entry>
<entry>Place holder for future extensions.</entry>
--
1.8.4.2
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
