code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _frontend-property-terrestrial-systems:

***********************************************
Properties used on terrestrial delivery systems
***********************************************

.. _dvbt-params:

DVB-T delivery system
=====================

The following parameters are valid for DVB-T:

-  :ref:`DTV_API_VERSION <DTV-API-VERSION>`

-  :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`

-  :ref:`DTV_TUNE <DTV-TUNE>`

-  :ref:`DTV_CLEAR <DTV-CLEAR>`

-  :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`

-  :ref:`DTV_MODULATION <DTV-MODULATION>`

-  :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`

-  :ref:`DTV_INVERSION <DTV-INVERSION>`

-  :ref:`DTV_CODE_RATE_HP <DTV-CODE-RATE-HP>`

-  :ref:`DTV_CODE_RATE_LP <DTV-CODE-RATE-LP>`

-  :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`

-  :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`

-  :ref:`DTV_HIERARCHY <DTV-HIERARCHY>`

-  :ref:`DTV_LNA <DTV-LNA>`

In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
are also valid.

.. _dvbt2-params:

DVB-T2 delivery system
======================

DVB-T2 support is currently in the early stages of development, so
expect that this section maygrow and become more detailed with time.

The following parameters are valid for DVB-T2:

-  :ref:`DTV_API_VERSION <DTV-API-VERSION>`

-  :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`

-  :ref:`DTV_TUNE <DTV-TUNE>`

-  :ref:`DTV_CLEAR <DTV-CLEAR>`

-  :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`

-  :ref:`DTV_MODULATION <DTV-MODULATION>`

-  :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`

-  :ref:`DTV_INVERSION <DTV-INVERSION>`

-  :ref:`DTV_CODE_RATE_HP <DTV-CODE-RATE-HP>`

-  :ref:`DTV_CODE_RATE_LP <DTV-CODE-RATE-LP>`

-  :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`

-  :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`

-  :ref:`DTV_HIERARCHY <DTV-HIERARCHY>`

-  :ref:`DTV_STREAM_ID <DTV-STREAM-ID>`

-  :ref:`DTV_LNA <DTV-LNA>`

In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
are also valid.

.. _isdbt:

ISDB-T delivery system
======================

This ISDB-T/ISDB-Tsb API extension should reflect all information needed
to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible that some
very sophisticated devices won't need certain parameters to tune.

The information given here should help application writers to know how
to handle ISDB-T and ISDB-Tsb hardware using the Linux Digital TV API.

The details given here about ISDB-T and ISDB-Tsb are just enough to
basically show the dependencies between the needed parameter values, but
surely some information is left out. For more detailed information see
the following documents:

ARIB STD-B31 - "Transmission System for Digital Terrestrial Television
Broadcasting" and

ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial Television
Broadcasting".

In order to understand the ISDB specific parameters, one has to have
some knowledge the channel structure in ISDB-T and ISDB-Tsb. I.e. it has
to be known to the reader that an ISDB-T channel consists of 13
segments, that it can have up to 3 layer sharing those segments, and
things like that.

The following parameters are valid for ISDB-T:

-  :ref:`DTV_API_VERSION <DTV-API-VERSION>`

-  :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`

-  :ref:`DTV_TUNE <DTV-TUNE>`

-  :ref:`DTV_CLEAR <DTV-CLEAR>`

-  :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`

-  :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`

-  :ref:`DTV_INVERSION <DTV-INVERSION>`

-  :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`

-  :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`

-  :ref:`DTV_ISDBT_LAYER_ENABLED <DTV-ISDBT-LAYER-ENABLED>`

-  :ref:`DTV_ISDBT_PARTIAL_RECEPTION <DTV-ISDBT-PARTIAL-RECEPTION>`

-  :ref:`DTV_ISDBT_SOUND_BROADCASTING <DTV-ISDBT-SOUND-BROADCASTING>`

-  :ref:`DTV_ISDBT_SB_SUBCHANNEL_ID <DTV-ISDBT-SB-SUBCHANNEL-ID>`

-  :ref:`DTV_ISDBT_SB_SEGMENT_IDX <DTV-ISDBT-SB-SEGMENT-IDX>`

-  :ref:`DTV_ISDBT_SB_SEGMENT_COUNT <DTV-ISDBT-SB-SEGMENT-COUNT>`

-  :ref:`DTV_ISDBT_LAYERA_FEC <DTV-ISDBT-LAYER-FEC>`

-  :ref:`DTV_ISDBT_LAYERA_MODULATION <DTV-ISDBT-LAYER-MODULATION>`

-  :ref:`DTV_ISDBT_LAYERA_SEGMENT_COUNT <DTV-ISDBT-LAYER-SEGMENT-COUNT>`

-  :ref:`DTV_ISDBT_LAYERA_TIME_INTERLEAVING <DTV-ISDBT-LAYER-TIME-INTERLEAVING>`

-  :ref:`DTV_ISDBT_LAYERB_FEC <DTV-ISDBT-LAYER-FEC>`

-  :ref:`DTV_ISDBT_LAYERB_MODULATION <DTV-ISDBT-LAYER-MODULATION>`

-  :ref:`DTV_ISDBT_LAYERB_SEGMENT_COUNT <DTV-ISDBT-LAYER-SEGMENT-COUNT>`

-  :ref:`DTV_ISDBT_LAYERB_TIME_INTERLEAVING <DTV-ISDBT-LAYER-TIME-INTERLEAVING>`

-  :ref:`DTV_ISDBT_LAYERC_FEC <DTV-ISDBT-LAYER-FEC>`

-  :ref:`DTV_ISDBT_LAYERC_MODULATION <DTV-ISDBT-LAYER-MODULATION>`

-  :ref:`DTV_ISDBT_LAYERC_SEGMENT_COUNT <DTV-ISDBT-LAYER-SEGMENT-COUNT>`

-  :ref:`DTV_ISDBT_LAYERC_TIME_INTERLEAVING <DTV-ISDBT-LAYER-TIME-INTERLEAVING>`

In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
are also valid.

.. _atsc-params:

ATSC delivery system
====================

The following parameters are valid for ATSC:

-  :ref:`DTV_API_VERSION <DTV-API-VERSION>`

-  :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`

-  :ref:`DTV_TUNE <DTV-TUNE>`

-  :ref:`DTV_CLEAR <DTV-CLEAR>`

-  :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`

-  :ref:`DTV_MODULATION <DTV-MODULATION>`

-  :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`

In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
are also valid.

.. _atscmh-params:

ATSC-MH delivery system
=======================

The following parameters are valid for ATSC-MH:

-  :ref:`DTV_API_VERSION <DTV-API-VERSION>`

-  :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`

-  :ref:`DTV_TUNE <DTV-TUNE>`

-  :ref:`DTV_CLEAR <DTV-CLEAR>`

-  :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`

-  :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`

-  :ref:`DTV_ATSCMH_FIC_VER <DTV-ATSCMH-FIC-VER>`

-  :ref:`DTV_ATSCMH_PARADE_ID <DTV-ATSCMH-PARADE-ID>`

-  :ref:`DTV_ATSCMH_NOG <DTV-ATSCMH-NOG>`

-  :ref:`DTV_ATSCMH_TNOG <DTV-ATSCMH-TNOG>`

-  :ref:`DTV_ATSCMH_SGN <DTV-ATSCMH-SGN>`

-  :ref:`DTV_ATSCMH_PRC <DTV-ATSCMH-PRC>`

-  :ref:`DTV_ATSCMH_RS_FRAME_MODE <DTV-ATSCMH-RS-FRAME-MODE>`

-  :ref:`DTV_ATSCMH_RS_FRAME_ENSEMBLE <DTV-ATSCMH-RS-FRAME-ENSEMBLE>`

-  :ref:`DTV_ATSCMH_RS_CODE_MODE_PRI <DTV-ATSCMH-RS-CODE-MODE-PRI>`

-  :ref:`DTV_ATSCMH_RS_CODE_MODE_SEC <DTV-ATSCMH-RS-CODE-MODE-SEC>`

-  :ref:`DTV_ATSCMH_SCCC_BLOCK_MODE <DTV-ATSCMH-SCCC-BLOCK-MODE>`

-  :ref:`DTV_ATSCMH_SCCC_CODE_MODE_A <DTV-ATSCMH-SCCC-CODE-MODE-A>`

-  :ref:`DTV_ATSCMH_SCCC_CODE_MODE_B <DTV-ATSCMH-SCCC-CODE-MODE-B>`

-  :ref:`DTV_ATSCMH_SCCC_CODE_MODE_C <DTV-ATSCMH-SCCC-CODE-MODE-C>`

-  :ref:`DTV_ATSCMH_SCCC_CODE_MODE_D <DTV-ATSCMH-SCCC-CODE-MODE-D>`

In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
are also valid.

.. _dtmb-params:

DTMB delivery system
====================

The following parameters are valid for DTMB:

-  :ref:`DTV_API_VERSION <DTV-API-VERSION>`

-  :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`

-  :ref:`DTV_TUNE <DTV-TUNE>`

-  :ref:`DTV_CLEAR <DTV-CLEAR>`

-  :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`

-  :ref:`DTV_MODULATION <DTV-MODULATION>`

-  :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`

-  :ref:`DTV_INVERSION <DTV-INVERSION>`

-  :ref:`DTV_INNER_FEC <DTV-INNER-FEC>`

-  :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`

-  :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`

-  :ref:`DTV_INTERLEAVING <DTV-INTERLEAVING>`

-  :ref:`DTV_LNA <DTV-LNA>`

In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
are also valid.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _frontend-stat-properties:

******************************
Frontend statistics indicators
******************************

The values are returned via ``dtv_property.stat``. If the property is
supported, ``dtv_property.stat.len`` is bigger than zero.

For most delivery systems, ``dtv_property.stat.len`` will be 1 if the
stats is supported, and the properties will return a single value for
each parameter.

It should be noted, however, that new OFDM delivery systems like ISDB
can use different modulation types for each group of carriers. On such
standards, up to 3 groups of statistics can be provided, and
``dtv_property.stat.len`` is updated to reflect the "global" metrics,
plus one metric per each carrier group (called "layer" on ISDB).

So, in order to be consistent with other delivery systems, the first
value at :c:type:`dtv_property.stat.dtv_stats <dtv_stats>` array refers
to the global metric. The other elements of the array represent each
layer, starting from layer A(index 1), layer B (index 2) and so on.

The number of filled elements are stored at ``dtv_property.stat.len``.

Each element of the ``dtv_property.stat.dtv_stats`` array consists on
two elements:

-  ``svalue`` or ``uvalue``, where ``svalue`` is for signed values of
   the measure (dB measures) and ``uvalue`` is for unsigned values
   (counters, relative scale)

-  ``scale`` - Scale for the value. It can be:

   -  ``FE_SCALE_NOT_AVAILABLE`` - The parameter is supported by the
      frontend, but it was not possible to collect it (could be a
      transitory or permanent condition)

   -  ``FE_SCALE_DECIBEL`` - parameter is a signed value, measured in
      1/1000 dB

   -  ``FE_SCALE_RELATIVE`` - parameter is a unsigned value, where 0
      means 0% and 65535 means 100%.

   -  ``FE_SCALE_COUNTER`` - parameter is a unsigned value that counts
      the occurrence of an event, like bit error, block error, or lapsed
      time.

