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