1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 3.. _sdr: 4 5************************************** 6Software Defined Radio Interface (SDR) 7************************************** 8 9SDR is an abbreviation of Software Defined Radio, the radio device which 10uses application software for modulation or demodulation. This interface 11is intended for controlling and data streaming of such devices. 12 13SDR devices are accessed through character device special files named 14``/dev/swradio0`` to ``/dev/swradio255`` with major number 81 and 15dynamically allocated minor numbers 0 to 255. 16 17 18Querying Capabilities 19===================== 20 21Devices 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 26device has an Analog to Digital Converter (ADC), which is a mandatory 27element for the SDR receiver. 28 29Devices 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 34device has an Digital to Analog Converter (DAC), which is a mandatory 35element for the SDR transmitter. 36 37At least one of the read/write or streaming I/O methods 38must be supported. 39 40 41Supplemental Functions 42====================== 43 44SDR devices can support :ref:`controls <control>`, and must support 45the :ref:`tuner` ioctls. Tuner ioctls are used for setting the 46ADC/DAC sampling rate (sampling frequency) and the possible radio 47frequency (RF). 48 49The ``V4L2_TUNER_SDR`` tuner type is used for setting SDR device ADC/DAC 50frequency, and the ``V4L2_TUNER_RF`` tuner type is used for setting 51radio frequency. The tuner index of the RF tuner (if any) must always 52follow the SDR tuner index. Normally the SDR tuner is #0 and the RF 53tuner is #1. 54 55The :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl is 56not supported. 57 58 59Data Format Negotiation 60======================= 61 62The SDR device uses the :ref:`format` ioctls to select the 63capture and output format. Both the sampling resolution and the data 64streaming format are bound to that selectable format. In addition to the 65basic :ref:`format` ioctls, the 66:ref:`VIDIOC_ENUM_FMT` ioctl must be supported as 67well. 68 69To use the :ref:`format` ioctls applications set the ``type`` 70field of a struct :c:type:`v4l2_format` to 71``V4L2_BUF_TYPE_SDR_CAPTURE`` or ``V4L2_BUF_TYPE_SDR_OUTPUT`` and use 72the struct :c:type:`v4l2_sdr_format` ``sdr`` member 73of the ``fmt`` union as needed per the desired operation. Currently 74there are two fields, ``pixelformat`` and ``buffersize``, of 75struct :c:type:`v4l2_sdr_format` which are used. 76Content of the ``pixelformat`` is V4L2 FourCC code of the data format. 77The ``buffersize`` field is maximum buffer size in bytes required for 78data 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.5cm}| 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 106An SDR device may support :ref:`read/write <rw>` and/or streaming 107(:ref:`memory mapping <mmap>` or :ref:`user pointer <userp>`) I/O. 108