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