Commit 559f40fe authored by Antti Palosaari's avatar Antti Palosaari Committed by Mauro Carvalho Chehab
Browse files

[media] DocBook: Software Defined Radio Interface 



Document V4L2 SDR interface.

Cc: Hans Verkuil <hverkuil@xs4all.nl>
Signed-off-by: default avatarAntti Palosaari <crope@iki.fi>
Acked-by: default avatarHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: default avatarMauro Carvalho Chehab <m.chehab@samsung.com>
parent 70b5efb8

Documentation/DocBook/media/v4l/compat.xml

+10 −0
Original line number Diff line number Diff line
@@ -2535,6 +2535,16 @@ fields changed from _s32 to _u32. 
      </orderedlist>

    </section>



    <section>

      <title>V4L2 in Linux 3.15</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>

Documentation/DocBook/media/v4l/dev-sdr.xml

0 → 100644
+104 −0
Original line number Diff line number Diff line 
  <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. This 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 the device has an

Analog to Digital Converter (ADC), which is a mandatory element for the 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 the ADC sampling rate (sampling frequency) and the possible RF tuner

frequency.

    </para>



    <para>

The <constant>V4L2_TUNER_ADC</constant> tuner type is used for ADC tuners, and

the <constant>V4L2_TUNER_RF</constant> tuner type is used for RF tuners. The

tuner index of the RF tuner (if any) must always follow the ADC tuner index.

Normally the ADC tuner is #0 and the RF tuner is #1.

    </para>



    <para>

The &VIDIOC-S-HW-FREQ-SEEK; ioctl is not supported.

    </para>

  </section>



  <section>

    <title>Data Format Negotiation</title>



    <para>

The SDR capture device uses the <link linkend="format">format</link> ioctls to

select the capture format. Both the sampling resolution and the data streaming

format are bound to that selectable format. In addition to the basic

<link linkend="format">format</link> ioctls, the &VIDIOC-ENUM-FMT; ioctl

must be supported as well.

    </para>



    <para>

To use the <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 the desired operation.

Currently only the <structfield>pixelformat</structfield> field of

&v4l2-format-sdr; is used. The content of that field is the V4L2 fourcc code

of the data format.

    </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>

The data format or type of compression, set by the application. This is a

little endian <link linkend="v4l2-fourcc">four character code</link>.

V4L2 defines SDR formats in <xref linkend="sdr-formats" />.

           </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>

An 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>

Documentation/DocBook/media/v4l/io.xml

+6 −0
Original line number Diff line number Diff line
@@ -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>

Documentation/DocBook/media/v4l/pixfmt.xml

+8 −0
Original line number Diff line number Diff line
@@ -811,6 +811,14 @@ extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see 
    </table>

  </section>



  <section id="sdr-formats">

    <title>SDR Formats</title>



    <para>These formats are used for <link linkend="sdr">SDR Capture</link>

interface only.</para>



  </section>



  <section id="pixfmt-reserved">

    <title>Reserved Format Identifiers</title>

Documentation/DocBook/media/v4l/v4l2.xml

+1 −0
Original line number Diff line number Diff line
@@ -548,6 +548,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>