Debian Codegraph @

Documentation/userspace-api/media/v4l/dev-sdr.rst

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