1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 254f38fcaSMauro Carvalho Chehab 354f38fcaSMauro Carvalho Chehab.. _sdr: 454f38fcaSMauro Carvalho Chehab 554f38fcaSMauro Carvalho Chehab************************************** 654f38fcaSMauro Carvalho ChehabSoftware Defined Radio Interface (SDR) 754f38fcaSMauro Carvalho Chehab************************************** 854f38fcaSMauro Carvalho Chehab 954f38fcaSMauro Carvalho ChehabSDR is an abbreviation of Software Defined Radio, the radio device which 1054f38fcaSMauro Carvalho Chehabuses application software for modulation or demodulation. This interface 1154f38fcaSMauro Carvalho Chehabis intended for controlling and data streaming of such devices. 1254f38fcaSMauro Carvalho Chehab 1354f38fcaSMauro Carvalho ChehabSDR devices are accessed through character device special files named 1454f38fcaSMauro Carvalho Chehab``/dev/swradio0`` to ``/dev/swradio255`` with major number 81 and 1554f38fcaSMauro Carvalho Chehabdynamically allocated minor numbers 0 to 255. 1654f38fcaSMauro Carvalho Chehab 1754f38fcaSMauro Carvalho Chehab 1854f38fcaSMauro Carvalho ChehabQuerying Capabilities 1954f38fcaSMauro Carvalho Chehab===================== 2054f38fcaSMauro Carvalho Chehab 2154f38fcaSMauro Carvalho ChehabDevices supporting the SDR receiver interface set the 2254f38fcaSMauro Carvalho Chehab``V4L2_CAP_SDR_CAPTURE`` and ``V4L2_CAP_TUNER`` flag in the 2354f38fcaSMauro Carvalho Chehab``capabilities`` field of struct 2454f38fcaSMauro Carvalho Chehab:c:type:`v4l2_capability` returned by the 2554f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_QUERYCAP` ioctl. That flag means the 2654f38fcaSMauro Carvalho Chehabdevice has an Analog to Digital Converter (ADC), which is a mandatory 2754f38fcaSMauro Carvalho Chehabelement for the SDR receiver. 2854f38fcaSMauro Carvalho Chehab 2954f38fcaSMauro Carvalho ChehabDevices supporting the SDR transmitter interface set the 3054f38fcaSMauro Carvalho Chehab``V4L2_CAP_SDR_OUTPUT`` and ``V4L2_CAP_MODULATOR`` flag in the 3154f38fcaSMauro Carvalho Chehab``capabilities`` field of struct 3254f38fcaSMauro Carvalho Chehab:c:type:`v4l2_capability` returned by the 3354f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_QUERYCAP` ioctl. That flag means the 3454f38fcaSMauro Carvalho Chehabdevice has an Digital to Analog Converter (DAC), which is a mandatory 3554f38fcaSMauro Carvalho Chehabelement for the SDR transmitter. 3654f38fcaSMauro Carvalho Chehab 37*17611d3fSHans VerkuilAt least one of the read/write or streaming I/O methods 3854f38fcaSMauro Carvalho Chehabmust be supported. 3954f38fcaSMauro Carvalho Chehab 4054f38fcaSMauro Carvalho Chehab 4154f38fcaSMauro Carvalho ChehabSupplemental Functions 4254f38fcaSMauro Carvalho Chehab====================== 4354f38fcaSMauro Carvalho Chehab 4454f38fcaSMauro Carvalho ChehabSDR devices can support :ref:`controls <control>`, and must support 4554f38fcaSMauro Carvalho Chehabthe :ref:`tuner` ioctls. Tuner ioctls are used for setting the 4654f38fcaSMauro Carvalho ChehabADC/DAC sampling rate (sampling frequency) and the possible radio 4754f38fcaSMauro Carvalho Chehabfrequency (RF). 4854f38fcaSMauro Carvalho Chehab 4954f38fcaSMauro Carvalho ChehabThe ``V4L2_TUNER_SDR`` tuner type is used for setting SDR device ADC/DAC 5054f38fcaSMauro Carvalho Chehabfrequency, and the ``V4L2_TUNER_RF`` tuner type is used for setting 5154f38fcaSMauro Carvalho Chehabradio frequency. The tuner index of the RF tuner (if any) must always 5254f38fcaSMauro Carvalho Chehabfollow the SDR tuner index. Normally the SDR tuner is #0 and the RF 5354f38fcaSMauro Carvalho Chehabtuner is #1. 5454f38fcaSMauro Carvalho Chehab 5554f38fcaSMauro Carvalho ChehabThe :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl is 5654f38fcaSMauro Carvalho Chehabnot supported. 5754f38fcaSMauro Carvalho Chehab 5854f38fcaSMauro Carvalho Chehab 5954f38fcaSMauro Carvalho ChehabData Format Negotiation 6054f38fcaSMauro Carvalho Chehab======================= 6154f38fcaSMauro Carvalho Chehab 6254f38fcaSMauro Carvalho ChehabThe SDR device uses the :ref:`format` ioctls to select the 6354f38fcaSMauro Carvalho Chehabcapture and output format. Both the sampling resolution and the data 6454f38fcaSMauro Carvalho Chehabstreaming format are bound to that selectable format. In addition to the 6554f38fcaSMauro Carvalho Chehabbasic :ref:`format` ioctls, the 6654f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_ENUM_FMT` ioctl must be supported as 6754f38fcaSMauro Carvalho Chehabwell. 6854f38fcaSMauro Carvalho Chehab 6954f38fcaSMauro Carvalho ChehabTo use the :ref:`format` ioctls applications set the ``type`` 7054f38fcaSMauro Carvalho Chehabfield of a struct :c:type:`v4l2_format` to 7154f38fcaSMauro Carvalho Chehab``V4L2_BUF_TYPE_SDR_CAPTURE`` or ``V4L2_BUF_TYPE_SDR_OUTPUT`` and use 7254f38fcaSMauro Carvalho Chehabthe struct :c:type:`v4l2_sdr_format` ``sdr`` member 7354f38fcaSMauro Carvalho Chehabof the ``fmt`` union as needed per the desired operation. Currently 74b4cc96f9SRandy Dunlapthere are two fields, ``pixelformat`` and ``buffersize``, of 7554f38fcaSMauro Carvalho Chehabstruct :c:type:`v4l2_sdr_format` which are used. 7654f38fcaSMauro Carvalho ChehabContent of the ``pixelformat`` is V4L2 FourCC code of the data format. 7754f38fcaSMauro Carvalho ChehabThe ``buffersize`` field is maximum buffer size in bytes required for 7854f38fcaSMauro Carvalho Chehabdata transfer, set by the driver in order to inform application. 7954f38fcaSMauro Carvalho Chehab 8054f38fcaSMauro Carvalho Chehab 8154f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_sdr_format 8254f38fcaSMauro Carvalho Chehab 83fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| 8454f38fcaSMauro Carvalho Chehab 8554f38fcaSMauro Carvalho Chehab.. flat-table:: struct v4l2_sdr_format 8654f38fcaSMauro Carvalho Chehab :header-rows: 0 8754f38fcaSMauro Carvalho Chehab :stub-columns: 0 8854f38fcaSMauro Carvalho Chehab :widths: 1 1 2 8954f38fcaSMauro Carvalho Chehab 9054f38fcaSMauro Carvalho Chehab * - __u32 9154f38fcaSMauro Carvalho Chehab - ``pixelformat`` 9254f38fcaSMauro Carvalho Chehab - The data format or type of compression, set by the application. 9354f38fcaSMauro Carvalho Chehab This is a little endian 9454f38fcaSMauro Carvalho Chehab :ref:`four character code <v4l2-fourcc>`. V4L2 defines SDR 9554f38fcaSMauro Carvalho Chehab formats in :ref:`sdr-formats`. 9654f38fcaSMauro Carvalho Chehab * - __u32 9754f38fcaSMauro Carvalho Chehab - ``buffersize`` 9854f38fcaSMauro Carvalho Chehab - Maximum size in bytes required for data. Value is set by the 9954f38fcaSMauro Carvalho Chehab driver. 10054f38fcaSMauro Carvalho Chehab * - __u8 10154f38fcaSMauro Carvalho Chehab - ``reserved[24]`` 10254f38fcaSMauro Carvalho Chehab - This array is reserved for future extensions. Drivers and 10354f38fcaSMauro Carvalho Chehab applications must set it to zero. 10454f38fcaSMauro Carvalho Chehab 10554f38fcaSMauro Carvalho Chehab 10654f38fcaSMauro Carvalho ChehabAn SDR device may support :ref:`read/write <rw>` and/or streaming 10754f38fcaSMauro Carvalho Chehab(:ref:`memory mapping <mmap>` or :ref:`user pointer <userp>`) I/O. 108