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 At least one of the read/write, streaming or asynchronous I/O methods must
  32 be supported.
  33     </para>
  34   </section>
  35
  36   <section>
  37     <title>Supplemental Functions</title>
  38
  39     <para>
  40 SDR devices can support <link linkend="control">controls</link>, and must
  41 support the <link linkend="tuner">tuner</link> ioctls. Tuner ioctls are used
  42 for setting the ADC sampling rate (sampling frequency) and the possible RF tuner
  43 frequency.
  44     </para>
  45
  46     <para>
  47 The <constant>V4L2_TUNER_ADC</constant> tuner type is used for ADC tuners, and
  48 the <constant>V4L2_TUNER_RF</constant> tuner type is used for RF tuners. The
  49 tuner index of the RF tuner (if any) must always follow the ADC tuner index.
  50 Normally the ADC tuner is #0 and the RF tuner is #1.
  51     </para>
  52
  53     <para>
  54 The &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>
  62 The SDR capture device uses the <link linkend="format">format</link> ioctls to
  63 select the capture format. Both the sampling resolution and the data streaming
  64 format are bound to that selectable format. In addition to the basic
  65 <link linkend="format">format</link> ioctls, the &VIDIOC-ENUM-FMT; ioctl
  66 must be supported as well.
  67     </para>
  68
  69     <para>
  70 To 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>
  74 union as needed per the desired operation.
  75 Currently only the <structfield>pixelformat</structfield> field of
  76 &v4l2-sdr-format; is used. The content of that field is the V4L2 fourcc code
  77 of the data format.
  78     </para>
  79
  80     <table pgwide="1" frame="none" id="v4l2-sdr-format">
  81       <title>struct <structname>v4l2_sdr_format</structname></title>
  82       <tgroup cols="3">
  83         &cs-str;
  84         <tbody valign="top">
  85           <row>
  86             <entry>__u32</entry>
  87             <entry><structfield>pixelformat</structfield></entry>
  88             <entry>
  89 The data format or type of compression, set by the application. This is a
  90 little endian <link linkend="v4l2-fourcc">four character code</link>.
  91 V4L2 defines SDR formats in <xref linkend="sdr-formats" />.
  92            </entry>
  93           </row>
  94           <row>
  95             <entry>__u8</entry>
  96             <entry><structfield>reserved[28]</structfield></entry>
  97             <entry>This array is reserved for future extensions.
  98 Drivers and applications must set it to zero.</entry>
  99           </row>
 100         </tbody>
 101       </tgroup>
 102     </table>
 103
 104     <para>
 105 An SDR device may support <link linkend="rw">read/write</link>
 106 and/or streaming (<link linkend="mmap">memory mapping</link>
 107 or <link linkend="userp">user pointer</link>) I/O.
 108     </para>
 109
 110   </section>