| 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. |