1  <title>Software Defined Radio Interface (SDR)</title>
2
3  <note>
4    <title>Experimental</title>
5    <para>This is an <link linkend="experimental"> experimental </link>
6    interface and may change in the future.</para>
7  </note>
8
9  <para>
10SDR is an abbreviation of Software Defined Radio, the radio device
11which uses application software for modulation or demodulation. This interface
12is intended for controlling and data streaming of such devices.
13  </para>
14
15  <para>
16SDR devices are accessed through character device special files named
17<filename>/dev/swradio0</filename> to <filename>/dev/swradio255</filename>
18with major number 81 and dynamically allocated minor numbers 0 to 255.
19  </para>
20
21  <section>
22    <title>Querying Capabilities</title>
23
24    <para>
25Devices supporting the SDR receiver interface set the
26<constant>V4L2_CAP_SDR_CAPTURE</constant> and
27<constant>V4L2_CAP_TUNER</constant> flag in the
28<structfield>capabilities</structfield> field of &v4l2-capability;
29returned by the &VIDIOC-QUERYCAP; ioctl. That flag means the device has an
30Analog to Digital Converter (ADC), which is a mandatory element for the SDR receiver.
31At least one of the read/write, streaming or asynchronous I/O methods must
32be supported.
33    </para>
34  </section>
35
36  <section>
37    <title>Supplemental Functions</title>
38
39    <para>
40SDR devices can support <link linkend="control">controls</link>, and must
41support the <link linkend="tuner">tuner</link> ioctls. Tuner ioctls are used
42for setting the ADC sampling rate (sampling frequency) and the possible RF tuner
43frequency.
44    </para>
45
46    <para>
47The <constant>V4L2_TUNER_ADC</constant> tuner type is used for ADC tuners, and
48the <constant>V4L2_TUNER_RF</constant> tuner type is used for RF tuners. The
49tuner index of the RF tuner (if any) must always follow the ADC tuner index.
50Normally the ADC tuner is #0 and the RF tuner is #1.
51    </para>
52
53    <para>
54The &VIDIOC-S-HW-FREQ-SEEK; ioctl is not supported.
55    </para>
56  </section>
57
58  <section>
59    <title>Data Format Negotiation</title>
60
61    <para>
62The SDR capture device uses the <link linkend="format">format</link> ioctls to
63select the capture format. Both the sampling resolution and the data streaming
64format are bound to that selectable format. In addition to the basic
65<link linkend="format">format</link> ioctls, the &VIDIOC-ENUM-FMT; ioctl
66must be supported as well.
67    </para>
68
69    <para>
70To use the <link linkend="format">format</link> ioctls applications set the
71<structfield>type</structfield> field of a &v4l2-format; to
72<constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant> and use the &v4l2-sdr-format;
73<structfield>sdr</structfield> member of the <structfield>fmt</structfield>
74union as needed per the desired operation.
75Currently there is two fields, <structfield>pixelformat</structfield> and
76<structfield>buffersize</structfield>, of struct &v4l2-sdr-format; which are
77used. Content of the <structfield>pixelformat</structfield> is V4L2 FourCC
78code of the data format. The <structfield>buffersize</structfield> field is
79maximum buffer size in bytes required for data transfer, set by the driver in
80order to inform application.
81    </para>
82
83    <table pgwide="1" frame="none" id="v4l2-sdr-format">
84      <title>struct <structname>v4l2_sdr_format</structname></title>
85      <tgroup cols="3">
86        &cs-str;
87        <tbody valign="top">
88          <row>
89            <entry>__u32</entry>
90            <entry><structfield>pixelformat</structfield></entry>
91            <entry>
92The data format or type of compression, set by the application. This is a
93little endian <link linkend="v4l2-fourcc">four character code</link>.
94V4L2 defines SDR formats in <xref linkend="sdr-formats" />.
95           </entry>
96          </row>
97          <row>
98            <entry>__u32</entry>
99            <entry><structfield>buffersize</structfield></entry>
100            <entry>
101Maximum size in bytes required for data. Value is set by the driver.
102           </entry>
103          </row>
104          <row>
105            <entry>__u8</entry>
106            <entry><structfield>reserved[24]</structfield></entry>
107            <entry>This array is reserved for future extensions.
108Drivers and applications must set it to zero.</entry>
109          </row>
110        </tbody>
111      </tgroup>
112    </table>
113
114    <para>
115An SDR device may support <link linkend="rw">read/write</link>
116and/or streaming (<link linkend="mmap">memory mapping</link>
117or <link linkend="userp">user pointer</link>) I/O.
118    </para>
119
120  </section>
121