0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002
0003 .. _sdr:
0004
0005 **************************************
0006 Software Defined Radio Interface (SDR)
0007 **************************************
0008
0009 SDR is an abbreviation of Software Defined Radio, the radio device which
0010 uses application software for modulation or demodulation. This interface
0011 is intended for controlling and data streaming of such devices.
0012
0013 SDR devices are accessed through character device special files named
0014 ``/dev/swradio0`` to ``/dev/swradio255`` with major number 81 and
0015 dynamically allocated minor numbers 0 to 255.
0016
0017
0018 Querying Capabilities
0019 =====================
0020
0021 Devices supporting the SDR receiver interface set the
0022 ``V4L2_CAP_SDR_CAPTURE`` and ``V4L2_CAP_TUNER`` flag in the
0023 ``capabilities`` field of struct
0024 :c:type:`v4l2_capability` returned by the
0025 :ref:`VIDIOC_QUERYCAP` ioctl. That flag means the
0026 device has an Analog to Digital Converter (ADC), which is a mandatory
0027 element for the SDR receiver.
0028
0029 Devices supporting the SDR transmitter interface set the
0030 ``V4L2_CAP_SDR_OUTPUT`` and ``V4L2_CAP_MODULATOR`` flag in the
0031 ``capabilities`` field of struct
0032 :c:type:`v4l2_capability` returned by the
0033 :ref:`VIDIOC_QUERYCAP` ioctl. That flag means the
0034 device has an Digital to Analog Converter (DAC), which is a mandatory
0035 element for the SDR transmitter.
0036
0037 At least one of the read/write, streaming or asynchronous I/O methods
0038 must be supported.
0039
0040
0041 Supplemental Functions
0042 ======================
0043
0044 SDR devices can support :ref:`controls <control>`, and must support
0045 the :ref:`tuner` ioctls. Tuner ioctls are used for setting the
0046 ADC/DAC sampling rate (sampling frequency) and the possible radio
0047 frequency (RF).
0048
0049 The ``V4L2_TUNER_SDR`` tuner type is used for setting SDR device ADC/DAC
0050 frequency, and the ``V4L2_TUNER_RF`` tuner type is used for setting
0051 radio frequency. The tuner index of the RF tuner (if any) must always
0052 follow the SDR tuner index. Normally the SDR tuner is #0 and the RF
0053 tuner is #1.
0054
0055 The :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl is
0056 not supported.
0057
0058
0059 Data Format Negotiation
0060 =======================
0061
0062 The SDR device uses the :ref:`format` ioctls to select the
0063 capture and output format. Both the sampling resolution and the data
0064 streaming format are bound to that selectable format. In addition to the
0065 basic :ref:`format` ioctls, the
0066 :ref:`VIDIOC_ENUM_FMT` ioctl must be supported as
0067 well.
0068
0069 To use the :ref:`format` ioctls applications set the ``type``
0070 field of a struct :c:type:`v4l2_format` to
0071 ``V4L2_BUF_TYPE_SDR_CAPTURE`` or ``V4L2_BUF_TYPE_SDR_OUTPUT`` and use
0072 the struct :c:type:`v4l2_sdr_format` ``sdr`` member
0073 of the ``fmt`` union as needed per the desired operation. Currently
0074 there are two fields, ``pixelformat`` and ``buffersize``, of
0075 struct :c:type:`v4l2_sdr_format` which are used.
0076 Content of the ``pixelformat`` is V4L2 FourCC code of the data format.
0077 The ``buffersize`` field is maximum buffer size in bytes required for
0078 data transfer, set by the driver in order to inform application.
0079
0080
0081 .. c:type:: v4l2_sdr_format
0082
0083 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0084
0085 .. flat-table:: struct v4l2_sdr_format
0086 :header-rows: 0
0087 :stub-columns: 0
0088 :widths: 1 1 2
0089
0090 * - __u32
0091 - ``pixelformat``
0092 - The data format or type of compression, set by the application.
0093 This is a little endian
0094 :ref:`four character code <v4l2-fourcc>`. V4L2 defines SDR
0095 formats in :ref:`sdr-formats`.
0096 * - __u32
0097 - ``buffersize``
0098 - Maximum size in bytes required for data. Value is set by the
0099 driver.
0100 * - __u8
0101 - ``reserved[24]``
0102 - This array is reserved for future extensions. Drivers and
0103 applications must set it to zero.
0104
0105
0106 An SDR device may support :ref:`read/write <rw>` and/or streaming
0107 (:ref:`memory mapping <mmap>` or :ref:`user pointer <userp>`) I/O.
