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

   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>
  10 SDR is an abbreviation of Software Defined Radio, the radio device
  11 which uses application software for modulation or demodulation. This interface
  12 is intended for controlling and data streaming of such devices.
  13   </para>
  14
  15   <para>
  16 SDR devices are accessed through character device special files named
  17 <filename>/dev/swradio0</filename> to <filename>/dev/swradio255</filename>
  18 with major number 81 and dynamically allocated minor numbers 0 to 255.
  19   </para>
  20
  21   <section>
  22     <title>Querying Capabilities</title>
  23
  24     <para>
  25 Devices 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;
  29 returned by the &VIDIOC-QUERYCAP; ioctl. That flag means the device has an
  30 Analog to Digital Converter (ADC), which is a mandatory element for the SDR receiver.
  31     </para>
  32     <para>
  33 Devices 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;
  37 returned by the &VIDIOC-QUERYCAP; ioctl. That flag means the device has an
  38 Digital to Analog Converter (DAC), which is a mandatory element for the SDR transmitter.
  39     </para>
  40     <para>
  41 At least one of the read/write, streaming or asynchronous I/O methods must
  42 be supported.
  43     </para>
  44   </section>
  45
  46   <section>
  47     <title>Supplemental Functions</title>
  48
  49     <para>
  50 SDR devices can support <link linkend="control">controls</link>, and must
  51 support the <link linkend="tuner">tuner</link> ioctls. Tuner ioctls are used
  52 for setting the ADC/DAC sampling rate (sampling frequency) and the possible
  53 radio frequency (RF).
  54     </para>
  55
  56     <para>
  57 The <constant>V4L2_TUNER_SDR</constant> tuner type is used for setting SDR
  58 device ADC/DAC frequency, and the <constant>V4L2_TUNER_RF</constant>
  59 tuner type is used for setting radio frequency.
  60 The tuner index of the RF tuner (if any) must always follow the SDR tuner index.
  61 Normally the SDR tuner is #0 and the RF tuner is #1.
  62     </para>
  63
  64     <para>
  65 The &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>
  73 The SDR device uses the <link linkend="format">format</link> ioctls to
  74 select the capture and output format. Both the sampling resolution and the data
  75 streaming format are bound to that selectable format. In addition to the basic
  76 <link linkend="format">format</link> ioctls, the &VIDIOC-ENUM-FMT; ioctl
  77 must be supported as well.
  78     </para>
  79
  80     <para>
  81 To 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>
  86 union as needed per the desired operation.
  87 Currently there is two fields, <structfield>pixelformat</structfield> and
  88 <structfield>buffersize</structfield>, of struct &v4l2-sdr-format; which are
  89 used. Content of the <structfield>pixelformat</structfield> is V4L2 FourCC
  90 code of the data format. The <structfield>buffersize</structfield> field is
  91 maximum buffer size in bytes required for data transfer, set by the driver in
  92 order 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>
 104 The data format or type of compression, set by the application. This is a
 105 little endian <link linkend="v4l2-fourcc">four character code</link>.
 106 V4L2 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>
 113 Maximum 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.
 120 Drivers and applications must set it to zero.</entry>
 121           </row>
 122         </tbody>
 123       </tgroup>
 124     </table>
 125
 126     <para>
 127 An SDR device may support <link linkend="rw">read/write</link>
 128 and/or streaming (<link linkend="mmap">memory mapping</link>
 129 or <link linkend="userp">user pointer</link>) I/O.
 130     </para>
 131
 132   </section>