.. _DTV-STAT-SIGNAL-STRENGTH:

DTV_STAT_SIGNAL_STRENGTH
========================

Indicates the signal strength level at the analog part of the tuner or
of the demod.

Possible scales for this metric are:

-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
   measurement was not complete yet.

-  ``FE_SCALE_DECIBEL`` - signal strength is in 0.001 dBm units, power
   measured in miliwatts. This value is generally negative.

-  ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100%
   measurement for power (actually, 0 to 65535).

.. _DTV-STAT-CNR:

DTV_STAT_CNR
============

Indicates the Signal to Noise ratio for the main carrier.

Possible scales for this metric are:

-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
   measurement was not complete yet.

-  ``FE_SCALE_DECIBEL`` - Signal/Noise ratio is in 0.001 dB units.

-  ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100%
   measurement for Signal/Noise (actually, 0 to 65535).

.. _DTV-STAT-PRE-ERROR-BIT-COUNT:

DTV_STAT_PRE_ERROR_BIT_COUNT
============================

Measures the number of bit errors before the forward error correction
(FEC) on the inner coding block (before Viterbi, LDPC or other inner
code).

This measure is taken during the same interval as
``DTV_STAT_PRE_TOTAL_BIT_COUNT``.

In order to get the BER (Bit Error Rate) measurement, it should be
divided by
:ref:`DTV_STAT_PRE_TOTAL_BIT_COUNT <DTV-STAT-PRE-TOTAL-BIT-COUNT>`.

This measurement is monotonically increased, as the frontend gets more
bit count measurements. The frontend may reset it when a
channel/transponder is tuned.

Possible scales for this metric are:

-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
   measurement was not complete yet.

-  ``FE_SCALE_COUNTER`` - Number of error bits counted before the inner
   coding.

.. _DTV-STAT-PRE-TOTAL-BIT-COUNT:

DTV_STAT_PRE_TOTAL_BIT_COUNT
============================

Measures the amount of bits received before the inner code block, during
the same period as
:ref:`DTV_STAT_PRE_ERROR_BIT_COUNT <DTV-STAT-PRE-ERROR-BIT-COUNT>`
measurement was taken.

It should be noted that this measurement can be smaller than the total
amount of bits on the transport stream, as the frontend may need to
manually restart the measurement, losing some data between each
measurement interval.

This measurement is monotonically increased, as the frontend gets more
bit count measurements. The frontend may reset it when a
channel/transponder is tuned.

Possible scales for this metric are:

-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
   measurement was not complete yet.

-  ``FE_SCALE_COUNTER`` - Number of bits counted while measuring
   :ref:`DTV_STAT_PRE_ERROR_BIT_COUNT <DTV-STAT-PRE-ERROR-BIT-COUNT>`.

.. _DTV-STAT-POST-ERROR-BIT-COUNT:

DTV_STAT_POST_ERROR_BIT_COUNT
=============================

Measures the number of bit errors after the forward error correction
(FEC) done by inner code block (after Viterbi, LDPC or other inner
code).

This measure is taken during the same interval as
``DTV_STAT_POST_TOTAL_BIT_COUNT``.

In order to get the BER (Bit Error Rate) measurement, it should be
divided by
:ref:`DTV_STAT_POST_TOTAL_BIT_COUNT <DTV-STAT-POST-TOTAL-BIT-COUNT>`.

This measurement is monotonically increased, as the frontend gets more
bit count measurements. The frontend may reset it when a
channel/transponder is tuned.

Possible scales for this metric are:

-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
   measurement was not complete yet.

-  ``FE_SCALE_COUNTER`` - Number of error bits counted after the inner
   coding.

.. _DTV-STAT-POST-TOTAL-BIT-COUNT:

DTV_STAT_POST_TOTAL_BIT_COUNT
=============================

Measures the amount of bits received after the inner coding, during the
same period as
:ref:`DTV_STAT_POST_ERROR_BIT_COUNT <DTV-STAT-POST-ERROR-BIT-COUNT>`
measurement was taken.

It should be noted that this measurement can be smaller than the total
amount of bits on the transport stream, as the frontend may need to
manually restart the measurement, losing some data between each
measurement interval.

This measurement is monotonically increased, as the frontend gets more
bit count measurements. The frontend may reset it when a
channel/transponder is tuned.

Possible scales for this metric are:

-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
   measurement was not complete yet.

-  ``FE_SCALE_COUNTER`` - Number of bits counted while measuring
   :ref:`DTV_STAT_POST_ERROR_BIT_COUNT <DTV-STAT-POST-ERROR-BIT-COUNT>`.

.. _DTV-STAT-ERROR-BLOCK-COUNT:

DTV_STAT_ERROR_BLOCK_COUNT
==========================

Measures the number of block errors after the outer forward error
correction coding (after Reed-Solomon or other outer code).

This measurement is monotonically increased, as the frontend gets more
bit count measurements. The frontend may reset it when a
channel/transponder is tuned.

Possible scales for this metric are:

-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
   measurement was not complete yet.

-  ``FE_SCALE_COUNTER`` - Number of error blocks counted after the outer
   coding.

.. _DTV-STAT-TOTAL-BLOCK-COUNT:

DTV-STAT_TOTAL_BLOCK_COUNT
==========================

Measures the total number of blocks received during the same period as
:ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>`
measurement was taken.

It can be used to calculate the PER indicator, by dividing
:ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>` by
:ref:`DTV-STAT-TOTAL-BLOCK-COUNT`.

Possible scales for this metric are:

-  ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
   measurement was not complete yet.

-  ``FE_SCALE_COUNTER`` - Number of blocks counted while measuring
   :ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>`.

repo_name: angery/linux


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _dvb_frontend:

#######################
Digital TV Frontend API
#######################

The Digital TV frontend API was designed to support three groups of delivery
systems: Terrestrial, cable and Satellite. Currently, the following
delivery systems are supported:

-  Terrestrial systems: DVB-T, DVB-T2, ATSC, ATSC M/H, ISDB-T, DVB-H,
   DTMB, CMMB

-  Cable systems: DVB-C Annex A/C, ClearQAM (DVB-C Annex B)

-  Satellite systems: DVB-S, DVB-S2, DVB Turbo, ISDB-S, DSS

The Digital TV frontend controls several sub-devices including:

-  Tuner

-  Digital TV demodulator

-  Low noise amplifier (LNA)

-  Satellite Equipment Control (SEC) [#f1]_.

The frontend can be accessed through ``/dev/dvb/adapter?/frontend?``.
Data types and ioctl definitions can be accessed by including
``linux/dvb/frontend.h`` in your application.

.. note::

   Transmission via the internet (DVB-IP) and MMT (MPEG Media Transport)
   is not yet handled by this API but a future extension is possible.

.. [#f1]

   On Satellite systems, the API support for the Satellite Equipment
   Control (SEC) allows to power control and to send/receive signals to
   control the antenna subsystem, selecting the polarization and choosing
   the Intermediate Frequency IF) of the Low Noise Block Converter Feed
   Horn (LNBf). It supports the DiSEqC and V-SEC protocols. The DiSEqC
   (digital SEC) specification is available at
   `Eutelsat <http://www.eutelsat.com/satellites/4_5_5.html>`__.

.. toctree::
    :maxdepth: 1

    query-dvb-frontend-info
    dvb-fe-read-status
    dvbproperty
    frontend_fcalls


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: DTV.fe

.. _frontend_f_close:

***************************
Digital TV frontend close()
***************************

Name
====

fe-close - Close a frontend device

Synopsis
========

.. code-block:: c

    #include <unistd.h>

.. c:function:: int close( int fd )

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

Description
===========

This system call closes a previously opened front-end device. After
closing a front-end device, its corresponding hardware might be powered
down automatically.

Return Value
============

On success 0 is returned.

On error -1 is returned, and the ``errno`` variable is set
appropriately.

Generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: DTV.fe

.. _frontend_f_open:

***************************
Digital TV frontend open()
***************************

Name
====

fe-open - Open a frontend device

Synopsis
========

.. code-block:: c

    #include <fcntl.h>

.. c:function:: int open( const char *device_name, int flags )

Arguments
=========

``device_name``
    Device to be opened.

``flags``
    Open flags. Access can either be ``O_RDWR`` or ``O_RDONLY``.

    Multiple opens are allowed with ``O_RDONLY``. In this mode, only
    query and read ioctls are allowed.

    Only one open is allowed in ``O_RDWR``. In this mode, all ioctls are
    allowed.

    When the ``O_NONBLOCK`` flag is given, the system calls may return
    ``EAGAIN`` error code when no data is available or when the device
    driver is temporarily busy.

    Other flags have no effect.

Description
===========

This system call opens a named frontend device
(``/dev/dvb/adapter?/frontend?``) for subsequent use. Usually the first
thing to do after a successful open is to find out the frontend type
with :ref:`FE_GET_INFO`.

The device can be opened in read-only mode, which only allows monitoring
of device status and statistics, or read/write mode, which allows any
kind of use (e.g. performing tuning operations.)

In a system with multiple front-ends, it is usually the case that
multiple devices cannot be open in read/write mode simultaneously. As
long as a front-end device is opened in read/write mode, other open()
calls in read/write mode will either fail or block, depending on whether
non-blocking or blocking mode was specified. A front-end device opened
in blocking mode can later be put into non-blocking mode (and vice
versa) using the F_SETFL command of the fcntl system call. This is a
standard system call, documented in the Linux manual page for fcntl.
When an open() call has succeeded, the device will be ready for use in
the specified mode. This implies that the corresponding hardware is
powered up, and that other front-ends may have been powered down to make
that possible.

Return Value
============

On success :c:func:`open()` returns the new file descriptor.
On error, -1 is returned, and the ``errno`` variable is set appropriately.

Possible error codes are:

On success 0 is returned, and :c:type:`ca_slot_info` is filled.

On error -1 is returned, and the ``errno`` variable is set
appropriately.

.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|

.. flat-table::
    :header-rows:  0
    :stub-columns: 0
    :widths: 1 16

    -  - ``EPERM``
       -  The caller has no permission to access the device.

    -  - ``EBUSY``
       -  The the device driver is already in use.

    -  - ``EMFILE``
       -  The process already has the maximum number of files open.

    -  - ``ENFILE``
       -  The limit on the total number of files open on the system has been
	  reached.

The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _frontend_fcalls:

#######################
Frontend Function Calls
#######################

.. toctree::
    :maxdepth: 1

    frontend_f_open
    frontend_f_close
    fe-get-info
    fe-read-status
    fe-get-property
    fe-diseqc-reset-overload
    fe-diseqc-send-master-cmd
    fe-diseqc-recv-slave-reply
    fe-diseqc-send-burst
    fe-set-tone
    fe-set-voltage
    fe-enable-high-lnb-voltage
    fe-set-frontend-tune-mode


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _frontend_legacy_types:

Frontend Legacy Data Types
==========================

.. toctree::
    :maxdepth: 1

    fe-type-t
    fe-bandwidth-t
    dvb-frontend-parameters
    dvb-frontend-event

.. _frontend_legacy_fcalls:

Frontend Legacy Function Calls
==============================

Those functions are defined at DVB version 3. The support is kept in the
kernel due to compatibility issues only. Their usage is strongly not
recommended

