summaryrefslogtreecommitdiff
path: root/Documentation/media/uapi/mediactl
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/media/uapi/mediactl')
-rw-r--r--Documentation/media/uapi/mediactl/media-controller-intro.rst33
-rw-r--r--Documentation/media/uapi/mediactl/media-controller-model.rst35
-rw-r--r--Documentation/media/uapi/mediactl/media-controller.rst52
-rw-r--r--Documentation/media/uapi/mediactl/media-func-close.rst47
-rw-r--r--Documentation/media/uapi/mediactl/media-func-ioctl.rst67
-rw-r--r--Documentation/media/uapi/mediactl/media-func-open.rst69
-rw-r--r--Documentation/media/uapi/mediactl/media-funcs.rst18
-rw-r--r--Documentation/media/uapi/mediactl/media-header.rst10
-rw-r--r--Documentation/media/uapi/mediactl/media-ioc-device-info.rst142
-rw-r--r--Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst199
-rw-r--r--Documentation/media/uapi/mediactl/media-ioc-enum-links.rst170
-rw-r--r--Documentation/media/uapi/mediactl/media-ioc-g-topology.rst377
-rw-r--r--Documentation/media/uapi/mediactl/media-ioc-setup-link.rst68
-rw-r--r--Documentation/media/uapi/mediactl/media-types.rst606
14 files changed, 1893 insertions, 0 deletions
diff --git a/Documentation/media/uapi/mediactl/media-controller-intro.rst b/Documentation/media/uapi/mediactl/media-controller-intro.rst
new file mode 100644
index 000000000..3e776c0d8
--- /dev/null
+++ b/Documentation/media/uapi/mediactl/media-controller-intro.rst
@@ -0,0 +1,33 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _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.
diff --git a/Documentation/media/uapi/mediactl/media-controller-model.rst b/Documentation/media/uapi/mediactl/media-controller-model.rst
new file mode 100644
index 000000000..558273cf9
--- /dev/null
+++ b/Documentation/media/uapi/mediactl/media-controller-model.rst
@@ -0,0 +1,35 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _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.
diff --git a/Documentation/media/uapi/mediactl/media-controller.rst b/Documentation/media/uapi/mediactl/media-controller.rst
new file mode 100644
index 000000000..7ae38d489
--- /dev/null
+++ b/Documentation/media/uapi/mediactl/media-controller.rst
@@ -0,0 +1,52 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. include:: <isonum.txt>
+
+.. _media_controller:
+
+##############################
+Part IV - Media Controller API
+##############################
+
+.. class:: toc-title
+
+ Table of Contents
+
+.. toctree::
+ :maxdepth: 5
+ :numbered:
+
+ media-controller-intro
+ media-controller-model
+ media-types
+ 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
diff --git a/Documentation/media/uapi/mediactl/media-func-close.rst b/Documentation/media/uapi/mediactl/media-func-close.rst
new file mode 100644
index 000000000..39ef70ac8
--- /dev/null
+++ b/Documentation/media/uapi/mediactl/media-func-close.rst
@@ -0,0 +1,47 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-func-close:
+
+*************
+media close()
+*************
+
+Name
+====
+
+media-close - Close a media device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <unistd.h>
+
+
+.. cpp:function:: int close( int fd )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+
+Description
+===========
+
+Closes the media device. Resources associated with the file descriptor
+are freed. The device configuration remain unchanged.
+
+
+Return Value
+============
+
+:ref:`close() <media-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.
diff --git a/Documentation/media/uapi/mediactl/media-func-ioctl.rst b/Documentation/media/uapi/mediactl/media-func-ioctl.rst
new file mode 100644
index 000000000..9d1b23133
--- /dev/null
+++ b/Documentation/media/uapi/mediactl/media-func-ioctl.rst
@@ -0,0 +1,67 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-func-ioctl:
+
+*************
+media ioctl()
+*************
+
+Name
+====
+
+media-ioctl - Control a media device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <sys/ioctl.h>
+
+
+.. cpp:function:: int ioctl( int fd, int request, void *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <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.
diff --git a/Documentation/media/uapi/mediactl/media-func-open.rst b/Documentation/media/uapi/mediactl/media-func-open.rst
new file mode 100644
index 000000000..2b2ecd85b
--- /dev/null
+++ b/Documentation/media/uapi/mediactl/media-func-open.rst
@@ -0,0 +1,69 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-func-open:
+
+************
+media open()
+************
+
+Name
+====
+
+media-open - Open a media device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <fcntl.h>
+
+
+.. cpp: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 :ref:`open() <media-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
+============
+
+:ref:`open() <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.
diff --git a/Documentation/media/uapi/mediactl/media-funcs.rst b/Documentation/media/uapi/mediactl/media-funcs.rst
new file mode 100644
index 000000000..076856501
--- /dev/null
+++ b/Documentation/media/uapi/mediactl/media-funcs.rst
@@ -0,0 +1,18 @@
+.. _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
diff --git a/Documentation/media/uapi/mediactl/media-header.rst b/Documentation/media/uapi/mediactl/media-header.rst
new file mode 100644
index 000000000..96f7b0155
--- /dev/null
+++ b/Documentation/media/uapi/mediactl/media-header.rst
@@ -0,0 +1,10 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media_header:
+
+****************************
+Media Controller Header File
+****************************
+
+.. kernel-include:: $BUILDDIR/media.h.rst
+
diff --git a/Documentation/media/uapi/mediactl/media-ioc-device-info.rst b/Documentation/media/uapi/mediactl/media-ioc-device-info.rst
new file mode 100644
index 000000000..467d82cbb
--- /dev/null
+++ b/Documentation/media/uapi/mediactl/media-ioc-device-info.rst
@@ -0,0 +1,142 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media_ioc_device_info:
+
+***************************
+ioctl MEDIA_IOC_DEVICE_INFO
+***************************
+
+Name
+====
+
+MEDIA_IOC_DEVICE_INFO - Query device information
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct media_device_info *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <media-func-open>`.
+
+``request``
+ MEDIA_IOC_DEVICE_INFO
+
+``argp``
+
+
+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 :ref:`media_device_info <media-device-info>`. The driver
+fills the structure and returns the information to the application. The
+ioctl never fails.
+
+
+.. _media-device-info:
+
+.. flat-table:: struct media_device_info
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - 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.
+
+ - .. row 2
+
+ - 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.
+
+ - .. row 3
+
+ - char
+
+ - ``serial``\ [40]
+
+ - Serial number as a NUL-terminated ASCII string.
+
+ - .. row 4
+
+ - 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.
+
+ - .. row 5
+
+ - __u32
+
+ - ``media_version``
+
+ - Media API version, formatted with the ``KERNEL_VERSION()`` macro.
+
+ - .. row 6
+
+ - __u32
+
+ - ``hw_revision``
+
+ - Hardware device revision in a driver-specific format.
+
+ - .. row 7
+
+ - __u32
+
+ - ``driver_version``
+
+ - Media device driver version, formatted with the
+ ``KERNEL_VERSION()`` macro. Together with the ``driver`` field
+ this identifies a particular driver.
+
+ - .. row 8
+
+ - __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.
diff --git a/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst b/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst
new file mode 100644
index 000000000..12d4b25d5
--- /dev/null
+++ b/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst
@@ -0,0 +1,199 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media_ioc_enum_entities:
+
+*****************************
+ioctl MEDIA_IOC_ENUM_ENTITIES
+*****************************
+
+Name
+====
+
+MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct media_entity_desc *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <media-func-open>`.
+
+``request``
+ MEDIA_IOC_ENUM_ENTITIES
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of an entity, applications set the id field of a
+struct :ref:`media_entity_desc <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.
+
+
+.. _media-entity-desc:
+
+.. flat-table:: struct media_entity_desc
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 1 8
+
+
+ - .. row 1
+
+ - __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.
+
+ - .. row 2
+
+ - char
+
+ - ``name``\ [32]
+
+ -
+ -
+ - Entity name as an UTF-8 NULL-terminated string.
+
+ - .. row 3
+
+ - __u32
+
+ - ``type``
+
+ -
+ -
+ - Entity type, see :ref:`media-entity-type` for details.
+
+ - .. row 4
+
+ - __u32
+
+ - ``revision``
+
+ -
+ -
+ - Entity revision. Always zero (obsolete)
+
+ - .. row 5
+
+ - __u32
+
+ - ``flags``
+
+ -
+ -
+ - Entity flags, see :ref:`media-entity-flag` for details.
+
+ - .. row 6
+
+ - __u32
+
+ - ``group_id``
+
+ -
+ -
+ - Entity group ID. Always zero (obsolete)
+
+ - .. row 7
+
+ - __u16
+
+ - ``pads``
+
+ -
+ -
+ - Number of pads
+
+ - .. row 8
+
+ - __u16
+
+ - ``links``
+
+ -
+ -
+ - Total number of outbound links. Inbound links are not counted in
+ this field.
+
+ - .. row 9
+
+ - union
+
+ - .. row 10
+
+ -
+ - struct
+
+ - ``dev``
+
+ -
+ - Valid for (sub-)devices that create a single device node.
+
+ - .. row 11
+
+ -
+ -
+ - __u32
+
+ - ``major``
+
+ - Device node major number.
+
+ - .. row 12
+
+ -
+ -
+ - __u32
+
+ - ``minor``
+
+ - Device node minor number.
+
+ - .. row 13
+
+ -
+ - __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 :ref:`media_entity_desc <media-entity-desc>` ``id``
+ references a non-existing entity.
diff --git a/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst b/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst
new file mode 100644
index 000000000..87443b1ce
--- /dev/null
+++ b/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst
@@ -0,0 +1,170 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media_ioc_enum_links:
+
+**************************
+ioctl MEDIA_IOC_ENUM_LINKS
+**************************
+
+Name
+====
+
+MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct media_links_enum *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <media-func-open>`.
+
+``request``
+ MEDIA_IOC_ENUM_LINKS
+
+``argp``
+
+
+Description
+===========
+
+To enumerate pads and/or links for a given entity, applications set the
+entity field of a struct :ref:`media_links_enum <media-links-enum>`
+structure and initialize the struct
+:ref:`media_pad_desc <media-pad-desc>` and struct
+:ref:`media_link_desc <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.
+
+
+.. _media-links-enum:
+
+.. flat-table:: struct media_links_enum
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``entity``
+
+ - Entity id, set by the application.
+
+ - .. row 2
+
+ - struct :ref:`media_pad_desc <media-pad-desc>`
+
+ - \*\ ``pads``
+
+ - Pointer to a pads array allocated by the application. Ignored if
+ NULL.
+
+ - .. row 3
+
+ - struct :ref:`media_link_desc <media-link-desc>`
+
+ - \*\ ``links``
+
+ - Pointer to a links array allocated by the application. Ignored if
+ NULL.
+
+
+
+.. _media-pad-desc:
+
+.. flat-table:: struct media_pad_desc
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``entity``
+
+ - ID of the entity this pad belongs to.
+
+ - .. row 2
+
+ - __u16
+
+ - ``index``
+
+ - 0-based pad index.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - Pad flags, see :ref:`media-pad-flag` for more details.
+
+
+
+.. _media-link-desc:
+
+.. flat-table:: struct media_link_desc
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - struct :ref:`media_pad_desc <media-pad-desc>`
+
+ - ``source``
+
+ - Pad at the origin of this link.
+
+ - .. row 2
+
+ - struct :ref:`media_pad_desc <media-pad-desc>`
+
+ - ``sink``
+
+ - Pad at the target of this link.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - Link flags, see :ref:`media-link-flag` for more details.
+
+
+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 :ref:`media_links_enum <media-links-enum>` ``id``
+ references a non-existing entity.
diff --git a/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst b/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst
new file mode 100644
index 000000000..2e382cc77
--- /dev/null
+++ b/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst
@@ -0,0 +1,377 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media_ioc_g_topology:
+
+**************************
+ioctl MEDIA_IOC_G_TOPOLOGY
+**************************
+
+Name
+====
+
+MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct media_v2_topology *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <media-func-open>`.
+
+``request``
+ MEDIA_IOC_G_TOPOLOGY
+
+``argp``
+
+
+Description
+===========
+
+The typical usage of this ioctl is to call it twice. On the first call,
+the structure defined at struct
+:ref:`media_v2_topology <media-v2-topology>` should be zeroed. At
+return, if no errors happen, this ioctl will return the
+``topology_version`` and the total number of entities, interfaces, pads
+and links.
+
+Before the second call, the userspace should allocate arrays to store
+the graph elements that are desired, putting the pointers to them at the
+ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping the
+other values untouched.
+
+If the ``topology_version`` remains the same, the ioctl should fill the
+desired arrays with the media graph elements.
+
+
+.. _media-v2-topology:
+
+.. flat-table:: struct media_v2_topology
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 2 8
+
+
+ - .. row 1
+
+ - __u64
+
+ - ``topology_version``
+
+ - Version of the media graph topology. When the graph is created,
+ this field starts with zero. Every time a graph element is added
+ or removed, this field is incremented.
+
+ - .. row 2
+
+ - __u64
+
+ - ``num_entities``
+
+ - Number of entities in the graph
+
+ - .. row 3
+
+ - __u64
+
+ - ``ptr_entities``
+
+ - A pointer to a memory area where the entities array will be
+ stored, converted to a 64-bits integer. It can be zero. if zero,
+ the ioctl won't store the entities. It will just update
+ ``num_entities``
+
+ - .. row 4
+
+ - __u64
+
+ - ``num_interfaces``
+
+ - Number of interfaces in the graph
+
+ - .. row 5
+
+ - __u64
+
+ - ``ptr_interfaces``
+
+ - A pointer to a memory area where the interfaces array will be
+ stored, converted to a 64-bits integer. It can be zero. if zero,
+ the ioctl won't store the interfaces. It will just update
+ ``num_interfaces``
+
+ - .. row 6
+
+ - __u64
+
+ - ``num_pads``
+
+ - Total number of pads in the graph
+
+ - .. row 7
+
+ - __u64
+
+ - ``ptr_pads``
+
+ - A pointer to a memory area where the pads array will be stored,
+ converted to a 64-bits integer. It can be zero. if zero, the ioctl
+ won't store the pads. It will just update ``num_pads``
+
+ - .. row 8
+
+ - __u64
+
+ - ``num_links``
+
+ - Total number of data and interface links in the graph
+
+ - .. row 9
+
+ - __u64
+
+ - ``ptr_links``
+
+ - A pointer to a memory area where the links array will be stored,
+ converted to a 64-bits integer. It can be zero. if zero, the ioctl
+ won't store the links. It will just update ``num_links``
+
+
+
+.. _media-v2-entity:
+
+.. flat-table:: struct media_v2_entity
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 2 8
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - Unique ID for the entity.
+
+ - .. row 2
+
+ - char
+
+ - ``name``\ [64]
+
+ - Entity name as an UTF-8 NULL-terminated string.
+
+ - .. row 3
+
+ - __u32
+
+ - ``function``
+
+ - Entity main function, see :ref:`media-entity-type` for details.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [12]
+
+ - Reserved for future extensions. Drivers and applications must set
+ this array to zero.
+
+
+
+.. _media-v2-interface:
+
+.. flat-table:: struct media_v2_interface
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 2 8
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - Unique ID for the interface.
+
+ - .. row 2
+
+ - __u32
+
+ - ``intf_type``
+
+ - Interface type, see :ref:`media-intf-type` for details.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - Interface flags. Currently unused.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [9]
+
+ - Reserved for future extensions. Drivers and applications must set
+ this array to zero.
+
+ - .. row 5
+
+ - struct media_v2_intf_devnode
+
+ - ``devnode``
+
+ - Used only for device node interfaces. See
+ :ref:`media-v2-intf-devnode` for details..
+
+
+
+.. _media-v2-intf-devnode:
+
+.. flat-table:: struct media_v2_interface
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 2 8
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``major``
+
+ - Device node major number.
+
+ - .. row 2
+
+ - __u32
+
+ - ``minor``
+
+ - Device node minor number.
+
+
+
+.. _media-v2-pad:
+
+.. flat-table:: struct media_v2_pad
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 2 8
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - Unique ID for the pad.
+
+ - .. row 2
+
+ - __u32
+
+ - ``entity_id``
+
+ - Unique ID for the entity where this pad belongs.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - Pad flags, see :ref:`media-pad-flag` for more details.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [9]
+
+ - Reserved for future extensions. Drivers and applications must set
+ this array to zero.
+
+
+
+.. _media-v2-link:
+
+.. flat-table:: struct media_v2_pad
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 2 8
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - Unique ID for the pad.
+
+ - .. row 2
+
+ - __u32
+
+ - ``source_id``
+
+ - On pad to pad links: unique ID for the source pad.
+
+ On interface to entity links: unique ID for the interface.
+
+ - .. row 3
+
+ - __u32
+
+ - ``sink_id``
+
+ - On pad to pad links: unique ID for the sink pad.
+
+ On interface to entity links: unique ID for the entity.
+
+ - .. row 4
+
+ - __u32
+
+ - ``flags``
+
+ - Link flags, see :ref:`media-link-flag` for more details.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved``\ [5]
+
+ - Reserved for future extensions. Drivers and applications must set
+ this 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.
+
+ENOSPC
+ This is returned when either one or more of the num_entities,
+ num_interfaces, num_links or num_pads are non-zero and are
+ smaller than the actual number of elements inside the graph. This
+ may happen if the ``topology_version`` changed when compared to the
+ last time this ioctl was called. Userspace should usually free the
+ area for the pointers, zero the struct elements and call this ioctl
+ again.
diff --git a/Documentation/media/uapi/mediactl/media-ioc-setup-link.rst b/Documentation/media/uapi/mediactl/media-ioc-setup-link.rst
new file mode 100644
index 000000000..e02fe23de
--- /dev/null
+++ b/Documentation/media/uapi/mediactl/media-ioc-setup-link.rst
@@ -0,0 +1,68 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media_ioc_setup_link:
+
+**************************
+ioctl MEDIA_IOC_SETUP_LINK
+**************************
+
+Name
+====
+
+MEDIA_IOC_SETUP_LINK - Modify the properties of a link
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct media_link_desc *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <media-func-open>`.
+
+``request``
+ MEDIA_IOC_SETUP_LINK
+
+``argp``
+
+
+Description
+===========
+
+To change link properties applications fill a struct
+:ref:`media_link_desc <media-link-desc>` with link identification
+information (source and sink pad) and the new requested link flags. They
+then call the MEDIA_IOC_SETUP_LINK ioctl with a pointer to that
+structure.
+
+The only configurable property is the ``ENABLED`` link flag to
+enable/disable a link. Links marked with the ``IMMUTABLE`` link flag can
+not be enabled or disabled.
+
+Link configuration has no side effect on other links. If an enabled link
+at the sink pad prevents the link from being enabled, the driver returns
+with an ``EBUSY`` error code.
+
+Only links marked with the ``DYNAMIC`` link flag can be enabled/disabled
+while streaming media data. Attempting to enable or disable a streaming
+non-dynamic link will return an ``EBUSY`` error code.
+
+If the specified link can't be found the driver returns with an ``EINVAL``
+error code.
+
+
+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 :ref:`media_link_desc <media-link-desc>` references a
+ non-existing link, or the link is immutable and an attempt to modify
+ its configuration was made.
diff --git a/Documentation/media/uapi/mediactl/media-types.rst b/Documentation/media/uapi/mediactl/media-types.rst
new file mode 100644
index 000000000..c77717b23
--- /dev/null
+++ b/Documentation/media/uapi/mediactl/media-types.rst
@@ -0,0 +1,606 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-controller-types:
+
+Types and flags used to represent the media graph elements
+==========================================================
+
+
+.. _media-entity-type:
+
+.. flat-table:: Media entity types
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ .. _MEDIA-ENT-F-UNKNOWN:
+ .. _MEDIA-ENT-F-V4L2-SUBDEV-UNKNOWN:
+
+ - ``MEDIA_ENT_F_UNKNOWN`` and ``MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN``
+
+ - Unknown entity. That generally indicates that a driver didn't
+ initialize properly the entity, with is a Kernel bug
+
+ - .. row 2
+
+ .. _MEDIA-ENT-F-IO-V4L:
+
+ - ``MEDIA_ENT_F_IO_V4L``
+
+ - Data streaming input and/or output entity.
+
+ - .. row 3
+
+ .. _MEDIA-ENT-F-IO-VBI:
+
+ - ``MEDIA_ENT_F_IO_VBI``
+
+ - V4L VBI streaming input or output entity
+
+ - .. row 4
+
+ .. _MEDIA-ENT-F-IO-SWRADIO:
+
+ - ``MEDIA_ENT_F_IO_SWRADIO``
+
+ - V4L Software Digital Radio (SDR) streaming input or output entity
+
+ - .. row 5
+
+ .. _MEDIA-ENT-F-IO-DTV:
+
+ - ``MEDIA_ENT_F_IO_DTV``
+
+ - DVB Digital TV streaming input or output entity
+
+ - .. row 6
+
+ .. _MEDIA-ENT-F-DTV-DEMOD:
+
+ - ``MEDIA_ENT_F_DTV_DEMOD``
+
+ - Digital TV demodulator entity.
+
+ - .. row 7
+
+ .. _MEDIA-ENT-F-TS-DEMUX:
+
+ - ``MEDIA_ENT_F_TS_DEMUX``
+
+ - MPEG Transport stream demux entity. Could be implemented on
+ hardware or in Kernelspace by the Linux DVB subsystem.
+
+ - .. row 8
+
+ .. _MEDIA-ENT-F-DTV-CA:
+
+ - ``MEDIA_ENT_F_DTV_CA``
+
+ - Digital TV Conditional Access module (CAM) entity
+
+ - .. row 9
+
+ .. _MEDIA-ENT-F-DTV-NET-DECAP:
+
+ - ``MEDIA_ENT_F_DTV_NET_DECAP``
+
+ - Digital TV network ULE/MLE desencapsulation entity. Could be
+ implemented on hardware or in Kernelspace
+
+ - .. row 10
+
+ .. _MEDIA-ENT-F-CONN-RF:
+
+ - ``MEDIA_ENT_F_CONN_RF``
+
+ - Connector for a Radio Frequency (RF) signal.
+
+ - .. row 11
+
+ .. _MEDIA-ENT-F-CONN-SVIDEO:
+
+ - ``MEDIA_ENT_F_CONN_SVIDEO``
+
+ - Connector for a S-Video signal.
+
+ - .. row 12
+
+ .. _MEDIA-ENT-F-CONN-COMPOSITE:
+
+ - ``MEDIA_ENT_F_CONN_COMPOSITE``
+
+ - Connector for a RGB composite signal.
+
+ - .. row 13
+
+ .. _MEDIA-ENT-F-CAM-SENSOR:
+
+ - ``MEDIA_ENT_F_CAM_SENSOR``
+
+ - Camera video sensor entity.
+
+ - .. row 14
+
+ .. _MEDIA-ENT-F-FLASH:
+
+ - ``MEDIA_ENT_F_FLASH``
+
+ - Flash controller entity.
+
+ - .. row 15
+
+ .. _MEDIA-ENT-F-LENS:
+
+ - ``MEDIA_ENT_F_LENS``
+
+ - Lens controller entity.
+
+ - .. row 16
+
+ .. _MEDIA-ENT-F-ATV-DECODER:
+
+ - ``MEDIA_ENT_F_ATV_DECODER``
+
+ - Analog video decoder, the basic function of the video decoder is
+ to accept analogue video from a wide variety of sources such as
+ broadcast, DVD players, cameras and video cassette recorders, in
+ either NTSC, PAL, SECAM or HD format, separating the stream into
+ its component parts, luminance and chrominance, and output it in
+ some digital video standard, with appropriate timing signals.
+
+ - .. row 17
+
+ .. _MEDIA-ENT-F-TUNER:
+
+ - ``MEDIA_ENT_F_TUNER``
+
+ - Digital TV, analog TV, radio and/or software radio tuner, with
+ consists on a PLL tuning stage that converts radio frequency (RF)
+ signal into an Intermediate Frequency (IF). Modern tuners have
+ internally IF-PLL decoders for audio and video, but older models
+ have those stages implemented on separate entities.
+
+ - .. row 18
+
+ .. _MEDIA-ENT-F-IF-VID-DECODER:
+
+ - ``MEDIA_ENT_F_IF_VID_DECODER``
+
+ - IF-PLL video decoder. It receives the IF from a PLL and decodes
+ the analog TV video signal. This is commonly found on some very
+ old analog tuners, like Philips MK3 designs. They all contain a
+ tda9887 (or some software compatible similar chip, like tda9885).
+ Those devices use a different I2C address than the tuner PLL.
+
+ - .. row 19
+
+ .. _MEDIA-ENT-F-IF-AUD-DECODER:
+
+ - ``MEDIA_ENT_F_IF_AUD_DECODER``
+
+ - IF-PLL sound decoder. It receives the IF from a PLL and decodes
+ the analog TV audio signal. This is commonly found on some very
+ old analog hardware, like Micronas msp3400, Philips tda9840,
+ tda985x, etc. Those devices use a different I2C address than the
+ tuner PLL and should be controlled together with the IF-PLL video
+ decoder.
+
+ - .. row 20
+
+ .. _MEDIA-ENT-F-AUDIO-CAPTURE:
+
+ - ``MEDIA_ENT_F_AUDIO_CAPTURE``
+
+ - Audio Capture Function Entity.
+
+ - .. row 21
+
+ .. _MEDIA-ENT-F-AUDIO-PLAYBACK:
+
+ - ``MEDIA_ENT_F_AUDIO_PLAYBACK``
+
+ - Audio Playback Function Entity.
+
+ - .. row 22
+
+ .. _MEDIA-ENT-F-AUDIO-MIXER:
+
+ - ``MEDIA_ENT_F_AUDIO_MIXER``
+
+ - Audio Mixer Function Entity.
+
+ - .. row 23
+
+ .. _MEDIA-ENT-F-PROC-VIDEO-COMPOSER:
+
+ - ``MEDIA_ENT_F_PROC_VIDEO_COMPOSER``
+
+ - Video composer (blender). An entity capable of video
+ composing must have at least two sink pads and one source
+ pad, and composes input video frames onto output video
+ frames. Composition can be performed using alpha blending,
+ color keying, raster operations (ROP), stitching or any other
+ means.
+
+ - .. row 24
+
+ .. _MEDIA-ENT-F-PROC-VIDEO-PIXEL-FORMATTER:
+
+ - ``MEDIA_ENT_F_PROC_VIDEO_PIXEL_FORMATTER``
+
+ - Video pixel formatter. An entity capable of pixel formatting
+ must have at least one sink pad and one source pad. Read
+ pixel formatters read pixels from memory and perform a subset
+ of unpacking, cropping, color keying, alpha multiplication
+ and pixel encoding conversion. Write pixel formatters perform
+ a subset of dithering, pixel encoding conversion and packing
+ and write pixels to memory.
+
+ - .. row 25
+
+ .. _MEDIA-ENT-F-PROC-VIDEO-PIXEL-ENC-CONV:
+
+ - ``MEDIA_ENT_F_PROC_VIDEO_PIXEL_ENC_CONV``
+
+ - Video pixel encoding converter. An entity capable of pixel
+ enconding conversion must have at least one sink pad and one
+ source pad, and convert the encoding of pixels received on
+ its sink pad(s) to a different encoding output on its source
+ pad(s). Pixel encoding conversion includes but isn't limited
+ to RGB to/from HSV, RGB to/from YUV and CFA (Bayer) to RGB
+ conversions.
+
+ - .. row 26
+
+ .. _MEDIA-ENT-F-PROC-VIDEO-LUT:
+
+ - ``MEDIA_ENT_F_PROC_VIDEO_LUT``
+
+ - Video look-up table. An entity capable of video lookup table
+ processing must have one sink pad and one source pad. It uses
+ the values of the pixels received on its sink pad to look up
+ entries in internal tables and output them on its source pad.
+ The lookup processing can be performed on all components
+ separately or combine them for multi-dimensional table
+ lookups.
+
+ - .. row 27
+
+ .. _MEDIA-ENT-F-PROC-VIDEO-SCALER:
+
+ - ``MEDIA_ENT_F_PROC_VIDEO_SCALER``
+
+ - Video scaler. An entity capable of video scaling must have
+ at least one sink pad and one source pad, and scale the
+ video frame(s) received on its sink pad(s) to a different
+ resolution output on its source pad(s). The range of
+ supported scaling ratios is entity-specific and can differ
+ between the horizontal and vertical directions (in particular
+ scaling can be supported in one direction only). Binning and
+ skipping are considered as scaling.
+
+ - .. row 28
+
+ .. _MEDIA-ENT-F-PROC-VIDEO-STATISTICS:
+
+ - ``MEDIA_ENT_F_PROC_VIDEO_STATISTICS``
+
+ - Video statistics computation (histogram, 3A, ...). An entity
+ capable of statistics computation must have one sink pad and
+ one source pad. It computes statistics over the frames
+ received on its sink pad and outputs the statistics data on
+ its source pad.
+
+
+.. _media-entity-flag:
+
+.. flat-table:: Media entity flags
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ .. _MEDIA-ENT-FL-DEFAULT:
+
+ - ``MEDIA_ENT_FL_DEFAULT``
+
+ - Default entity for its type. Used to discover the default audio,
+ VBI and video devices, the default camera sensor, ...
+
+ - .. row 2
+
+ .. _MEDIA-ENT-FL-CONNECTOR:
+
+ - ``MEDIA_ENT_FL_CONNECTOR``
+
+ - The entity represents a data conector
+
+
+
+.. _media-intf-type:
+
+.. flat-table:: Media interface types
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ .. _MEDIA-INTF-T-DVB-FE:
+
+ - ``MEDIA_INTF_T_DVB_FE``
+
+ - Device node interface for the Digital TV frontend
+
+ - typically, /dev/dvb/adapter?/frontend?
+
+ - .. row 2
+
+ .. _MEDIA-INTF-T-DVB-DEMUX:
+
+ - ``MEDIA_INTF_T_DVB_DEMUX``
+
+ - Device node interface for the Digital TV demux
+
+ - typically, /dev/dvb/adapter?/demux?
+
+ - .. row 3
+
+ .. _MEDIA-INTF-T-DVB-DVR:
+
+ - ``MEDIA_INTF_T_DVB_DVR``
+
+ - Device node interface for the Digital TV DVR
+
+ - typically, /dev/dvb/adapter?/dvr?
+
+ - .. row 4
+
+ .. _MEDIA-INTF-T-DVB-CA:
+
+ - ``MEDIA_INTF_T_DVB_CA``
+
+ - Device node interface for the Digital TV Conditional Access
+
+ - typically, /dev/dvb/adapter?/ca?
+
+ - .. row 5
+
+ .. _MEDIA-INTF-T-DVB-NET:
+
+ - ``MEDIA_INTF_T_DVB_NET``
+
+ - Device node interface for the Digital TV network control
+
+ - typically, /dev/dvb/adapter?/net?
+
+ - .. row 6
+
+ .. _MEDIA-INTF-T-V4L-VIDEO:
+
+ - ``MEDIA_INTF_T_V4L_VIDEO``
+
+ - Device node interface for video (V4L)
+
+ - typically, /dev/video?
+
+ - .. row 7
+
+ .. _MEDIA-INTF-T-V4L-VBI:
+
+ - ``MEDIA_INTF_T_V4L_VBI``
+
+ - Device node interface for VBI (V4L)
+
+ - typically, /dev/vbi?
+
+ - .. row 8
+
+ .. _MEDIA-INTF-T-V4L-RADIO:
+
+ - ``MEDIA_INTF_T_V4L_RADIO``
+
+ - Device node interface for radio (V4L)
+
+ - typically, /dev/vbi?
+
+ - .. row 9
+
+ .. _MEDIA-INTF-T-V4L-SUBDEV:
+
+ - ``MEDIA_INTF_T_V4L_SUBDEV``
+
+ - Device node interface for a V4L subdevice
+
+ - typically, /dev/v4l-subdev?
+
+ - .. row 10
+
+ .. _MEDIA-INTF-T-V4L-SWRADIO:
+
+ - ``MEDIA_INTF_T_V4L_SWRADIO``
+
+ - Device node interface for Software Defined Radio (V4L)
+
+ - typically, /dev/swradio?
+
+ - .. row 11
+
+ .. _MEDIA-INTF-T-ALSA-PCM-CAPTURE:
+
+ - ``MEDIA_INTF_T_ALSA_PCM_CAPTURE``
+
+ - Device node interface for ALSA PCM Capture
+
+ - typically, /dev/snd/pcmC?D?c
+
+ - .. row 12
+
+ .. _MEDIA-INTF-T-ALSA-PCM-PLAYBACK:
+
+ - ``MEDIA_INTF_T_ALSA_PCM_PLAYBACK``
+
+ - Device node interface for ALSA PCM Playback
+
+ - typically, /dev/snd/pcmC?D?p
+
+ - .. row 13
+
+ .. _MEDIA-INTF-T-ALSA-CONTROL:
+
+ - ``MEDIA_INTF_T_ALSA_CONTROL``
+
+ - Device node interface for ALSA Control
+
+ - typically, /dev/snd/controlC?
+
+ - .. row 14
+
+ .. _MEDIA-INTF-T-ALSA-COMPRESS:
+
+ - ``MEDIA_INTF_T_ALSA_COMPRESS``
+
+ - Device node interface for ALSA Compress
+
+ - typically, /dev/snd/compr?
+
+ - .. row 15
+
+ .. _MEDIA-INTF-T-ALSA-RAWMIDI:
+
+ - ``MEDIA_INTF_T_ALSA_RAWMIDI``
+
+ - Device node interface for ALSA Raw MIDI
+
+ - typically, /dev/snd/midi?
+
+ - .. row 16
+
+ .. _MEDIA-INTF-T-ALSA-HWDEP:
+
+ - ``MEDIA_INTF_T_ALSA_HWDEP``
+
+ - Device node interface for ALSA Hardware Dependent
+
+ - typically, /dev/snd/hwC?D?
+
+ - .. row 17
+
+ .. _MEDIA-INTF-T-ALSA-SEQUENCER:
+
+ - ``MEDIA_INTF_T_ALSA_SEQUENCER``
+
+ - Device node interface for ALSA Sequencer
+
+ - typically, /dev/snd/seq
+
+ - .. row 18
+
+ .. _MEDIA-INTF-T-ALSA-TIMER:
+
+ - ``MEDIA_INTF_T_ALSA_TIMER``
+
+ - Device node interface for ALSA Timer
+
+ - typically, /dev/snd/timer
+
+
+
+.. _media-pad-flag:
+
+.. flat-table:: Media pad flags
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ .. _MEDIA-PAD-FL-SINK:
+
+ - ``MEDIA_PAD_FL_SINK``
+
+ - Input pad, relative to the entity. Input pads sink data and are
+ targets of links.
+
+ - .. row 2
+
+ .. _MEDIA-PAD-FL-SOURCE:
+
+ - ``MEDIA_PAD_FL_SOURCE``
+
+ - Output pad, relative to the entity. Output pads source data and
+ are origins of links.
+
+ - .. row 3
+
+ .. _MEDIA-PAD-FL-MUST-CONNECT:
+
+ - ``MEDIA_PAD_FL_MUST_CONNECT``
+
+ - If this flag is set and the pad is linked to any other pad, then
+ at least one of those links must be enabled for the entity to be
+ able to stream. There could be temporary reasons (e.g. device
+ configuration dependent) for the pad to need enabled links even
+ when this flag isn't set; the absence of the flag doesn't imply
+ there is none.
+
+
+One and only one of ``MEDIA_PAD_FL_SINK`` and ``MEDIA_PAD_FL_SOURCE``
+must be set for every pad.
+
+
+.. _media-link-flag:
+
+.. flat-table:: Media link flags
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ .. _MEDIA-LNK-FL-ENABLED:
+
+ - ``MEDIA_LNK_FL_ENABLED``
+
+ - The link is enabled and can be used to transfer media data. When
+ two or more links target a sink pad, only one of them can be
+ enabled at a time.
+
+ - .. row 2
+
+ .. _MEDIA-LNK-FL-IMMUTABLE:
+
+ - ``MEDIA_LNK_FL_IMMUTABLE``
+
+ - The link enabled state can't be modified at runtime. An immutable
+ link is always enabled.
+
+ - .. row 3
+
+ .. _MEDIA-LNK-FL-DYNAMIC:
+
+ - ``MEDIA_LNK_FL_DYNAMIC``
+
+ - The link enabled state can be modified during streaming. This flag
+ is set by drivers and is read-only for applications.
+
+ - .. row 4
+
+ .. _MEDIA-LNK-FL-LINK-TYPE:
+
+ - ``MEDIA_LNK_FL_LINK_TYPE``
+
+ - This is a bitmask that defines the type of the link. Currently,
+ two types of links are supported:
+
+ .. _MEDIA-LNK-FL-DATA-LINK:
+
+ ``MEDIA_LNK_FL_DATA_LINK`` if the link is between two pads
+
+ .. _MEDIA-LNK-FL-INTERFACE-LINK:
+
+ ``MEDIA_LNK_FL_INTERFACE_LINK`` if the link is between an
+ interface and an entity