1 .. SPDX-License-Identifier: GFDL-1.1-no-invari !! 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
2 9
3 .. _sdr: 10 .. _sdr:
4 11
5 ************************************** 12 **************************************
6 Software Defined Radio Interface (SDR) 13 Software Defined Radio Interface (SDR)
7 ************************************** 14 **************************************
8 15
9 SDR is an abbreviation of Software Defined Rad 16 SDR is an abbreviation of Software Defined Radio, the radio device which
10 uses application software for modulation or de 17 uses application software for modulation or demodulation. This interface
11 is intended for controlling and data streaming 18 is intended for controlling and data streaming of such devices.
12 19
13 SDR devices are accessed through character dev 20 SDR devices are accessed through character device special files named
14 ``/dev/swradio0`` to ``/dev/swradio255`` with 21 ``/dev/swradio0`` to ``/dev/swradio255`` with major number 81 and
15 dynamically allocated minor numbers 0 to 255. 22 dynamically allocated minor numbers 0 to 255.
16 23
17 24
18 Querying Capabilities 25 Querying Capabilities
19 ===================== 26 =====================
20 27
21 Devices supporting the SDR receiver interface 28 Devices supporting the SDR receiver interface set the
22 ``V4L2_CAP_SDR_CAPTURE`` and ``V4L2_CAP_TUNER` 29 ``V4L2_CAP_SDR_CAPTURE`` and ``V4L2_CAP_TUNER`` flag in the
23 ``capabilities`` field of struct 30 ``capabilities`` field of struct
24 :c:type:`v4l2_capability` returned by the 31 :c:type:`v4l2_capability` returned by the
25 :ref:`VIDIOC_QUERYCAP` ioctl. That flag means 32 :ref:`VIDIOC_QUERYCAP` ioctl. That flag means the
26 device has an Analog to Digital Converter (ADC 33 device has an Analog to Digital Converter (ADC), which is a mandatory
27 element for the SDR receiver. 34 element for the SDR receiver.
28 35
29 Devices supporting the SDR transmitter interfa 36 Devices supporting the SDR transmitter interface set the
30 ``V4L2_CAP_SDR_OUTPUT`` and ``V4L2_CAP_MODULAT 37 ``V4L2_CAP_SDR_OUTPUT`` and ``V4L2_CAP_MODULATOR`` flag in the
31 ``capabilities`` field of struct 38 ``capabilities`` field of struct
32 :c:type:`v4l2_capability` returned by the 39 :c:type:`v4l2_capability` returned by the
33 :ref:`VIDIOC_QUERYCAP` ioctl. That flag means 40 :ref:`VIDIOC_QUERYCAP` ioctl. That flag means the
34 device has an Digital to Analog Converter (DAC 41 device has an Digital to Analog Converter (DAC), which is a mandatory
35 element for the SDR transmitter. 42 element for the SDR transmitter.
36 43
37 At least one of the read/write or streaming I/ !! 44 At least one of the read/write, streaming or asynchronous I/O methods
38 must be supported. 45 must be supported.
39 46
40 47
41 Supplemental Functions 48 Supplemental Functions
42 ====================== 49 ======================
43 50
44 SDR devices can support :ref:`controls <contro 51 SDR devices can support :ref:`controls <control>`, and must support
45 the :ref:`tuner` ioctls. Tuner ioctls are used 52 the :ref:`tuner` ioctls. Tuner ioctls are used for setting the
46 ADC/DAC sampling rate (sampling frequency) and 53 ADC/DAC sampling rate (sampling frequency) and the possible radio
47 frequency (RF). 54 frequency (RF).
48 55
49 The ``V4L2_TUNER_SDR`` tuner type is used for 56 The ``V4L2_TUNER_SDR`` tuner type is used for setting SDR device ADC/DAC
50 frequency, and the ``V4L2_TUNER_RF`` tuner typ 57 frequency, and the ``V4L2_TUNER_RF`` tuner type is used for setting
51 radio frequency. The tuner index of the RF tun 58 radio frequency. The tuner index of the RF tuner (if any) must always
52 follow the SDR tuner index. Normally the SDR t 59 follow the SDR tuner index. Normally the SDR tuner is #0 and the RF
53 tuner is #1. 60 tuner is #1.
54 61
55 The :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl is 62 The :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl is
56 not supported. 63 not supported.
57 64
58 65
59 Data Format Negotiation 66 Data Format Negotiation
60 ======================= 67 =======================
61 68
62 The SDR device uses the :ref:`format` ioctls t 69 The SDR device uses the :ref:`format` ioctls to select the
63 capture and output format. Both the sampling r 70 capture and output format. Both the sampling resolution and the data
64 streaming format are bound to that selectable 71 streaming format are bound to that selectable format. In addition to the
65 basic :ref:`format` ioctls, the 72 basic :ref:`format` ioctls, the
66 :ref:`VIDIOC_ENUM_FMT` ioctl must be supported 73 :ref:`VIDIOC_ENUM_FMT` ioctl must be supported as
67 well. 74 well.
68 75
69 To use the :ref:`format` ioctls applications s 76 To use the :ref:`format` ioctls applications set the ``type``
70 field of a struct :c:type:`v4l2_format` to 77 field of a struct :c:type:`v4l2_format` to
71 ``V4L2_BUF_TYPE_SDR_CAPTURE`` or ``V4L2_BUF_TY 78 ``V4L2_BUF_TYPE_SDR_CAPTURE`` or ``V4L2_BUF_TYPE_SDR_OUTPUT`` and use
72 the struct :c:type:`v4l2_sdr_format` ``sdr`` m 79 the struct :c:type:`v4l2_sdr_format` ``sdr`` member
73 of the ``fmt`` union as needed per the desired 80 of the ``fmt`` union as needed per the desired operation. Currently
74 there are two fields, ``pixelformat`` and ``bu !! 81 there is two fields, ``pixelformat`` and ``buffersize``, of struct
75 struct :c:type:`v4l2_sdr_format` which are use 82 struct :c:type:`v4l2_sdr_format` which are used.
76 Content of the ``pixelformat`` is V4L2 FourCC 83 Content of the ``pixelformat`` is V4L2 FourCC code of the data format.
77 The ``buffersize`` field is maximum buffer siz 84 The ``buffersize`` field is maximum buffer size in bytes required for
78 data transfer, set by the driver in order to i 85 data transfer, set by the driver in order to inform application.
79 86
80 87
81 .. c:type:: v4l2_sdr_format 88 .. c:type:: v4l2_sdr_format
82 89
83 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm !! 90 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
84 91
85 .. flat-table:: struct v4l2_sdr_format 92 .. flat-table:: struct v4l2_sdr_format
86 :header-rows: 0 93 :header-rows: 0
87 :stub-columns: 0 94 :stub-columns: 0
88 :widths: 1 1 2 95 :widths: 1 1 2
89 96
90 * - __u32 97 * - __u32
91 - ``pixelformat`` 98 - ``pixelformat``
92 - The data format or type of compression 99 - The data format or type of compression, set by the application.
93 This is a little endian 100 This is a little endian
94 :ref:`four character code <v4l2-fourcc 101 :ref:`four character code <v4l2-fourcc>`. V4L2 defines SDR
95 formats in :ref:`sdr-formats`. 102 formats in :ref:`sdr-formats`.
96 * - __u32 103 * - __u32
97 - ``buffersize`` 104 - ``buffersize``
98 - Maximum size in bytes required for dat 105 - Maximum size in bytes required for data. Value is set by the
99 driver. 106 driver.
100 * - __u8 107 * - __u8
101 - ``reserved[24]`` 108 - ``reserved[24]``
102 - This array is reserved for future exte 109 - This array is reserved for future extensions. Drivers and
103 applications must set it to zero. 110 applications must set it to zero.
104 111
105 112
106 An SDR device may support :ref:`read/write <rw 113 An SDR device may support :ref:`read/write <rw>` and/or streaming
107 (:ref:`memory mapping <mmap>` or :ref:`user po 114 (:ref:`memory mapping <mmap>` or :ref:`user pointer <userp>`) I/O.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.