.. toctree::
    :maxdepth: 1

    fe-read-ber
    fe-read-snr
    fe-read-signal-strength
    fe-read-uncorrected-blocks
    fe-set-frontend
    fe-get-frontend
    fe-get-event
    fe-dishnetwork-send-legacy-cmd


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _frontend_legacy_dvbv3_api:

***********************************************
Digital TV Frontend legacy API (a. k. a. DVBv3)
***********************************************

The usage of this API is deprecated, as it doesn't support all digital
TV standards, doesn't provide good statistics measurements and provides
incomplete information. This is kept only to support legacy
applications.

.. toctree::
    :maxdepth: 1

    frontend_legacy_api


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

****************************
Digital TV uAPI header files
****************************

Digital TV uAPI headers
***********************

.. kernel-include:: $BUILDDIR/frontend.h.rst

.. kernel-include:: $BUILDDIR/dmx.h.rst

.. kernel-include:: $BUILDDIR/ca.h.rst

.. kernel-include:: $BUILDDIR/net.h.rst


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _dvb_introdution:

************
Introduction
************

.. _requisites:

What you need to know
=====================

The reader of this document is required to have some knowledge in the
area of digital video broadcasting (Digital TV) and should be familiar with
part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e
you should know what a program/transport stream (PS/TS) is and what is
meant by a packetized elementary stream (PES) or an I-frame.

Various Digital TV standards documents are available for download at:

- European standards (DVB): http://www.dvb.org and/or http://www.etsi.org.
- American standards (ATSC): https://www.atsc.org/standards/
- Japanese standards (ISDB): http://www.dibeg.org/

It is also necessary to know how to access Linux devices and how to
use ioctl calls. This also includes the knowledge of C or C++.

.. _history:

History
=======

The first API for Digital TV cards we used at Convergence in late 1999 was an
extension of the Video4Linux API which was primarily developed for frame
grabber cards. As such it was not really well suited to be used for Digital
TV cards and their new features like recording MPEG streams and filtering
several section and PES data streams at the same time.

In early 2000, Convergence was approached by Nokia with a proposal for a new
standard Linux Digital TV API. As a commitment to the development of terminals
based on open standards, Nokia and Convergence made it available to all
Linux developers and published it on https://linuxtv.org in September
2000. With the Linux driver for the Siemens/Hauppauge DVB PCI card,
Convergence provided a first implementation of the Linux Digital TV API.
Convergence was the maintainer of the Linux Digital TV API in the early
days.

Now, the API is maintained by the LinuxTV community (i.e. you, the reader
of this document). The Linux  Digital TV API is constantly reviewed and
improved together with the improvements at the subsystem's core at the
Kernel.

.. _overview:

Overview
========

.. _stb_components:

.. kernel-figure:: dvbstb.svg
    :alt:   dvbstb.svg
    :align: center

    Components of a Digital TV card/STB

A Digital TV card or set-top-box (STB) usually consists of the
following main hardware components:

Frontend consisting of tuner and digital TV demodulator
   Here the raw signal reaches the digital TV hardware from a satellite dish or
   antenna or directly from cable. The frontend down-converts and
   demodulates this signal into an MPEG transport stream (TS). In case
   of a satellite frontend, this includes a facility for satellite
   equipment control (SEC), which allows control of LNB polarization,
   multi feed switches or dish rotors.

Conditional Access (CA) hardware like CI adapters and smartcard slots
   The complete TS is passed through the CA hardware. Programs to which
   the user has access (controlled by the smart card) are decoded in
   real time and re-inserted into the TS.

   .. note::

      Not every digital TV hardware provides conditional access hardware.

Demultiplexer which filters the incoming Digital TV MPEG-TS stream
   The demultiplexer splits the TS into its components like audio and
   video streams. Besides usually several of such audio and video
   streams it also contains data streams with information about the
   programs offered in this or other streams of the same provider.

Audio and video decoder
   The main targets of the demultiplexer are audio and video
   decoders. After decoding, they pass on the uncompressed audio and
   video to the computer screen or to a TV set.

   .. note::

      Modern hardware usually doesn't have a separate decoder hardware, as
      such functionality can be provided by the main CPU, by the graphics
      adapter of the system or by a signal processing hardware embedded on
      a Systems on a Chip (SoC) integrated circuit.

      It may also not be needed for certain usages (e.g. for data-only
      uses like "internet over satellite").

:ref:`stb_components` shows a crude schematic of the control and data
flow between those components.

.. _dvb_devices:

Linux Digital TV Devices
========================

The Linux Digital TV API lets you control these hardware components through
currently six Unix-style character devices for video, audio, frontend,
demux, CA and IP-over-DVB networking. The video and audio devices
control the MPEG2 decoder hardware, the frontend device the tuner and
the Digital TV demodulator. The demux device gives you control over the PES
and section filters of the hardware. If the hardware does not support
filtering these filters can be implemented in software. Finally, the CA
device controls all the conditional access capabilities of the hardware.
It can depend on the individual security requirements of the platform,
if and how many of the CA functions are made available to the
application through this device.

All devices can be found in the ``/dev`` tree under ``/dev/dvb``. The
individual devices are called:

-  ``/dev/dvb/adapterN/audioM``,

-  ``/dev/dvb/adapterN/videoM``,

-  ``/dev/dvb/adapterN/frontendM``,

-  ``/dev/dvb/adapterN/netM``,

-  ``/dev/dvb/adapterN/demuxM``,

-  ``/dev/dvb/adapterN/dvrM``,

-  ``/dev/dvb/adapterN/caM``,

where ``N`` enumerates the Digital TV cards in a system starting from 0, and
``M`` enumerates the devices of each type within each adapter, starting
from 0, too. We will omit the "``/dev/dvb/adapterN/``\ " in the further
discussion of these devices.

More details about the data structures and function calls of all the
devices are described in the following chapters.

.. _include_files:

API include files
=================

For each of the Digital TV devices a corresponding include file exists. The
Digital TV API include files should be included in application sources with a
partial path like:

.. code-block:: c

	#include <linux/dvb/ca.h>

	#include <linux/dvb/dmx.h>

	#include <linux/dvb/frontend.h>

	#include <linux/dvb/net.h>

To enable applications to support different API version, an additional
include file ``linux/dvb/version.h`` exists, which defines the constant
``DVB_API_VERSION``. This document describes ``DVB_API_VERSION 5.10``.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _legacy_dvb_apis:

***************************
Digital TV Deprecated APIs
***************************

The APIs described here **should not** be used on new drivers or applications.

The DVBv3 frontend API has issues with new delivery systems, including
DVB-S2, DVB-T2, ISDB, etc.

.. attention::

   The APIs described here doesn't necessarily reflect the current
   code implementation, as this section of the document was written
   for DVB version 1, while the code reflects DVB version 3
   implementation.

.. toctree::
    :maxdepth: 1

    frontend_legacy_dvbv3_api


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: DTV.net

.. _NET_ADD_IF:

****************
ioctl NET_ADD_IF
****************

Name
====

NET_ADD_IF - Creates a new network interface for a given Packet ID.

Synopsis
========

.. c:macro:: NET_ADD_IF

``int ioctl(int fd, NET_ADD_IF, struct dvb_net_if *net_if)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``net_if``
    pointer to struct :c:type:`dvb_net_if`

Description
===========

The NET_ADD_IF ioctl system call selects the Packet ID (PID) that
contains a TCP/IP traffic, the type of encapsulation to be used (MPE or
ULE) and the interface number for the new interface to be created. When
the system call successfully returns, a new virtual network interface is
created.

The struct :c:type:`dvb_net_if`::ifnum field will be
filled with the number of the created interface.

Return Value
============

On success 0 is returned, and :c:type:`ca_slot_info` is filled.

On error -1 is returned, and the ``errno`` variable is set
appropriately.

The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: DTV.net

.. _NET_GET_IF:

****************
ioctl NET_GET_IF
****************

Name
====

NET_GET_IF - Read the configuration data of an interface created via - :ref:`NET_ADD_IF <net>`.

Synopsis
========

.. c:macro:: NET_GET_IF

``int ioctl(int fd, NET_GET_IF, struct dvb_net_if *net_if)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``net_if``
    pointer to struct :c:type:`dvb_net_if`

Description
===========

The NET_GET_IF ioctl uses the interface number given by the struct
:c:type:`dvb_net_if`::ifnum field and fills the content of
struct :c:type:`dvb_net_if` with the packet ID and
encapsulation type used on such interface. If the interface was not
created yet with :ref:`NET_ADD_IF <net>`, it will return -1 and fill
the ``errno`` with ``EINVAL`` error code.

Return Value
============

On success 0 is returned, and :c:type:`ca_slot_info` is filled.

On error -1 is returned, and the ``errno`` variable is set
appropriately.

The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: DTV.net

.. _NET_REMOVE_IF:

*******************
ioctl NET_REMOVE_IF
*******************

Name
====

NET_REMOVE_IF - Removes a network interface.

Synopsis
========

.. c:macro:: NET_REMOVE_IF

``int ioctl(int fd, NET_REMOVE_IF, int ifnum)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``net_if``
    number of the interface to be removed

Description
===========

The NET_REMOVE_IF ioctl deletes an interface previously created via
:ref:`NET_ADD_IF <net>`.

Return Value
============

On success 0 is returned, and :c:type:`ca_slot_info` is filled.

On error -1 is returned, and the ``errno`` variable is set
appropriately.

The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _net_types:

**************
Net Data Types
**************

.. kernel-doc:: include/uapi/linux/dvb/net.h


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _net:

######################
Digital TV Network API
######################

The Digital TV net device controls the mapping of data packages that are part
of a transport stream to be mapped into a virtual network interface,
visible through the standard Linux network protocol stack.

Currently, two encapsulations are supported:

-  `Multi Protocol Encapsulation (MPE) <http://en.wikipedia.org/wiki/Multiprotocol_Encapsulation>`__

-  `Ultra Lightweight Encapsulation (ULE) <http://en.wikipedia.org/wiki/Unidirectional_Lightweight_Encapsulation>`__

In order to create the Linux virtual network interfaces, an application
needs to tell to the Kernel what are the PIDs and the encapsulation
types that are present on the transport stream. This is done through
``/dev/dvb/adapter?/net?`` device node. The data will be available via
virtual ``dvb?_?`` network interfaces, and will be controlled/routed via
the standard ip tools (like ip, route, netstat, ifconfig, etc).

Data types and ioctl definitions are defined via ``linux/dvb/net.h``
header.

.. _net_fcalls:

Digital TV net Function Calls
#############################

.. toctree::
    :maxdepth: 1

    net-types
    net-add-if
    net-remove-if
    net-get-if


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _query-dvb-frontend-info:

*****************************
Querying frontend information
*****************************

Usually, the first thing to do when the frontend is opened is to check
the frontend capabilities. This is done using
:ref:`FE_GET_INFO`. This ioctl will enumerate the
Digital TV API version and other characteristics about the frontend, and can
be opened either in read only or read/write mode.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _fdl:

******************************
GNU Free Documentation License
******************************

.. _fdl-preamble:

0. PREAMBLE
===========

