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

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