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, streaming or asynchronous 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