The purpose of this License is to make a manual, textbook, or other
written document "free" in the sense of freedom: to assure everyone the
effective freedom to copy and redistribute it, with or without modifying
it, either commercially or noncommercially. Secondarily, this License
preserves for the author and publisher a way to get credit for their
work, while not being considered responsible for modifications made by
others.

This License is a kind of "copyleft", which means that derivative works
of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft license
designed for free software.

We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free program
should come with manuals providing the same freedoms that the software
does. But this License is not limited to software manuals; it can be
used for any textual work, regardless of subject matter or whether it is
published as a printed book. We recommend this License principally for
works whose purpose is instruction or reference.

.. _fdl-section1:

1. APPLICABILITY AND DEFINITIONS
================================

.. _fdl-document:

This License applies to any manual or other work that contains a notice
placed by the copyright holder saying it can be distributed under the
terms of this License. The "Document", below, refers to any such manual
or work. Any member of the public is a licensee, and is addressed as
"you".

.. _fdl-modified:

A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.

.. _fdl-secondary:

A "Secondary Section" is a named appendix or a front-matter section of
the :ref:`Document <fdl-document>` that deals exclusively with the
relationship of the publishers or authors of the Document to the
Document's overall subject (or to related matters) and contains nothing
that could fall directly within that overall subject. (For example, if
the Document is in part a textbook of mathematics, a Secondary Section
may not explain any mathematics.) The relationship could be a matter of
historical connection with the subject or with related matters, or of
legal, commercial, philosophical, ethical or political position
regarding them.

.. _fdl-invariant:

The "Invariant Sections" are certain
:ref:`Secondary Sections <fdl-secondary>` whose titles are designated,
as being those of Invariant Sections, in the notice that says that the
:ref:`Document <fdl-document>` is released under this License.

.. _fdl-cover-texts:

The "Cover Texts" are certain short passages of text that are listed, as
Front-Cover Texts or Back-Cover Texts, in the notice that says that the
:ref:`Document <fdl-document>` is released under this License.

.. _fdl-transparent:

A "Transparent" copy of the :ref:`Document <fdl-document>` means a
machine-readable copy, represented in a format whose specification is
available to the general public, whose contents can be viewed and edited
directly and straightforwardly with generic text editors or (for images
composed of pixels) generic paint programs or (for drawings) some widely
available drawing editor, and that is suitable for input to text
formatters or for automatic translation to a variety of formats suitable
for input to text formatters. A copy made in an otherwise Transparent
file format whose markup has been designed to thwart or discourage
subsequent modification by readers is not Transparent. A copy that is
not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII
without markup, Texinfo input format, LaTeX input format, SGML or XML
using a publicly available DTD, and standard-conforming simple HTML
designed for human modification. Opaque formats include PostScript, PDF,
proprietary formats that can be read and edited only by proprietary word
processors, SGML or XML for which the DTD and/or processing tools are
not generally available, and the machine-generated HTML produced by some
word processors for output purposes only.

.. _fdl-title-page:

The "Title Page" means, for a printed book, the title page itself, plus
such following pages as are needed to hold, legibly, the material this
License requires to appear in the title page. For works in formats which
do not have any title page as such, "Title Page" means the text near the
most prominent appearance of the work's title, preceding the beginning
of the body of the text.

.. _fdl-section2:

2. VERBATIM COPYING
===================

You may copy and distribute the :ref:`Document <fdl-document>` in any
medium, either commercially or noncommercially, provided that this
License, the copyright notices, and the license notice saying this
License applies to the Document are reproduced in all copies, and that
you add no other conditions whatsoever to those of this License. You may
not use technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in
:ref:`section 3 <fdl-section3>`.

You may also lend copies, under the same conditions stated above, and
you may publicly display copies.

.. _fdl-section3:

3. COPYING IN QUANTITY
======================

If you publish printed copies of the :ref:`Document <fdl-document>`
numbering more than 100, and the Document's license notice requires
:ref:`Cover Texts <fdl-cover-texts>`, you must enclose the copies in
covers that carry, clearly and legibly, all these Cover Texts:
Front-Cover Texts on the front cover, and Back-Cover Texts on the back
cover. Both covers must also clearly and legibly identify you as the
publisher of these copies. The front cover must present the full title
with all words of the title equally prominent and visible. You may add
other material on the covers in addition. Copying with changes limited
to the covers, as long as they preserve the title of the
:ref:`Document <fdl-document>` and satisfy these conditions, can be
treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.

If you publish or distribute :ref:`Opaque <fdl-transparent>` copies of
the :ref:`Document <fdl-document>` numbering more than 100, you must
either include a machine-readable :ref:`Transparent <fdl-transparent>`
copy along with each Opaque copy, or state in or with each Opaque copy a
publicly-accessible computer-network location containing a complete
Transparent copy of the Document, free of added material, which the
general network-using public has access to download anonymously at no
charge using public-standard network protocols. If you use the latter
option, you must take reasonably prudent steps, when you begin
distribution of Opaque copies in quantity, to ensure that this
Transparent copy will remain thus accessible at the stated location
until at least one year after the last time you distribute an Opaque
copy (directly or through your agents or retailers) of that edition to
the public.

It is requested, but not required, that you contact the authors of the
:ref:`Document <fdl-document>` well before redistributing any large
number of copies, to give them a chance to provide you with an updated
version of the Document.

.. _fdl-section4:

4. MODIFICATIONS
================

You may copy and distribute a :ref:`Modified Version <fdl-modified>`
of the :ref:`Document <fdl-document>` under the conditions of sections
:ref:`2 <fdl-section2>` and :ref:`3 <fdl-section3>` above, provided
that you release the Modified Version under precisely this License, with
the Modified Version filling the role of the Document, thus licensing
distribution and modification of the Modified Version to whoever
possesses a copy of it. In addition, you must do these things in the
Modified Version:

-  **A.**
   Use in the :ref:`Title Page <fdl-title-page>` (and on the covers,
   if any) a title distinct from that of the
   :ref:`Document <fdl-document>`, and from those of previous versions
   (which should, if there were any, be listed in the History section of
   the Document). You may use the same title as a previous version if
   the original publisher of that version gives permission.

-  **B.**
   List on the :ref:`Title Page <fdl-title-page>`, as authors, one or
   more persons or entities responsible for authorship of the
   modifications in the :ref:`Modified Version <fdl-modified>`,
   together with at least five of the principal authors of the
   :ref:`Document <fdl-document>` (all of its principal authors, if it
   has less than five).

-  **C.**
   State on the :ref:`Title Page <fdl-title-page>` the name of the
   publisher of the :ref:`Modified Version <fdl-modified>`, as the
   publisher.

-  **D.**
   Preserve all the copyright notices of the
   :ref:`Document <fdl-document>`.

-  **E.**
   Add an appropriate copyright notice for your modifications adjacent
   to the other copyright notices.

-  **F.**
   Include, immediately after the copyright notices, a license notice
   giving the public permission to use the
   :ref:`Modified Version <fdl-modified>` under the terms of this
   License, in the form shown in the Addendum below.

-  **G.**
   Preserve in that license notice the full lists of
   :ref:`Invariant Sections <fdl-invariant>` and required
   :ref:`Cover Texts <fdl-cover-texts>` given in the
   :ref:`Document's <fdl-document>` license notice.

-  **H.**
   Include an unaltered copy of this License.

-  **I.**
   Preserve the section entitled "History", and its title, and add to it
   an item stating at least the title, year, new authors, and publisher
   of the :ref:`Modified Version <fdl-modified>` as given on the
   :ref:`Title Page <fdl-title-page>`. If there is no section entitled
   "History" in the :ref:`Document <fdl-document>`, create one stating
   the title, year, authors, and publisher of the Document as given on
   its Title Page, then add an item describing the Modified Version as
   stated in the previous sentence.

-  **J.**
   Preserve the network location, if any, given in the
   :ref:`Document <fdl-document>` for public access to a
   :ref:`Transparent <fdl-transparent>` copy of the Document, and
   likewise the network locations given in the Document for previous
   versions it was based on. These may be placed in the "History"
   section. You may omit a network location for a work that was
   published at least four years before the Document itself, or if the
   original publisher of the version it refers to gives permission.

-  **K.**
   In any section entitled "Acknowledgements" or "Dedications", preserve
   the section's title, and preserve in the section all the substance
   and tone of each of the contributor acknowledgements and/or
   dedications given therein.

-  **L.**
   Preserve all the :ref:`Invariant Sections <fdl-invariant>` of the
   :ref:`Document <fdl-document>`, unaltered in their text and in
   their titles. Section numbers or the equivalent are not considered
   part of the section titles.

-  **M.**
   Delete any section entitled "Endorsements". Such a section may not be
   included in the :ref:`Modified Version <fdl-modified>`.

-  **N.**
   Do not retitle any existing section as "Endorsements" or to conflict
   in title with any :ref:`Invariant Section <fdl-invariant>`.

If the :ref:`Modified Version <fdl-modified>` includes new
front-matter sections or appendices that qualify as
:ref:`Secondary Sections <fdl-secondary>` and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the list
of :ref:`Invariant Sections <fdl-invariant>` in the Modified Version's
license notice. These titles must be distinct from any other section
titles.

You may add a section entitled "Endorsements", provided it contains
nothing but endorsements of your
:ref:`Modified Version <fdl-modified>` by various parties--for
example, statements of peer review or that the text has been approved by
an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a
:ref:`Front-Cover Text <fdl-cover-texts>`, and a passage of up to 25
words as a :ref:`Back-Cover Text <fdl-cover-texts>`, to the end of the
list of :ref:`Cover Texts <fdl-cover-texts>` in the
:ref:`Modified Version <fdl-modified>`. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or through
arrangements made by) any one entity. If the
:ref:`Document <fdl-document>` already includes a cover text for the
same cover, previously added by you or by arrangement made by the same
entity you are acting on behalf of, you may not add another; but you may
replace the old one, on explicit permission from the previous publisher
that added the old one.

The author(s) and publisher(s) of the :ref:`Document <fdl-document>`
do not by this License give permission to use their names for publicity
for or to assert or imply endorsement of any
:ref:`Modified Version <fdl-modified>`.

.. _fdl-section5:

5. COMBINING DOCUMENTS
======================

You may combine the :ref:`Document <fdl-document>` with other
documents released under this License, under the terms defined in
:ref:`section 4 <fdl-section4>` above for modified versions, provided
that you include in the combination all of the
:ref:`Invariant Sections <fdl-invariant>` of all of the original
documents, unmodified, and list them all as Invariant Sections of your
combined work in its license notice.

The combined work need only contain one copy of this License, and
multiple identical :ref:`Invariant Sections <fdl-invariant>` may be
replaced with a single copy. If there are multiple Invariant Sections
with the same name but different contents, make the title of each such
section unique by adding at the end of it, in parentheses, the name of
the original author or publisher of that section if known, or else a
unique number. Make the same adjustment to the section titles in the
list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections entitled "History" in
the various original documents, forming one section entitled "History";
likewise combine any sections entitled "Acknowledgements", and any
sections entitled "Dedications". You must delete all sections entitled
"Endorsements."

.. _fdl-section6:

6. COLLECTIONS OF DOCUMENTS
===========================

You may make a collection consisting of the
:ref:`Document <fdl-document>` and other documents released under this
License, and replace the individual copies of this License in the
various documents with a single copy that is included in the collection,
provided that you follow the rules of this License for verbatim copying
of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.

