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. 109