dev-sdr.rst

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