.. _fdl-section7:

7. AGGREGATION WITH INDEPENDENT WORKS
=====================================

A compilation of the :ref:`Document <fdl-document>` or its derivatives
with other separate and independent documents or works, in or on a
volume of a storage or distribution medium, does not as a whole count as
a :ref:`Modified Version <fdl-modified>` of the Document, provided no
compilation copyright is claimed for the compilation. Such a compilation
is called an "aggregate", and this License does not apply to the other
self-contained works thus compiled with the Document , on account of
their being thus compiled, if they are not themselves derivative works
of the Document. If the :ref:`Cover Text <fdl-cover-texts>`
requirement of :ref:`section 3 <fdl-section3>` is applicable to these
copies of the Document, then if the Document is less than one quarter of
the entire aggregate, the Document's Cover Texts may be placed on covers
that surround only the Document within the aggregate. Otherwise they
must appear on covers around the whole aggregate.

.. _fdl-section8:

8. TRANSLATION
==============

Translation is considered a kind of modification, so you may distribute
translations of the :ref:`Document <fdl-document>` under the terms of
:ref:`section 4 <fdl-section4>`. Replacing
:ref:`Invariant Sections <fdl-invariant>` with translations requires
special permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License provided that you also include the original
English version of this License. In case of a disagreement between the
translation and the original English version of this License, the
original English version will prevail.

.. _fdl-section9:

9. TERMINATION
==============

You may not copy, modify, sublicense, or distribute the
:ref:`Document <fdl-document>` except as expressly provided for under
this License. Any other attempt to copy, modify, sublicense or
distribute the Document is void, and will automatically terminate your
rights under this License. However, parties who have received copies, or
rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.

.. _fdl-section10:

10. FUTURE REVISIONS OF THIS LICENSE
====================================

The `Free Software Foundation <http://www.gnu.org/fsf/fsf.html>`__
may publish new, revised versions of the GNU Free Documentation License
from time to time. Such new versions will be similar in spirit to the
present version, but may differ in detail to address new problems or
concerns. See
`http://www.gnu.org/copyleft/ <http://www.gnu.org/copyleft>`__.

Each version of the License is given a distinguishing version number. If
the :ref:`Document <fdl-document>` specifies that a particular
numbered version of this License "or any later version" applies to it,
you have the option of following the terms and conditions either of that
specified version or of any later version that has been published (not
as a draft) by the Free Software Foundation. If the Document does not
specify a version number of this License, you may choose any version
ever published (not as a draft) by the Free Software Foundation.

.. _fdl-using:

Addendum
========

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

    Copyright © YEAR YOUR NAME.

    Permission is granted to copy, distribute and/or modify this
    document under the terms of the GNU Free Documentation License,
    Version 1.1 or any later version published by the Free Software
    Foundation; with the :ref:`Invariant Sections <fdl-invariant>`
    being LIST THEIR TITLES, with the
    :ref:`Front-Cover Texts <fdl-cover-texts>` being LIST, and with
    the :ref:`Back-Cover Texts <fdl-cover-texts>` being LIST. A copy
    of the license is included in the section entitled "GNU Free
    Documentation License".

If you have no :ref:`Invariant Sections <fdl-invariant>`, write "with
no Invariant Sections" instead of saying which ones are invariant. If
you have no :ref:`Front-Cover Texts <fdl-cover-texts>`, write "no
Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise
for :ref:`Back-Cover Texts <fdl-cover-texts>`.

If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of free
software license, such as the
`GNU General Public License <http://www.gnu.org/copyleft/gpl.html>`__,
to permit their use in free software.


code:
# SPDX-License-Identifier: GPL-2.0

# Ignore header name
ignore define _DVBFRONTEND_H_

# Group layer A-C symbols together
replace define DTV_ISDBT_LAYERA_FEC dtv-isdbt-layer-fec
replace define DTV_ISDBT_LAYERB_FEC dtv-isdbt-layer-fec
replace define DTV_ISDBT_LAYERC_FEC dtv-isdbt-layer-fec
replace define DTV_ISDBT_LAYERA_MODULATION dtv-isdbt-layer-modulation
replace define DTV_ISDBT_LAYERB_MODULATION dtv-isdbt-layer-modulation
replace define DTV_ISDBT_LAYERC_MODULATION dtv-isdbt-layer-modulation
replace define DTV_ISDBT_LAYERA_SEGMENT_COUNT dtv-isdbt-layer-segment-count
replace define DTV_ISDBT_LAYERB_SEGMENT_COUNT dtv-isdbt-layer-segment-count
replace define DTV_ISDBT_LAYERC_SEGMENT_COUNT dtv-isdbt-layer-segment-count
replace define DTV_ISDBT_LAYERA_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving
replace define DTV_ISDBT_LAYERB_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving
replace define DTV_ISDBT_LAYERC_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving

# Ignore legacy defines
ignore define DTV_ISDBS_TS_ID_LEGACY
ignore define SYS_DVBC_ANNEX_AC
ignore define SYS_DMBTH

# Ignore limits
ignore define DTV_MAX_COMMAND
ignore define MAX_DTV_STATS
ignore define DTV_IOCTL_MAX_MSGS

# the same reference is used for both get and set ioctls
replace ioctl FE_SET_PROPERTY :c:type:`FE_GET_PROPERTY`

# Typedefs that use the enum reference
replace typedef fe_sec_voltage_t :c:type:`fe_sec_voltage`

# Replaces for flag constants
replace define FE_TUNE_MODE_ONESHOT :c:func:`FE_SET_FRONTEND_TUNE_MODE`
replace define LNA_AUTO dtv-lna
replace define NO_STREAM_ID_FILTER dtv-stream-id

# Those enums are defined at the frontend.h header, and not externally

ignore symbol FE_IS_STUPID
ignore symbol FE_CAN_INVERSION_AUTO
ignore symbol FE_CAN_FEC_1_2
ignore symbol FE_CAN_FEC_2_3
ignore symbol FE_CAN_FEC_3_4
ignore symbol FE_CAN_FEC_4_5
ignore symbol FE_CAN_FEC_5_6
ignore symbol FE_CAN_FEC_6_7
ignore symbol FE_CAN_FEC_7_8
ignore symbol FE_CAN_FEC_8_9
ignore symbol FE_CAN_FEC_AUTO
ignore symbol FE_CAN_QPSK
ignore symbol FE_CAN_QAM_16
ignore symbol FE_CAN_QAM_32
ignore symbol FE_CAN_QAM_64
ignore symbol FE_CAN_QAM_128
ignore symbol FE_CAN_QAM_256
ignore symbol FE_CAN_QAM_AUTO
ignore symbol FE_CAN_TRANSMISSION_MODE_AUTO
ignore symbol FE_CAN_BANDWIDTH_AUTO
ignore symbol FE_CAN_GUARD_INTERVAL_AUTO
ignore symbol FE_CAN_HIERARCHY_AUTO
ignore symbol FE_CAN_8VSB
ignore symbol FE_CAN_16VSB
ignore symbol FE_HAS_EXTENDED_CAPS
ignore symbol FE_CAN_MULTISTREAM
ignore symbol FE_CAN_TURBO_FEC
ignore symbol FE_CAN_2G_MODULATION
ignore symbol FE_NEEDS_BENDING
ignore symbol FE_CAN_RECOVER
ignore symbol FE_CAN_MUTE_TS

ignore symbol QPSK
ignore symbol QAM_16
ignore symbol QAM_32
ignore symbol QAM_64
ignore symbol QAM_128
ignore symbol QAM_256
ignore symbol QAM_AUTO
ignore symbol VSB_8
ignore symbol VSB_16
ignore symbol PSK_8
ignore symbol APSK_16
ignore symbol APSK_32
ignore symbol DQPSK
ignore symbol QAM_4_NR
ignore symbol QAM_1024
ignore symbol QAM_4096
ignore symbol APSK_8_L
ignore symbol APSK_16_L
ignore symbol APSK_32_L
ignore symbol APSK_64
ignore symbol APSK_64_L

ignore symbol SEC_VOLTAGE_13
ignore symbol SEC_VOLTAGE_18
ignore symbol SEC_VOLTAGE_OFF

ignore symbol SEC_TONE_ON
ignore symbol SEC_TONE_OFF

ignore symbol SEC_MINI_A
ignore symbol SEC_MINI_B

ignore symbol FE_NONE
ignore symbol FE_HAS_SIGNAL
ignore symbol FE_HAS_CARRIER
ignore symbol FE_HAS_VITERBI
ignore symbol FE_HAS_SYNC
ignore symbol FE_HAS_LOCK
ignore symbol FE_REINIT
ignore symbol FE_TIMEDOUT

ignore symbol FEC_NONE
ignore symbol FEC_1_2
ignore symbol FEC_2_3
ignore symbol FEC_3_4
ignore symbol FEC_4_5
ignore symbol FEC_5_6
ignore symbol FEC_6_7
ignore symbol FEC_7_8
ignore symbol FEC_8_9
ignore symbol FEC_AUTO
ignore symbol FEC_3_5
ignore symbol FEC_9_10
ignore symbol FEC_2_5
ignore symbol FEC_1_3
ignore symbol FEC_1_4
ignore symbol FEC_5_9
ignore symbol FEC_7_9
ignore symbol FEC_8_15
ignore symbol FEC_11_15
ignore symbol FEC_13_18
ignore symbol FEC_9_20
ignore symbol FEC_11_20
ignore symbol FEC_23_36
ignore symbol FEC_25_36
ignore symbol FEC_13_45
ignore symbol FEC_26_45
ignore symbol FEC_28_45
ignore symbol FEC_32_45
ignore symbol FEC_77_90

ignore symbol TRANSMISSION_MODE_AUTO
ignore symbol TRANSMISSION_MODE_1K
ignore symbol TRANSMISSION_MODE_2K
ignore symbol TRANSMISSION_MODE_8K
ignore symbol TRANSMISSION_MODE_4K
ignore symbol TRANSMISSION_MODE_16K
ignore symbol TRANSMISSION_MODE_32K
ignore symbol TRANSMISSION_MODE_C1
ignore symbol TRANSMISSION_MODE_C3780
ignore symbol TRANSMISSION_MODE_2K
ignore symbol TRANSMISSION_MODE_8K

ignore symbol GUARD_INTERVAL_AUTO
ignore symbol GUARD_INTERVAL_1_128
ignore symbol GUARD_INTERVAL_1_32
ignore symbol GUARD_INTERVAL_1_16
ignore symbol GUARD_INTERVAL_1_8
ignore symbol GUARD_INTERVAL_1_4
ignore symbol GUARD_INTERVAL_19_128
ignore symbol GUARD_INTERVAL_19_256
ignore symbol GUARD_INTERVAL_PN420
ignore symbol GUARD_INTERVAL_PN595
ignore symbol GUARD_INTERVAL_PN945
ignore symbol GUARD_INTERVAL_1_64

ignore symbol HIERARCHY_NONE
ignore symbol HIERARCHY_AUTO
ignore symbol HIERARCHY_1
ignore symbol HIERARCHY_2
ignore symbol HIERARCHY_4

