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