Documentation/media/uapi/v4l/dev-sdr.rst

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _sdr:
  11
  12 **************************************
  13 Software Defined Radio Interface (SDR)
  14 **************************************
  15
  16 SDR is an abbreviation of Software Defined Radio, the radio device which
  17 uses application software for modulation or demodulation. This interface
  18 is intended for controlling and data streaming of such devices.
  19
  20 SDR devices are accessed through character device special files named
  21 ``/dev/swradio0`` to ``/dev/swradio255`` with major number 81 and
  22 dynamically allocated minor numbers 0 to 255.
  23
  24
  25 Querying Capabilities
  26 =====================
  27
  28 Devices supporting the SDR receiver interface set the
  29 ``V4L2_CAP_SDR_CAPTURE`` and ``V4L2_CAP_TUNER`` flag in the
  30 ``capabilities`` field of struct
  31 :c:type:`v4l2_capability` returned by the
  32 :ref:`VIDIOC_QUERYCAP` ioctl. That flag means the
  33 device has an Analog to Digital Converter (ADC), which is a mandatory
  34 element for the SDR receiver.
  35
  36 Devices supporting the SDR transmitter interface set the
  37 ``V4L2_CAP_SDR_OUTPUT`` and ``V4L2_CAP_MODULATOR`` flag in the
  38 ``capabilities`` field of struct
  39 :c:type:`v4l2_capability` returned by the
  40 :ref:`VIDIOC_QUERYCAP` ioctl. That flag means the
  41 device has an Digital to Analog Converter (DAC), which is a mandatory
  42 element for the SDR transmitter.
  43
  44 At least one of the read/write, streaming or asynchronous I/O methods
  45 must be supported.
  46
  47
  48 Supplemental Functions
  49 ======================
  50
  51 SDR devices can support :ref:`controls <control>`, and must support
  52 the :ref:`tuner` ioctls. Tuner ioctls are used for setting the
  53 ADC/DAC sampling rate (sampling frequency) and the possible radio
  54 frequency (RF).
  55
  56 The ``V4L2_TUNER_SDR`` tuner type is used for setting SDR device ADC/DAC
  57 frequency, and the ``V4L2_TUNER_RF`` tuner type is used for setting
  58 radio frequency. The tuner index of the RF tuner (if any) must always
  59 follow the SDR tuner index. Normally the SDR tuner is #0 and the RF
  60 tuner is #1.
  61
  62 The :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl is
  63 not supported.
  64
  65
  66 Data Format Negotiation
  67 =======================
  68
  69 The SDR device uses the :ref:`format` ioctls to select the
  70 capture and output format. Both the sampling resolution and the data
  71 streaming format are bound to that selectable format. In addition to the
  72 basic :ref:`format` ioctls, the
  73 :ref:`VIDIOC_ENUM_FMT` ioctl must be supported as
  74 well.
  75
  76 To use the :ref:`format` ioctls applications set the ``type``
  77 field of a struct :c:type:`v4l2_format` to
  78 ``V4L2_BUF_TYPE_SDR_CAPTURE`` or ``V4L2_BUF_TYPE_SDR_OUTPUT`` and use
  79 the struct :c:type:`v4l2_sdr_format` ``sdr`` member
  80 of the ``fmt`` union as needed per the desired operation. Currently
  81 there is two fields, ``pixelformat`` and ``buffersize``, of struct
  82 struct :c:type:`v4l2_sdr_format` which are used.
  83 Content of the ``pixelformat`` is V4L2 FourCC code of the data format.
  84 The ``buffersize`` field is maximum buffer size in bytes required for
  85 data transfer, set by the driver in order to inform application.
  86
  87
  88 .. c:type:: v4l2_sdr_format
  89
  90 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  91
  92 .. flat-table:: struct v4l2_sdr_format
  93     :header-rows:  0
  94     :stub-columns: 0
  95     :widths:       1 1 2
  96
  97     * - __u32
  98       - ``pixelformat``
  99       - The data format or type of compression, set by the application.
 100         This is a little endian
 101         :ref:`four character code <v4l2-fourcc>`. V4L2 defines SDR
 102         formats in :ref:`sdr-formats`.
 103     * - __u32
 104       - ``buffersize``
 105       - Maximum size in bytes required for data. Value is set by the
 106         driver.
 107     * - __u8
 108       - ``reserved[24]``
 109       - This array is reserved for future extensions. Drivers and
 110         applications must set it to zero.
 111
 112
 113 An SDR device may support :ref:`read/write <rw>` and/or streaming
 114 (:ref:`memory mapping <mmap>` or :ref:`user pointer <userp>`) I/O.