ignore symbol INTERLEAVING_NONE
ignore symbol INTERLEAVING_AUTO
ignore symbol INTERLEAVING_240
ignore symbol INTERLEAVING_720

ignore symbol PILOT_ON
ignore symbol PILOT_OFF
ignore symbol PILOT_AUTO

ignore symbol ROLLOFF_35
ignore symbol ROLLOFF_20
ignore symbol ROLLOFF_25
ignore symbol ROLLOFF_AUTO
ignore symbol ROLLOFF_15
ignore symbol ROLLOFF_10
ignore symbol ROLLOFF_5

ignore symbol INVERSION_ON
ignore symbol INVERSION_OFF
ignore symbol INVERSION_AUTO

ignore symbol SYS_UNDEFINED
ignore symbol SYS_DVBC_ANNEX_A
ignore symbol SYS_DVBC_ANNEX_B
ignore symbol SYS_DVBC_ANNEX_C
ignore symbol SYS_ISDBC
ignore symbol SYS_DVBT
ignore symbol SYS_DVBT2
ignore symbol SYS_ISDBT
ignore symbol SYS_ATSC
ignore symbol SYS_ATSCMH
ignore symbol SYS_DTMB
ignore symbol SYS_DVBS
ignore symbol SYS_DVBS2
ignore symbol SYS_TURBO
ignore symbol SYS_ISDBS
ignore symbol SYS_DAB
ignore symbol SYS_DSS
ignore symbol SYS_CMMB
ignore symbol SYS_DVBH
ignore symbol SYS_DVBC2

ignore symbol ATSCMH_SCCC_BLK_SEP
ignore symbol ATSCMH_SCCC_BLK_COMB
ignore symbol ATSCMH_SCCC_BLK_RES

ignore symbol ATSCMH_SCCC_CODE_HLF
ignore symbol ATSCMH_SCCC_CODE_QTR
ignore symbol ATSCMH_SCCC_CODE_RES

ignore symbol ATSCMH_RSFRAME_ENS_PRI
ignore symbol ATSCMH_RSFRAME_ENS_SEC

ignore symbol ATSCMH_RSFRAME_PRI_ONLY
ignore symbol ATSCMH_RSFRAME_PRI_SEC
ignore symbol ATSCMH_RSFRAME_RES

ignore symbol ATSCMH_RSCODE_211_187
ignore symbol ATSCMH_RSCODE_223_187
ignore symbol ATSCMH_RSCODE_235_187
ignore symbol ATSCMH_RSCODE_RES

ignore symbol FE_SCALE_NOT_AVAILABLE
ignore symbol FE_SCALE_DECIBEL
ignore symbol FE_SCALE_RELATIVE
ignore symbol FE_SCALE_COUNTER


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _gen_errors:

*******************
Generic Error Codes
*******************

.. _gen-errors:

.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|

.. flat-table:: Generic error codes
    :header-rows:  0
    :stub-columns: 0
    :widths: 1 16

    -  -  ``EAGAIN`` (aka ``EWOULDBLOCK``)

       -  The ioctl can't be handled because the device is in state where it
	  can't perform it. This could happen for example in case where
	  device is sleeping and ioctl is performed to query statistics. It
	  is also returned when the ioctl would need to wait for an event,
	  but the device was opened in non-blocking mode.

    -  -  ``EBADF``

       -  The file descriptor is not a valid.

    -  -  ``EBUSY``

       -  The ioctl can't be handled because the device is busy. This is
	  typically return while device is streaming, and an ioctl tried to
	  change something that would affect the stream, or would require
	  the usage of a hardware resource that was already allocated. The
	  ioctl must not be retried without performing another action to fix
	  the problem first (typically: stop the stream before retrying).

    -  -  ``EFAULT``

       -  There was a failure while copying data from/to userspace, probably
	  caused by an invalid pointer reference.

    -  -  ``EINVAL``

       -  One or more of the ioctl parameters are invalid or out of the
	  allowed range. This is a widely used error code. See the
	  individual ioctl requests for specific causes.

    -  -  ``ENODEV``

       -  Device not found or was removed.

    -  -  ``ENOMEM``

       -  There's not enough memory to handle the desired operation.

    -  -  ``ENOTTY``

       -  The ioctl is not supported by the driver, actually meaning that
	  the required functionality is not available, or the file
	  descriptor is not for a media device.

    -  -  ``ENOSPC``

       -  On USB devices, the stream ioctl's can return this error, meaning
	  that this request would overcommit the usb bandwidth reserved for
	  periodic transfers (up to 80% of the USB bandwidth).

    -  -  ``EPERM``

       -  Permission denied. Can be returned if the device needs write
	  permission, or some special capabilities is needed (e. g. root)

    -  -  ``EIO``

       -  I/O error. Typically used when there are problems communicating with
          a hardware device. This could indicate broken or flaky hardware.
	  It's a 'Something is wrong, I give up!' type of error.

    -  - ``ENXIO``

       -  No device corresponding to this device special file exists.

.. note::

  #. This list is not exhaustive; ioctls may return other error codes.
     Since errors may have side effects such as a driver reset,
     applications should abort on unexpected errors, or otherwise
     assume that the device is in a bad state.

  #. Request-specific error codes are listed in the individual
     requests descriptions.


code:
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later

========
Glossary
========

.. note::

   The goal of this section is to standardize the terms used within the media
   userspace API documentation. This is Work In Progress.

.. Please keep the glossary entries in alphabetical order

.. glossary::

    Bridge Driver
	A :term:`Device Driver` that implements the main logic to talk with
	media hardware.

    CEC API
	**Consumer Electronics Control API**

	An API designed to receive and transmit data via an HDMI
	CEC interface.

	See :ref:`cec`.

    Device Driver
	Part of the Linux Kernel that implements support for a hardware
	component.

    Device Node
	A character device node in the file system used to control and
	transfer data in and out of a Kernel driver.

    Digital TV API
	**Previously known as DVB API**

	An API designed to control a subset of the :term:`Media Hardware`
	that implements	digital TV (e. g. DVB, ATSC, ISDB, etc).

	See :ref:`dvbapi`.

    DSP
        **Digital Signal Processor**

	A specialized :term:`Microprocessor`, with its architecture
	optimized for the operational needs of digital signal processing.

    FPGA
	**Field-programmable Gate Array**

	An :term:`IC` circuit designed to be configured by a customer or
	a designer after manufacturing.

	See https://en.wikipedia.org/wiki/Field-programmable_gate_array.

    Hardware Component
	A subset of the :term:`Media Hardware`. For example an :term:`I²C` or
	:term:`SPI` device, or an :term:`IP Block` inside an
	:term:`SoC` or :term:`FPGA`.

    Hardware Peripheral
	A group of :term:`hardware components <Hardware Component>` that
	together make a larger user-facing functional peripheral. For
	instance, the :term:`SoC` :term:`ISP` :term:`IP Block`
	and the external camera sensors together make a camera hardware
	peripheral.

	Also known as :term:`Peripheral`.

    I²C
	**Inter-Integrated Circuit**

	A  multi-master, multi-slave, packet switched, single-ended,
	serial computer bus used to control some hardware components
	like sub-device hardware components.

	See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.

    IC
	**Integrated circuit**

	A set of electronic circuits on one small flat piece of
	semiconductor material, normally silicon.

	Also known as chip.

    IP Block
	**Intellectual property core**

	In electronic design a semiconductor intellectual property core,
	is a reusable unit of logic, cell, or integrated circuit layout
	design that is the intellectual property of one party.
	IP Blocks may be licensed to another party or can be owned
	and used by a single party alone.

	See https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core).

    ISP
	**Image Signal Processor**

	A specialized processor that implements a set of algorithms for
	processing image data. ISPs may implement algorithms for lens
	shading correction, demosaicing, scaling and pixel format conversion
	as well as produce statistics for the use of the control
	algorithms (e.g. automatic exposure, white balance and focus).

    Media API
	A set of userspace APIs used to control the media hardware. It is
	composed by:

	  - :term:`CEC API`;
	  - :term:`Digital TV API`;
	  - :term:`MC API`;
	  - :term:`RC API`; and
	  - :term:`V4L2 API`.

	See Documentation/userspace-api/media/index.rst.

    MC API
	**Media Controller API**

	An API designed to expose and control the relationships between
	multimedia devices and sub-devices.

	See :ref:`media_controller`.

    MC-centric
	:term:`V4L2 Hardware` device driver that requires :term:`MC API`.

	Such drivers have ``V4L2_CAP_IO_MC`` device_caps field set
	(see :ref:`VIDIOC_QUERYCAP`).

	See :ref:`v4l2_hardware_control` for more details.

    Media Hardware
	Subset of the hardware that is supported by the Linux Media API.

	This includes audio and video capture and playback hardware,
	digital and analog TV, camera sensors, ISPs, remote controllers,
	codecs, HDMI Consumer Electronics Control, HDMI capture, etc.

    Microprocessor
	Electronic circuitry that carries out the instructions of a
	computer program by performing the basic arithmetic, logical,
	control and input/output (I/O) operations specified by the
	instructions on a single integrated circuit.

    Peripheral
	The same as :term:`Hardware Peripheral`.

    RC API
	**Remote Controller API**

	An API designed to receive and transmit data from remote
	controllers.

	See :ref:`remote_controllers`.

    SMBus
	A subset of I²C, which defines a stricter usage of the bus.

    SPI
	**Serial Peripheral Interface Bus**

	Synchronous serial communication interface specification used for
	short distance communication, primarily in embedded systems.

    SoC
	**System on a Chip**

	An integrated circuit that integrates all components of a computer
	or other electronic systems.

    V4L2 API
	**V4L2 userspace API**

	The userspace API defined in :ref:`v4l2spec`, which is used to
	control a V4L2 hardware.

    V4L2 Device Node
	A :term:`Device Node` that is associated to a V4L driver.

	The V4L2 device node naming is specified at :ref:`v4l2_device_naming`.

    V4L2 Hardware
	Part of the media hardware which is supported by the :term:`V4L2 API`.

    V4L2 Sub-device
	V4L2 hardware components that aren't controlled by a
	:term:`Bridge Driver`. See :ref:`subdev`.

    Video-node-centric
	V4L2 device driver that doesn't require a media controller to be used.

	Such drivers have the ``V4L2_CAP_IO_MC`` device_caps field unset
	(see :ref:`VIDIOC_QUERYCAP`).

    V4L2 Sub-device API
	Part of the :term:`V4L2 API` which control
	:term:`V4L2 sub-devices <V4L2 Sub-device>`, like sensors,
	HDMI receivers, scalers, deinterlacers.

	See :ref:`v4l2_hardware_control` for more details.


code:
.. SPDX-License-Identifier: GPL-2.0

.. include:: <isonum.txt>

########################################
Linux Media Infrastructure userspace API
########################################

This section contains the  driver development information and Kernel APIs
used by media devices.

Please see:

Documentation/admin-guide/media/index.rst

  - for usage information about media subsystem and supported drivers;

Documentation/driver-api/media/index.rst

  - for driver development information and Kernel APIs used by
    media devices;

.. only:: html

   .. class:: toc-title

        Table of Contents

.. toctree::
    :maxdepth: 1

    intro
    v4l/v4l2
    dvb/dvbapi
    rc/remote_controllers
    mediactl/media-controller
    cec/cec-api
    gen-errors

    glossary

    fdl-appendix

    drivers/index

