summaryrefslogtreecommitdiff
path: root/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/media/uapi/mediactl/media-ioc-g-topology.rst')
-rw-r--r--Documentation/media/uapi/mediactl/media-ioc-g-topology.rst307
1 files changed, 0 insertions, 307 deletions
diff --git a/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst b/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst
deleted file mode 100644
index 0a7d76ac8ded..000000000000
--- a/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst
+++ /dev/null
@@ -1,307 +0,0 @@
-.. 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, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/media/uapi/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _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``
- Pointer to struct :c:type:`media_v2_topology`.
-
-
-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.