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. 31 </para> 32 <para> 33Devices supporting the SDR transmitter interface set the 34<constant>V4L2_CAP_SDR_OUTPUT</constant> and 35<constant>V4L2_CAP_MODULATOR</constant> flag in the 36<structfield>capabilities</structfield> field of &v4l2-capability; 37returned by the &VIDIOC-QUERYCAP; ioctl. That flag means the device has an 38Digital to Analog Converter (DAC), which is a mandatory element for the SDR transmitter. 39 </para> 40 <para> 41At least one of the read/write, streaming or asynchronous I/O methods must 42be supported. 43 </para> 44 </section> 45 46 <section> 47 <title>Supplemental Functions</title> 48 49 <para> 50SDR devices can support <link linkend="control">controls</link>, and must 51support the <link linkend="tuner">tuner</link> ioctls. Tuner ioctls are used 52for setting the ADC/DAC sampling rate (sampling frequency) and the possible 53radio frequency (RF). 54 </para> 55 56 <para> 57The <constant>V4L2_TUNER_SDR</constant> tuner type is used for setting SDR 58device ADC/DAC frequency, and the <constant>V4L2_TUNER_RF</constant> 59tuner type is used for setting radio frequency. 60The tuner index of the RF tuner (if any) must always follow the SDR tuner index. 61Normally the SDR tuner is #0 and the RF tuner is #1. 62 </para> 63 64 <para> 65The &VIDIOC-S-HW-FREQ-SEEK; ioctl is not supported. 66 </para> 67 </section> 68 69 <section> 70 <title>Data Format Negotiation</title> 71 72 <para> 73The SDR device uses the <link linkend="format">format</link> ioctls to 74select the capture and output format. Both the sampling resolution and the data 75streaming format are bound to that selectable format. In addition to the basic 76<link linkend="format">format</link> ioctls, the &VIDIOC-ENUM-FMT; ioctl 77must be supported as well. 78 </para> 79 80 <para> 81To use the <link linkend="format">format</link> ioctls applications set the 82<structfield>type</structfield> field of a &v4l2-format; to 83<constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant> or 84<constant>V4L2_BUF_TYPE_SDR_OUTPUT</constant> and use the &v4l2-sdr-format; 85<structfield>sdr</structfield> member of the <structfield>fmt</structfield> 86union as needed per the desired operation. 87Currently there is two fields, <structfield>pixelformat</structfield> and 88<structfield>buffersize</structfield>, of struct &v4l2-sdr-format; which are 89used. Content of the <structfield>pixelformat</structfield> is V4L2 FourCC 90code of the data format. The <structfield>buffersize</structfield> field is 91maximum buffer size in bytes required for data transfer, set by the driver in 92order to inform application. 93 </para> 94 95 <table pgwide="1" frame="none" id="v4l2-sdr-format"> 96 <title>struct <structname>v4l2_sdr_format</structname></title> 97 <tgroup cols="3"> 98 &cs-str; 99 <tbody valign="top"> 100 <row> 101 <entry>__u32</entry> 102 <entry><structfield>pixelformat</structfield></entry> 103 <entry> 104The data format or type of compression, set by the application. This is a 105little endian <link linkend="v4l2-fourcc">four character code</link>. 106V4L2 defines SDR formats in <xref linkend="sdr-formats" />. 107 </entry> 108 </row> 109 <row> 110 <entry>__u32</entry> 111 <entry><structfield>buffersize</structfield></entry> 112 <entry> 113Maximum size in bytes required for data. Value is set by the driver. 114 </entry> 115 </row> 116 <row> 117 <entry>__u8</entry> 118 <entry><structfield>reserved[24]</structfield></entry> 119 <entry>This array is reserved for future extensions. 120Drivers and applications must set it to zero.</entry> 121 </row> 122 </tbody> 123 </tgroup> 124 </table> 125 126 <para> 127An SDR device may support <link linkend="rw">read/write</link> 128and/or streaming (<link linkend="mmap">memory mapping</link> 129or <link linkend="userp">user pointer</link>) I/O. 130 </para> 131 132 </section> 133