**Copyright** |copy| 2009-2020 : LinuxTV Developers

::

  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.1 or
  any later version published by the Free Software Foundation, with no
  Invariant Sections. A copy of the license is included in the chapter
  entitled "GNU Free Documentation License".

Please notice that some documents inside the media userspace API,
when explicitly mentioned on its source code, are dual-licensed
with GNU Free Documentation License  Version 1.1 and with the
GNU General Public License::

  This documentation is free software; you can redistribute it and/or modify it
  under the terms of the GNU General Public License as published by the Free
  Software Foundation; either version 2 of the License, or (at your option) any
  later version.

  This program is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
  more details.

  For more details see the file COPYING in the source distribution of Linux.


code:
.. SPDX-License-Identifier: GPL-2.0

============
Introduction
============

This document covers the Linux Kernel to Userspace API's used by video
and radio streaming devices, including video cameras, analog and digital
TV receiver cards, AM/FM receiver cards, Software Defined Radio (SDR),
streaming capture and output devices, codec devices and remote controllers.

A typical media device hardware is shown at :ref:`typical_media_device`.

.. _typical_media_device:

.. kernel-figure:: typical_media_device.svg
    :alt:   typical_media_device.svg
    :align: center

    Typical Media Device

The media infrastructure API was designed to control such devices. It is
divided into five parts.

1. The :ref:`first part <v4l2spec>` covers radio, video capture and output,
   cameras, analog TV devices and codecs.

2. The :ref:`second part <dvbapi>` covers the API used for digital TV and
   Internet reception via one of the several digital tv standards. While it is
   called as DVB API, in fact it covers several different video standards
   including DVB-T/T2, DVB-S/S2, DVB-C, ATSC, ISDB-T, ISDB-S, DTMB, etc. The
   complete list of supported standards can be found at
   :c:type:`fe_delivery_system`.

3. The :ref:`third part <remote_controllers>` covers the Remote Controller API.

4. The :ref:`fourth part <media_controller>` covers the Media Controller API.

5. The :ref:`fifth part <cec>` covers the CEC (Consumer Electronics Control) API.

It should also be noted that a media device may also have audio components, like
mixers, PCM capture, PCM playback, etc, which are controlled via ALSA API.  For
additional information and for the latest development code, see:
`https://linuxtv.org <https://linuxtv.org>`__.  For discussing improvements,
reporting troubles, sending new drivers, etc, please mail to: `Linux Media
Mailing List (LMML) <http://vger.kernel.org/vger-lists.html#linux-media>`__.


code:
# SPDX-License-Identifier: GPL-2.0

# Ignore header name
ignore define _LINUX_LIRC_H

# Ignore helper macros

ignore define lirc_t

ignore define LIRC_SPACE
ignore define LIRC_PULSE
ignore define LIRC_FREQUENCY
ignore define LIRC_TIMEOUT
ignore define LIRC_OVERFLOW
ignore define LIRC_VALUE
ignore define LIRC_MODE2
ignore define LIRC_IS_SPACE
ignore define LIRC_IS_PULSE
ignore define LIRC_IS_FREQUENCY
ignore define LIRC_IS_TIMEOUT
ignore define LIRC_IS_OVERFLOW

ignore define LIRC_MODE2SEND
ignore define LIRC_SEND2MODE
ignore define LIRC_MODE2REC
ignore define LIRC_REC2MODE

ignore define LIRC_CAN_SEND
ignore define LIRC_CAN_REC

ignore define LIRC_CAN_SEND_MASK
ignore define LIRC_CAN_REC_MASK
ignore define LIRC_CAN_SET_REC_FILTER
ignore define LIRC_CAN_NOTIFY_DECODE

# Obsolete ioctls

ignore ioctl LIRC_GET_LENGTH
ignore ioctl LIRC_SET_REC_TIMEOUT_REPORTS

# rc protocols

ignore symbol RC_PROTO_UNKNOWN
ignore symbol RC_PROTO_OTHER
ignore symbol RC_PROTO_RC5
ignore symbol RC_PROTO_RC5X_20
ignore symbol RC_PROTO_RC5_SZ
ignore symbol RC_PROTO_JVC
ignore symbol RC_PROTO_SONY12
ignore symbol RC_PROTO_SONY15
ignore symbol RC_PROTO_SONY20
ignore symbol RC_PROTO_NEC
ignore symbol RC_PROTO_NECX
ignore symbol RC_PROTO_NEC32
ignore symbol RC_PROTO_SANYO
ignore symbol RC_PROTO_MCIR2_KBD
ignore symbol RC_PROTO_MCIR2_MSE
ignore symbol RC_PROTO_RC6_0
ignore symbol RC_PROTO_RC6_6A_20
ignore symbol RC_PROTO_RC6_6A_24
ignore symbol RC_PROTO_RC6_6A_32
ignore symbol RC_PROTO_RC6_MCE
ignore symbol RC_PROTO_SHARP
ignore symbol RC_PROTO_XMP
ignore symbol RC_PROTO_CEC
ignore symbol RC_PROTO_IMON
ignore symbol RC_PROTO_RCMM12
ignore symbol RC_PROTO_RCMM24
ignore symbol RC_PROTO_RCMM32
ignore symbol RC_PROTO_XBOX_DVD
ignore symbol RC_PROTO_MAX

# Undocumented macros

ignore define PULSE_BIT
ignore define PULSE_MASK

ignore define LIRC_MODE2_SPACE
ignore define LIRC_MODE2_PULSE
ignore define LIRC_MODE2_TIMEOUT
ignore define LIRC_MODE2_OVERFLOW

ignore define LIRC_VALUE_MASK
ignore define LIRC_MODE2_MASK

ignore define LIRC_MODE_RAW
ignore define LIRC_MODE_LIRCCODE


code:
# SPDX-License-Identifier: GPL-2.0

# Ignore header name
ignore define __LINUX_MEDIA_H

# Ignore macros
ignore define MEDIA_API_VERSION
ignore define MEDIA_ENT_F_BASE
ignore define MEDIA_ENT_F_OLD_BASE
ignore define MEDIA_ENT_F_OLD_SUBDEV_BASE
ignore define MEDIA_ENT_F_DTV_DECODER
ignore define MEDIA_INTF_T_DVB_BASE
ignore define MEDIA_INTF_T_V4L_BASE
ignore define MEDIA_INTF_T_ALSA_BASE
#ignore legacy entity type macros
ignore define MEDIA_ENT_TYPE_SHIFT
ignore define MEDIA_ENT_TYPE_MASK
ignore define MEDIA_ENT_SUBTYPE_MASK
ignore define MEDIA_ENT_T_DEVNODE_UNKNOWN
ignore define MEDIA_ENT_T_DEVNODE
ignore define MEDIA_ENT_T_DEVNODE_V4L
ignore define MEDIA_ENT_T_DEVNODE_FB
ignore define MEDIA_ENT_T_DEVNODE_ALSA
ignore define MEDIA_ENT_T_DEVNODE_DVB
ignore define MEDIA_ENT_T_UNKNOWN
ignore define MEDIA_ENT_T_V4L2_VIDEO
ignore define MEDIA_ENT_T_V4L2_SUBDEV
ignore define MEDIA_ENT_T_V4L2_SUBDEV_SENSOR
ignore define MEDIA_ENT_T_V4L2_SUBDEV_FLASH
ignore define MEDIA_ENT_T_V4L2_SUBDEV_LENS
ignore define MEDIA_ENT_T_V4L2_SUBDEV_DECODER
ignore define MEDIA_ENT_T_V4L2_SUBDEV_TUNER


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _media-controller-intro:

Introduction
============

Media devices increasingly handle multiple related functions. Many USB
cameras include microphones, video capture hardware can also output
video, or SoC camera interfaces also perform memory-to-memory operations
similar to video codecs.

Independent functions, even when implemented in the same hardware, can
be modelled as separate devices. A USB camera with a microphone will be
presented to userspace applications as V4L2 and ALSA capture devices.
The devices' relationships (when using a webcam, end-users shouldn't
have to manually select the associated USB microphone), while not made
available directly to applications by the drivers, can usually be
retrieved from sysfs.

With more and more advanced SoC devices being introduced, the current
approach will not scale. Device topologies are getting increasingly
complex and can't always be represented by a tree structure. Hardware
blocks are shared between different functions, creating dependencies
between seemingly unrelated devices.

Kernel abstraction APIs such as V4L2 and ALSA provide means for
applications to access hardware parameters. As newer hardware expose an
increasingly high number of those parameters, drivers need to guess what
applications really require based on limited information, thereby
implementing policies that belong to userspace.

The media controller API aims at solving those problems.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _media-controller-model:

Media device model
==================

Discovering a device internal topology, and configuring it at runtime,
is one of the goals of the media controller API. To achieve this,
hardware devices and Linux Kernel interfaces are modelled as graph
objects on an oriented graph. The object types that constitute the graph
are:

-  An **entity** is a basic media hardware or software building block.
   It can correspond to a large variety of logical blocks such as
   physical hardware devices (CMOS sensor for instance), logical
   hardware devices (a building block in a System-on-Chip image
   processing pipeline), DMA channels or physical connectors.

-  An **interface** is a graph representation of a Linux Kernel
   userspace API interface, like a device node or a sysfs file that
   controls one or more entities in the graph.

-  A **pad** is a data connection endpoint through which an entity can
   interact with other entities. Data (not restricted to video) produced
   by an entity flows from the entity's output to one or more entity
   inputs. Pads should not be confused with physical pins at chip
   boundaries.

-  A **data link** is a point-to-point oriented connection between two
   pads, either on the same entity or on different entities. Data flows
   from a source pad to a sink pad.

-  An **interface link** is a point-to-point bidirectional control
   connection between a Linux Kernel interface and an entity.

- An **ancillary link** is a point-to-point connection denoting that two
  entities form a single logical unit. For example this could represent the
  fact that a particular camera sensor and lens controller form a single
  physical module, meaning this lens controller drives the lens for this
  camera sensor.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. include:: <isonum.txt>

.. _media_controller:

##############################
Part IV - Media Controller API
##############################

.. only:: html

   .. class:: toc-title

        Table of Contents

.. toctree::
    :maxdepth: 5
    :numbered:

    media-controller-intro
    media-controller-model
    media-types
    request-api
    media-funcs
    media-header

**********************
Revision and Copyright
**********************

Authors:

- Pinchart, Laurent <laurent.pinchart@ideasonboard.com>

 - Initial version.

- Carvalho Chehab, Mauro <mchehab@kernel.org>

 - MEDIA_IOC_G_TOPOLOGY documentation and documentation improvements.

**Copyright** |copy| 2010 : Laurent Pinchart

**Copyright** |copy| 2015-2016 : Mauro Carvalho Chehab

****************
Revision History
****************

:revision: 1.1.0 / 2015-12-12 (*mcc*)

:revision: 1.0.0 / 2010-11-10 (*lp*)

Initial revision


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC

.. _media-func-close:

*************
media close()
*************

Name
====

media-close - Close a media device

Synopsis
========

.. code-block:: c

    #include <unistd.h>

.. c:function:: int close( int fd )

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

Description
===========

