diff options
Diffstat (limited to 'Documentation/media/uapi/mediactl')
14 files changed, 1528 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..0eea4f9a0 --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-controller.rst @@ -0,0 +1,54 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. 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 + 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..a8f5203af --- /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> + + +.. c:function:: int close( int fd ) + :name: mc-close + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open() <mc-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..fe072b7c8 --- /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> + + +.. c:function:: int ioctl( int fd, int request, void *argp ) + :name: mc-ioctl + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open() <mc-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..32f53016a --- /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> + + +.. c:function:: int open( const char *device_name, int flags ) + :name: mc-open + +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..649cb3d9e --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-ioc-device-info.rst @@ -0,0 +1,110 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media_ioc_device_info: + +*************************** +ioctl MEDIA_IOC_DEVICE_INFO +*************************** + +Name +==== + +MEDIA_IOC_DEVICE_INFO - Query device information + + +Synopsis +======== + +.. c:function:: int ioctl( int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp ) + :name: MEDIA_IOC_DEVICE_INFO + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <media-func-open>`. + +``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 :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.7cm}| + +.. 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. 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..fc2e39c07 --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst @@ -0,0 +1,158 @@ +.. -*- 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 +======== + +.. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp ) + :name: MEDIA_IOC_ENUM_ENTITIES + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <media-func-open>`. + +``argp`` + + +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{11.2cm}| + +.. flat-table:: struct media_entity_desc + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 1 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 + + * - + - 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. 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..f158c134e --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst @@ -0,0 +1,144 @@ +.. -*- 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 +======== + +.. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp ) + :name: MEDIA_IOC_ENUM_LINKS + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <media-func-open>`. + +``argp`` + + +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.7cm}| + +.. 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. + + +.. c:type:: media_pad_desc + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| + +.. 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.7cm}| + +.. 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[4]`` + - 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. 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..bac128c7e --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst @@ -0,0 +1,299 @@ +.. -*- 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 +======== + +.. c:function:: int ioctl( int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp ) + :name: MEDIA_IOC_G_TOPOLOGY + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <media-func-open>`. + +``argp`` + + +Description +=========== + +The typical usage of this ioctl is to call it twice. On the first call, +the structure defined at struct +:c:type:`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. + +.. tabularcolumns:: |p{1.6cm}|p{3.4cm}|p{12.5cm}| + +.. c:type:: media_v2_topology + +.. flat-table:: struct media_v2_topology + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 8 + + * - __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. + + * - __u32 + - ``num_entities`` + - Number of entities in the graph + + * - __u32 + - ``reserved1`` + - Applications and drivers shall set this to 0. + + * - __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`` + + * - __u32 + - ``num_interfaces`` + - Number of interfaces in the graph + + * - __u32 + - ``reserved2`` + - Applications and drivers shall set this to 0. + + * - __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`` + + * - __u32 + - ``num_pads`` + - Total number of pads in the graph + + * - __u32 + - ``reserved3`` + - Applications and drivers shall set this to 0. + + * - __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`` + + * - __u32 + - ``num_links`` + - Total number of data and interface links in the graph + + * - __u32 + - ``reserved4`` + - Applications and drivers shall set this to 0. + + * - __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`` + + +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| + +.. c:type:: media_v2_entity + +.. flat-table:: struct media_v2_entity + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 8 + + * - __u32 + - ``id`` + - Unique ID for the entity. 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``\ [64] + - Entity name as an UTF-8 NULL-terminated string. This name must be unique + within the media topology. + + * - __u32 + - ``function`` + - Entity main function, see :ref:`media-entity-functions` for details. + + * - __u32 + - ``flags`` + - Entity flags, see :ref:`media-entity-flag` for details. + Only valid if ``MEDIA_V2_ENTITY_HAS_FLAGS(media_version)`` + returns true. The ``media_version`` is defined in struct + :c:type:`media_device_info` and can be retrieved using + :ref:`MEDIA_IOC_DEVICE_INFO`. + + * - __u32 + - ``reserved``\ [5] + - Reserved for future extensions. Drivers and applications must set + this array to zero. + + +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| + +.. c:type:: media_v2_interface + +.. flat-table:: struct media_v2_interface + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 8 + + * - __u32 + - ``id`` + - Unique ID for the interface. Do not expect that the ID will + always be the same for each instance of the device. In other words, + do not hardcode interface IDs in an application. + + * - __u32 + - ``intf_type`` + - Interface type, see :ref:`media-intf-type` for details. + + * - __u32 + - ``flags`` + - Interface flags. Currently unused. + + * - __u32 + - ``reserved``\ [9] + - Reserved for future extensions. Drivers and applications must set + this array to zero. + + * - struct media_v2_intf_devnode + - ``devnode`` + - Used only for device node interfaces. See + :c:type:`media_v2_intf_devnode` for details. + + +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| + +.. c:type:: media_v2_intf_devnode + +.. flat-table:: struct media_v2_intf_devnode + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 8 + + * - __u32 + - ``major`` + - Device node major number. + + * - __u32 + - ``minor`` + - Device node minor number. + +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| + +.. c:type:: media_v2_pad + +.. flat-table:: struct media_v2_pad + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 8 + + * - __u32 + - ``id`` + - Unique ID for the pad. Do not expect that the ID will + always be the same for each instance of the device. In other words, + do not hardcode pad IDs in an application. + + * - __u32 + - ``entity_id`` + - Unique ID for the entity where this pad belongs. + + * - __u32 + - ``flags`` + - Pad flags, see :ref:`media-pad-flag` for more details. + + * - __u32 + - ``index`` + - Pad index, starts at 0. Only valid if ``MEDIA_V2_PAD_HAS_INDEX(media_version)`` + returns true. The ``media_version`` is defined in struct + :c:type:`media_device_info` and can be retrieved using + :ref:`MEDIA_IOC_DEVICE_INFO`. + + * - __u32 + - ``reserved``\ [4] + - Reserved for future extensions. Drivers and applications must set + this array to zero. + + +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| + +.. c:type:: media_v2_link + +.. flat-table:: struct media_v2_link + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 8 + + * - __u32 + - ``id`` + - Unique ID for the link. Do not expect that the ID will + always be the same for each instance of the device. In other words, + do not hardcode link IDs in an application. + + * - __u32 + - ``source_id`` + - On pad to pad links: unique ID for the source pad. + + On interface to entity links: unique ID for the interface. + + * - __u32 + - ``sink_id`` + - On pad to pad links: unique ID for the sink pad. + + On interface to entity links: unique ID for the entity. + + * - __u32 + - ``flags`` + - Link flags, see :ref:`media-link-flag` for more details. + + * - __u32 + - ``reserved``\ [6] + - 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..ae5194940 --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-ioc-setup-link.rst @@ -0,0 +1,66 @@ +.. -*- 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 +======== + +.. c:function:: int ioctl( int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp ) + :name: MEDIA_IOC_SETUP_LINK + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <media-func-open>`. + +``argp`` + + +Description +=========== + +To change link properties applications fill a struct +:c:type:`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 :c:type:`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..e4c57c8f4 --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-types.rst @@ -0,0 +1,418 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-controller-types: + +Types and flags used to represent the media graph elements +========================================================== + +.. tabularcolumns:: |p{8.2cm}|p{10.3cm}| + +.. _media-entity-functions: +.. _MEDIA-ENT-F-UNKNOWN: +.. _MEDIA-ENT-F-V4L2-SUBDEV-UNKNOWN: +.. _MEDIA-ENT-F-IO-V4L: +.. _MEDIA-ENT-F-IO-VBI: +.. _MEDIA-ENT-F-IO-SWRADIO: +.. _MEDIA-ENT-F-IO-DTV: +.. _MEDIA-ENT-F-DTV-DEMOD: +.. _MEDIA-ENT-F-TS-DEMUX: +.. _MEDIA-ENT-F-DTV-CA: +.. _MEDIA-ENT-F-DTV-NET-DECAP: +.. _MEDIA-ENT-F-CONN-RF: +.. _MEDIA-ENT-F-CONN-SVIDEO: +.. _MEDIA-ENT-F-CONN-COMPOSITE: +.. _MEDIA-ENT-F-CAM-SENSOR: +.. _MEDIA-ENT-F-FLASH: +.. _MEDIA-ENT-F-LENS: +.. _MEDIA-ENT-F-ATV-DECODER: +.. _MEDIA-ENT-F-TUNER: +.. _MEDIA-ENT-F-IF-VID-DECODER: +.. _MEDIA-ENT-F-IF-AUD-DECODER: +.. _MEDIA-ENT-F-AUDIO-CAPTURE: +.. _MEDIA-ENT-F-AUDIO-PLAYBACK: +.. _MEDIA-ENT-F-AUDIO-MIXER: +.. _MEDIA-ENT-F-PROC-VIDEO-COMPOSER: +.. _MEDIA-ENT-F-PROC-VIDEO-PIXEL-FORMATTER: +.. _MEDIA-ENT-F-PROC-VIDEO-PIXEL-ENC-CONV: +.. _MEDIA-ENT-F-PROC-VIDEO-LUT: +.. _MEDIA-ENT-F-PROC-VIDEO-SCALER: +.. _MEDIA-ENT-F-PROC-VIDEO-STATISTICS: +.. _MEDIA-ENT-F-PROC-VIDEO-ENCODER: +.. _MEDIA-ENT-F-PROC-VIDEO-DECODER: +.. _MEDIA-ENT-F-VID-MUX: +.. _MEDIA-ENT-F-VID-IF-BRIDGE: +.. _MEDIA-ENT-F-DV-DECODER: +.. _MEDIA-ENT-F-DV-ENCODER: + +.. cssclass:: longtable + +.. flat-table:: Media entity functions + :header-rows: 0 + :stub-columns: 0 + + * - ``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, which is a Kernel bug + + * - ``MEDIA_ENT_F_IO_V4L`` + - Data streaming input and/or output entity. + + * - ``MEDIA_ENT_F_IO_VBI`` + - V4L VBI streaming input or output entity + + * - ``MEDIA_ENT_F_IO_SWRADIO`` + - V4L Software Digital Radio (SDR) streaming input or output entity + + * - ``MEDIA_ENT_F_IO_DTV`` + - DVB Digital TV streaming input or output entity + + * - ``MEDIA_ENT_F_DTV_DEMOD`` + - Digital TV demodulator entity. + + * - ``MEDIA_ENT_F_TS_DEMUX`` + - MPEG Transport stream demux entity. Could be implemented on + hardware or in Kernelspace by the Linux DVB subsystem. + + * - ``MEDIA_ENT_F_DTV_CA`` + - Digital TV Conditional Access module (CAM) entity + + * - ``MEDIA_ENT_F_DTV_NET_DECAP`` + - Digital TV network ULE/MLE desencapsulation entity. Could be + implemented on hardware or in Kernelspace + + * - ``MEDIA_ENT_F_CONN_RF`` + - Connector for a Radio Frequency (RF) signal. + + * - ``MEDIA_ENT_F_CONN_SVIDEO`` + - Connector for a S-Video signal. + + * - ``MEDIA_ENT_F_CONN_COMPOSITE`` + - Connector for a RGB composite signal. + + * - ``MEDIA_ENT_F_CAM_SENSOR`` + - Camera video sensor entity. + + * - ``MEDIA_ENT_F_FLASH`` + - Flash controller entity. + + * - ``MEDIA_ENT_F_LENS`` + - Lens controller entity. + + * - ``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. + + * - ``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. + + * - ``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. + + * - ``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. + + * - ``MEDIA_ENT_F_AUDIO_CAPTURE`` + - Audio Capture Function Entity. + + * - ``MEDIA_ENT_F_AUDIO_PLAYBACK`` + - Audio Playback Function Entity. + + * - ``MEDIA_ENT_F_AUDIO_MIXER`` + - Audio Mixer Function Entity. + + * - ``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. + + * - ``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. + + * - ``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. + + * - ``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. + + * - ``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 + sub-sampling (occasionally also referred to as skipping) are + considered as scaling. + + * - ``MEDIA_ENT_F_PROC_VIDEO_STATISTICS`` + - Video statistics computation (histogram, 3A, etc.). 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_ENT_F_PROC_VIDEO_ENCODER`` + - Video (MPEG, HEVC, VPx, etc.) encoder. An entity capable of + compressing video frames. Must have one sink pad and at least + one source pad. + + * - ``MEDIA_ENT_F_PROC_VIDEO_DECODER`` + - Video (MPEG, HEVC, VPx, etc.) decoder. An entity capable of + decompressing a compressed video stream into uncompressed video + frames. Must have one sink pad and at least one source pad. + + * - ``MEDIA_ENT_F_VID_MUX`` + - Video multiplexer. An entity capable of multiplexing must have at + least two sink pads and one source pad, and must pass the video + frame(s) received from the active sink pad to the source pad. + + * - ``MEDIA_ENT_F_VID_IF_BRIDGE`` + - Video interface bridge. A video interface bridge entity must have at + least one sink pad and at least one source pad. It receives video + frames on its sink pad from an input video bus of one type (HDMI, eDP, + MIPI CSI-2, etc.), and outputs them on its source pad to an output + video bus of another type (eDP, MIPI CSI-2, parallel, etc.). + + * - ``MEDIA_ENT_F_DV_DECODER`` + - Digital video decoder. The basic function of the video decoder is + to accept digital video from a wide variety of sources + and output it in some digital video standard, with appropriate + timing signals. + + * - ``MEDIA_ENT_F_DV_ENCODER`` + - Digital video encoder. The basic function of the video encoder is + to accept digital video from some digital video standard with + appropriate timing signals (usually a parallel video bus with sync + signals) and output this to a digital video output connector such + as HDMI or DisplayPort. + +.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| + +.. _media-entity-flag: +.. _MEDIA-ENT-FL-DEFAULT: +.. _MEDIA-ENT-FL-CONNECTOR: + +.. flat-table:: Media entity flags + :header-rows: 0 + :stub-columns: 0 + + * - ``MEDIA_ENT_FL_DEFAULT`` + - Default entity for its type. Used to discover the default audio, + VBI and video devices, the default camera sensor, etc. + + * - ``MEDIA_ENT_FL_CONNECTOR`` + - The entity represents a connector. + + +.. tabularcolumns:: |p{6.5cm}|p{6.0cm}|p{5.0cm}| + +.. _media-intf-type: +.. _MEDIA-INTF-T-DVB-FE: +.. _MEDIA-INTF-T-DVB-DEMUX: +.. _MEDIA-INTF-T-DVB-DVR: +.. _MEDIA-INTF-T-DVB-CA: +.. _MEDIA-INTF-T-DVB-NET: +.. _MEDIA-INTF-T-V4L-VIDEO: +.. _MEDIA-INTF-T-V4L-VBI: +.. _MEDIA-INTF-T-V4L-RADIO: +.. _MEDIA-INTF-T-V4L-SUBDEV: +.. _MEDIA-INTF-T-V4L-SWRADIO: +.. _MEDIA-INTF-T-V4L-TOUCH: +.. _MEDIA-INTF-T-ALSA-PCM-CAPTURE: +.. _MEDIA-INTF-T-ALSA-PCM-PLAYBACK: +.. _MEDIA-INTF-T-ALSA-CONTROL: +.. _MEDIA-INTF-T-ALSA-COMPRESS: +.. _MEDIA-INTF-T-ALSA-RAWMIDI: +.. _MEDIA-INTF-T-ALSA-HWDEP: +.. _MEDIA-INTF-T-ALSA-SEQUENCER: +.. _MEDIA-INTF-T-ALSA-TIMER: + +.. flat-table:: Media interface types + :header-rows: 0 + :stub-columns: 0 + + * - ``MEDIA_INTF_T_DVB_FE`` + - Device node interface for the Digital TV frontend + - typically, /dev/dvb/adapter?/frontend? + + * - ``MEDIA_INTF_T_DVB_DEMUX`` + - Device node interface for the Digital TV demux + - typically, /dev/dvb/adapter?/demux? + + * - ``MEDIA_INTF_T_DVB_DVR`` + - Device node interface for the Digital TV DVR + - typically, /dev/dvb/adapter?/dvr? + + * - ``MEDIA_INTF_T_DVB_CA`` + - Device node interface for the Digital TV Conditional Access + - typically, /dev/dvb/adapter?/ca? + + * - ``MEDIA_INTF_T_DVB_NET`` + - Device node interface for the Digital TV network control + - typically, /dev/dvb/adapter?/net? + + * - ``MEDIA_INTF_T_V4L_VIDEO`` + - Device node interface for video (V4L) + - typically, /dev/video? + + * - ``MEDIA_INTF_T_V4L_VBI`` + - Device node interface for VBI (V4L) + - typically, /dev/vbi? + + * - ``MEDIA_INTF_T_V4L_RADIO`` + - Device node interface for radio (V4L) + - typically, /dev/radio? + + * - ``MEDIA_INTF_T_V4L_SUBDEV`` + - Device node interface for a V4L subdevice + - typically, /dev/v4l-subdev? + + * - ``MEDIA_INTF_T_V4L_SWRADIO`` + - Device node interface for Software Defined Radio (V4L) + - typically, /dev/swradio? + + * - ``MEDIA_INTF_T_V4L_TOUCH`` + - Device node interface for Touch device (V4L) + - typically, /dev/v4l-touch? + + * - ``MEDIA_INTF_T_ALSA_PCM_CAPTURE`` + - Device node interface for ALSA PCM Capture + - typically, /dev/snd/pcmC?D?c + + * - ``MEDIA_INTF_T_ALSA_PCM_PLAYBACK`` + - Device node interface for ALSA PCM Playback + - typically, /dev/snd/pcmC?D?p + + * - ``MEDIA_INTF_T_ALSA_CONTROL`` + - Device node interface for ALSA Control + - typically, /dev/snd/controlC? + + * - ``MEDIA_INTF_T_ALSA_COMPRESS`` + - Device node interface for ALSA Compress + - typically, /dev/snd/compr? + + * - ``MEDIA_INTF_T_ALSA_RAWMIDI`` + - Device node interface for ALSA Raw MIDI + - typically, /dev/snd/midi? + + * - ``MEDIA_INTF_T_ALSA_HWDEP`` + - Device node interface for ALSA Hardware Dependent + - typically, /dev/snd/hwC?D? + + * - ``MEDIA_INTF_T_ALSA_SEQUENCER`` + - Device node interface for ALSA Sequencer + - typically, /dev/snd/seq + + * - ``MEDIA_INTF_T_ALSA_TIMER`` + - Device node interface for ALSA Timer + - typically, /dev/snd/timer + + +.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| + +.. _media-pad-flag: +.. _MEDIA-PAD-FL-SINK: +.. _MEDIA-PAD-FL-SOURCE: +.. _MEDIA-PAD-FL-MUST-CONNECT: + +.. flat-table:: Media pad flags + :header-rows: 0 + :stub-columns: 0 + + * - ``MEDIA_PAD_FL_SINK`` + - Input pad, relative to the entity. Input pads sink data and are + targets of links. + + * - ``MEDIA_PAD_FL_SOURCE`` + - Output pad, relative to the entity. Output pads source data and + are origins of links. + + * - ``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. + +.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| + +.. _media-link-flag: +.. _MEDIA-LNK-FL-ENABLED: +.. _MEDIA-LNK-FL-IMMUTABLE: +.. _MEDIA-LNK-FL-DYNAMIC: +.. _MEDIA-LNK-FL-LINK-TYPE: + +.. flat-table:: Media link flags + :header-rows: 0 + :stub-columns: 0 + + * - ``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. + + * - ``MEDIA_LNK_FL_IMMUTABLE`` + - The link enabled state can't be modified at runtime. An immutable + link is always enabled. + + * - ``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. + + * - ``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 |