Closes the media device. Resources associated with the file descriptor
are freed. The device configuration remain unchanged.

Return Value
============

:c:func:`close()` returns 0 on success. On error, -1 is returned, and
``errno`` is set appropriately. Possible error codes are:

EBADF
    ``fd`` is not a valid open file descriptor.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC

.. _media-func-ioctl:

*************
media ioctl()
*************

Name
====

media-ioctl - Control a media device

Synopsis
========

.. code-block:: c

    #include <sys/ioctl.h>

``int ioctl(int fd, int request, void *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``request``
    Media ioctl request code as defined in the media.h header file, for
    example MEDIA_IOC_SETUP_LINK.

``argp``
    Pointer to a request-specific structure.

Description
===========

The :ref:`ioctl() <media-func-ioctl>` function manipulates media device
parameters. The argument ``fd`` must be an open file descriptor.

The ioctl ``request`` code specifies the media function to be called. It
has encoded in it whether the argument is an input, output or read/write
parameter, and the size of the argument ``argp`` in bytes.

Macros and structures definitions specifying media ioctl requests and
their parameters are located in the media.h header file. All media ioctl
requests, their respective function and parameters are specified in
:ref:`media-user-func`.

Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

Request-specific error codes are listed in the individual requests
descriptions.

When an ioctl that takes an output or read/write parameter fails, the
parameter remains unmodified.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC

.. _media-func-open:

************
media open()
************

Name
====

media-open - Open a media device

Synopsis
========

.. code-block:: c

    #include <fcntl.h>

.. c:function:: int open( const char *device_name, int flags )

Arguments
=========

``device_name``
    Device to be opened.

``flags``
    Open flags. Access mode must be either ``O_RDONLY`` or ``O_RDWR``.
    Other flags have no effect.

Description
===========

To open a media device applications call :c:func:`open()` with the
desired device name. The function has no side effects; the device
configuration remain unchanged.

When the device is opened in read-only mode, attempts to modify its
configuration will result in an error, and ``errno`` will be set to
EBADF.

Return Value
============

:c:func:`open()` returns the new file descriptor on success. On error,
-1 is returned, and ``errno`` is set appropriately. Possible error codes
are:

EACCES
    The requested access to the file is not allowed.

EMFILE
    The process already has the maximum number of files open.

ENFILE
    The system limit on the total number of open files has been reached.

ENOMEM
    Insufficient kernel memory was available.

ENXIO
    No device corresponding to this device special file exists.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _media-user-func:

******************
Function Reference
******************

.. toctree::
    :maxdepth: 1

    media-func-open
    media-func-close
    media-func-ioctl
    media-ioc-device-info
    media-ioc-g-topology
    media-ioc-enum-entities
    media-ioc-enum-links
    media-ioc-setup-link
    media-ioc-request-alloc
    request-func-close
    request-func-ioctl
    request-func-poll
    media-request-ioc-queue
    media-request-ioc-reinit


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _media_header:

****************************
Media Controller Header File
****************************

.. kernel-include:: $BUILDDIR/media.h.rst


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC

.. _media_ioc_device_info:

***************************
ioctl MEDIA_IOC_DEVICE_INFO
***************************

Name
====

MEDIA_IOC_DEVICE_INFO - Query device information

Synopsis
========

.. c:macro:: MEDIA_IOC_DEVICE_INFO

``int ioctl(int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`media_device_info`.

Description
===========

All media devices must support the ``MEDIA_IOC_DEVICE_INFO`` ioctl. To
query device information, applications call the ioctl with a pointer to
a struct :c:type:`media_device_info`. The driver
fills the structure and returns the information to the application. The
ioctl never fails.

.. c:type:: media_device_info

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. flat-table:: struct media_device_info
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    *  -  char
       -  ``driver``\ [16]
       -  Name of the driver implementing the media API as a NUL-terminated
	  ASCII string. The driver version is stored in the
	  ``driver_version`` field.

	  Driver specific applications can use this information to verify
	  the driver identity. It is also useful to work around known bugs,
	  or to identify drivers in error reports.

    *  -  char
       -  ``model``\ [32]
       -  Device model name as a NUL-terminated UTF-8 string. The device
	  version is stored in the ``device_version`` field and is not be
	  appended to the model name.

    *  -  char
       -  ``serial``\ [40]
       -  Serial number as a NUL-terminated ASCII string.

    *  -  char
       -  ``bus_info``\ [32]
       -  Location of the device in the system as a NUL-terminated ASCII
	  string. This includes the bus type name (PCI, USB, ...) and a
	  bus-specific identifier.

    *  -  __u32
       -  ``media_version``
       -  Media API version, formatted with the ``KERNEL_VERSION()`` macro.

    *  -  __u32
       -  ``hw_revision``
       -  Hardware device revision in a driver-specific format.

    *  -  __u32
       -  ``driver_version``
       -  Media device driver version, formatted with the
	  ``KERNEL_VERSION()`` macro. Together with the ``driver`` field
	  this identifies a particular driver.

    *  -  __u32
       -  ``reserved``\ [31]
       -  Reserved for future extensions. Drivers and applications must set
	  this array to zero.

The ``serial`` and ``bus_info`` fields can be used to distinguish
between multiple instances of otherwise identical hardware. The serial
number takes precedence when provided and can be assumed to be unique.
If the serial number is an empty string, the ``bus_info`` field can be
used instead. The ``bus_info`` field is guaranteed to be unique, but can
vary across reboots or device unplug/replug.

Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC

.. _media_ioc_enum_entities:

*****************************
ioctl MEDIA_IOC_ENUM_ENTITIES
*****************************

Name
====

MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties

Synopsis
========

.. c:macro:: MEDIA_IOC_ENUM_ENTITIES

``int ioctl(int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`media_entity_desc`.

Description
===========

To query the attributes of an entity, applications set the id field of a
struct :c:type:`media_entity_desc` structure and
call the MEDIA_IOC_ENUM_ENTITIES ioctl with a pointer to this
structure. The driver fills the rest of the structure or returns an
EINVAL error code when the id is invalid.

.. _media-ent-id-flag-next:

Entities can be enumerated by or'ing the id with the
``MEDIA_ENT_ID_FLAG_NEXT`` flag. The driver will return information
about the entity with the smallest id strictly larger than the requested
one ('next entity'), or the ``EINVAL`` error code if there is none.

Entity IDs can be non-contiguous. Applications must *not* try to
enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing
id's until they get an error.

.. c:type:: media_entity_desc

.. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{10.6cm}|

.. flat-table:: struct media_entity_desc
    :header-rows:  0
    :stub-columns: 0
    :widths: 2 2 1 8

    *  -  __u32
       -  ``id``
       -
       -  Entity ID, set by the application. When the ID is or'ed with
	  ``MEDIA_ENT_ID_FLAG_NEXT``, the driver clears the flag and returns
	  the first entity with a larger ID. Do not expect that the ID will
	  always be the same for each instance of the device. In other words,
	  do not hardcode entity IDs in an application.

    *  -  char
       -  ``name``\ [32]
       -
       -  Entity name as an UTF-8 NULL-terminated string. This name must be unique
          within the media topology.

    *  -  __u32
       -  ``type``
       -
       -  Entity type, see :ref:`media-entity-functions` for details.

    *  -  __u32
       -  ``revision``
       -
       -  Entity revision. Always zero (obsolete)

    *  -  __u32
       -  ``flags``
       -
       -  Entity flags, see :ref:`media-entity-flag` for details.

    *  -  __u32
       -  ``group_id``
       -
       -  Entity group ID. Always zero (obsolete)

    *  -  __u16
       -  ``pads``
       -
       -  Number of pads

    *  -  __u16
       -  ``links``
       -
       -  Total number of outbound links. Inbound links are not counted in
	  this field.

    *  -  __u32
       -  ``reserved[4]``
       -
       -  Reserved for future extensions. Drivers and applications must set
          the array to zero.

    *  -  union {
       -  (anonymous)

    *  -  struct
       -  ``dev``
       -
       -  Valid for (sub-)devices that create a single device node.

    *  -
       -  __u32
       -  ``major``
       -  Device node major number.

    *  -
       -  __u32
       -  ``minor``
       -  Device node minor number.

    *  -  __u8
       -  ``raw``\ [184]
       -
       -
    *  - }
       -

Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

EINVAL
    The struct :c:type:`media_entity_desc` ``id``
    references a non-existing entity.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC

.. _media_ioc_enum_links:

**************************
ioctl MEDIA_IOC_ENUM_LINKS
**************************

Name
====

MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity

Synopsis
========

.. c:macro:: MEDIA_IOC_ENUM_LINKS

``int ioctl(int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`media_links_enum`.

Description
===========

To enumerate pads and/or links for a given entity, applications set the
entity field of a struct :c:type:`media_links_enum`
structure and initialize the struct
:c:type:`media_pad_desc` and struct
:c:type:`media_link_desc` structure arrays pointed by
the ``pads`` and ``links`` fields. They then call the
MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure.

If the ``pads`` field is not NULL, the driver fills the ``pads`` array
with information about the entity's pads. The array must have enough
room to store all the entity's pads. The number of pads can be retrieved
with :ref:`MEDIA_IOC_ENUM_ENTITIES`.

If the ``links`` field is not NULL, the driver fills the ``links`` array
with information about the entity's outbound links. The array must have
enough room to store all the entity's outbound links. The number of
outbound links can be retrieved with :ref:`MEDIA_IOC_ENUM_ENTITIES`.

Only forward links that originate at one of the entity's source pads are
returned during the enumeration process.

.. c:type:: media_links_enum

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. flat-table:: struct media_links_enum
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    *  -  __u32
       -  ``entity``
       -  Entity id, set by the application.

    *  -  struct :c:type:`media_pad_desc`
       -  \*\ ``pads``
       -  Pointer to a pads array allocated by the application. Ignored if
	  NULL.

    *  -  struct :c:type:`media_link_desc`
       -  \*\ ``links``
       -  Pointer to a links array allocated by the application. Ignored if
	  NULL.

    *  -  __u32
       -  ``reserved[4]``
       -  Reserved for future extensions. Drivers and applications must set
          the array to zero.

.. c:type:: media_pad_desc

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. flat-table:: struct media_pad_desc
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    *  -  __u32
       -  ``entity``
       -  ID of the entity this pad belongs to.

    *  -  __u16
       -  ``index``
       -  Pad index, starts at 0.

    *  -  __u32
       -  ``flags``
       -  Pad flags, see :ref:`media-pad-flag` for more details.

    *  -  __u32
       -  ``reserved[2]``
       -  Reserved for future extensions. Drivers and applications must set
          the array to zero.

.. c:type:: media_link_desc

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. flat-table:: struct media_link_desc
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    *  -  struct :c:type:`media_pad_desc`
       -  ``source``
       -  Pad at the origin of this link.

    *  -  struct :c:type:`media_pad_desc`
       -  ``sink``
       -  Pad at the target of this link.

    *  -  __u32
       -  ``flags``
       -  Link flags, see :ref:`media-link-flag` for more details.

    *  -  __u32
       -  ``reserved[2]``
       -  Reserved for future extensions. Drivers and applications must set
          the array to zero.

Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

EINVAL
    The struct :c:type:`media_links_enum` ``id``
    references a non-existing entity.