+3 -7

Documentation/userspace-api/media/mediactl/media-func-close.rst

reviewed

··· 1 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 2 + .. c:namespace:: MC 2 3 3 4 .. _media-func-close: 4 5 ··· 12 11 13 12 media-close - Close a media device 14 13 15 15 - 16 14 Synopsis 17 15 ======== 18 16 ··· 19 19 20 20 #include <unistd.h> 21 21 22 22 - 23 22 .. c:function:: int close( int fd ) 24 24 - :name: mc-close 25 23 26 24 Arguments 27 25 ========= 28 26 29 27 ``fd`` 30 30 - File descriptor returned by :c:func:`open() <mc-open>`. 31 31 - 28 28 + File descriptor returned by :c:func:`open()`. 32 29 33 30 Description 34 31 =========== ··· 33 36 Closes the media device. Resources associated with the file descriptor 34 37 are freed. The device configuration remain unchanged. 35 38 36 36 - 37 39 Return Value 38 40 ============ 39 41 40 40 - :ref:`close() <media-func-close>` returns 0 on success. On error, -1 is returned, and 42 42 + :c:func:`close()` returns 0 on success. On error, -1 is returned, and 41 43 ``errno`` is set appropriately. Possible error codes are: 42 44 43 45 EBADF

+3 -7

Documentation/userspace-api/media/mediactl/media-func-ioctl.rst

reviewed

··· 1 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 2 + .. c:namespace:: MC 2 3 3 4 .. _media-func-ioctl: 4 5 ··· 12 11 13 12 media-ioctl - Control a media device 14 13 15 15 - 16 14 Synopsis 17 15 ======== 18 16 ··· 19 19 20 20 #include <sys/ioctl.h> 21 21 22 22 - 23 23 - .. c:function:: int ioctl( int fd, int request, void *argp ) 24 24 - :name: mc-ioctl 22 22 + ``int ioctl(int fd, int request, void *argp)`` 25 23 26 24 Arguments 27 25 ========= 28 26 29 27 ``fd`` 30 30 - File descriptor returned by :c:func:`open() <mc-open>`. 28 28 + File descriptor returned by :c:func:`open()`. 31 29 32 30 ``request`` 33 31 Media ioctl request code as defined in the media.h header file, for ··· 33 35 34 36 ``argp`` 35 37 Pointer to a request-specific structure. 36 36 - 37 38 38 39 Description 39 40 =========== ··· 48 51 their parameters are located in the media.h header file. All media ioctl 49 52 requests, their respective function and parameters are specified in 50 53 :ref:`media-user-func`. 51 51 - 52 54 53 55 Return Value 54 56 ============

+3 -7

Documentation/userspace-api/media/mediactl/media-func-open.rst

reviewed

··· 1 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 2 + .. c:namespace:: MC 2 3 3 4 .. _media-func-open: 4 5 ··· 12 11 13 12 media-open - Open a media device 14 13 15 15 - 16 14 Synopsis 17 15 ======== 18 16 ··· 19 19 20 20 #include <fcntl.h> 21 21 22 22 - 23 22 .. c:function:: int open( const char *device_name, int flags ) 24 24 - :name: mc-open 25 23 26 24 Arguments 27 25 ========= ··· 31 33 Open flags. Access mode must be either ``O_RDONLY`` or ``O_RDWR``. 32 34 Other flags have no effect. 33 35 34 34 - 35 36 Description 36 37 =========== 37 38 38 38 - To open a media device applications call :ref:`open() <media-func-open>` with the 39 39 + To open a media device applications call :c:func:`open()` with the 39 40 desired device name. The function has no side effects; the device 40 41 configuration remain unchanged. 41 42 ··· 42 45 configuration will result in an error, and ``errno`` will be set to 43 46 EBADF. 44 47 45 45 - 46 48 Return Value 47 49 ============ 48 50 49 49 - :ref:`open() <func-open>` returns the new file descriptor on success. On error, 51 51 + :c:func:`open()` returns the new file descriptor on success. On error, 50 52 -1 is returned, and ``errno`` is set appropriately. Possible error codes 51 53 are: 52 54

+4 -9

Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst

reviewed

··· 1 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 2 + .. c:namespace:: MC 2 3 3 4 .. _media_ioc_device_info: 4 5 ··· 12 11 13 12 MEDIA_IOC_DEVICE_INFO - Query device information 14 13 15 15 - 16 14 Synopsis 17 15 ======== 18 16 19 19 - .. c:function:: int ioctl( int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp ) 20 20 - :name: MEDIA_IOC_DEVICE_INFO 17 17 + .. c:macro:: MEDIA_IOC_DEVICE_INFO 21 18 19 19 + ``int ioctl(int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp)`` 22 20 23 21 Arguments 24 22 ========= 25 23 26 24 ``fd`` 27 27 - File descriptor returned by :ref:`open() <media-func-open>`. 25 25 + File descriptor returned by :c:func:`open()`. 28 26 29 27 ``argp`` 30 28 Pointer to struct :c:type:`media_device_info`. 31 31 - 32 29 33 30 Description 34 31 =========== ··· 37 38 fills the structure and returns the information to the application. The 38 39 ioctl never fails. 39 40 40 40 - 41 41 .. c:type:: media_device_info 42 42 43 43 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| ··· 45 47 :header-rows: 0 46 48 :stub-columns: 0 47 49 :widths: 1 1 2 48 48 - 49 50 50 51 * - char 51 52 - ``driver``\ [16] ··· 91 94 - Reserved for future extensions. Drivers and applications must set 92 95 this array to zero. 93 96 94 94 - 95 97 The ``serial`` and ``bus_info`` fields can be used to distinguish 96 98 between multiple instances of otherwise identical hardware. The serial 97 99 number takes precedence when provided and can be assumed to be unique. 98 100 If the serial number is an empty string, the ``bus_info`` field can be 99 101 used instead. The ``bus_info`` field is guaranteed to be unique, but can 100 102 vary across reboots or device unplug/replug. 101 101 - 102 103 103 104 Return Value 104 105 ============

+4 -7

Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst

reviewed

··· 1 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 2 + .. c:namespace:: MC 2 3 3 4 .. _media_ioc_enum_entities: 4 5 ··· 12 11 13 12 MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties 14 13 15 15 - 16 14 Synopsis 17 15 ======== 18 16 19 19 - .. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp ) 20 20 - :name: MEDIA_IOC_ENUM_ENTITIES 17 17 + .. c:macro:: MEDIA_IOC_ENUM_ENTITIES 21 18 19 19 + ``int ioctl(int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp)`` 22 20 23 21 Arguments 24 22 ========= 25 23 26 24 ``fd`` 27 27 - File descriptor returned by :ref:`open() <media-func-open>`. 25 25 + File descriptor returned by :c:func:`open()`. 28 26 29 27 ``argp`` 30 28 Pointer to struct :c:type:`media_entity_desc`. 31 31 - 32 29 33 30 Description 34 31 =========== ··· 47 48 Entity IDs can be non-contiguous. Applications must *not* try to 48 49 enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing 49 50 id's until they get an error. 50 50 - 51 51 52 52 .. c:type:: media_entity_desc 53 53 ··· 133 135 - 134 136 * - } 135 137 - 136 136 - 137 138 138 139 Return Value 139 140 ============

+4 -9

Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst

reviewed

··· 1 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 2 + .. c:namespace:: MC 2 3 3 4 .. _media_ioc_enum_links: 4 5 ··· 12 11 13 12 MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity 14 13 15 15 - 16 14 Synopsis 17 15 ======== 18 16 19 19 - .. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp ) 20 20 - :name: MEDIA_IOC_ENUM_LINKS 17 17 + .. c:macro:: MEDIA_IOC_ENUM_LINKS 21 18 19 19 + ``int ioctl(int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp)`` 22 20 23 21 Arguments 24 22 ========= 25 23 26 24 ``fd`` 27 27 - File descriptor returned by :ref:`open() <media-func-open>`. 25 25 + File descriptor returned by :c:func:`open()`. 28 26 29 27 ``argp`` 30 28 Pointer to struct :c:type:`media_links_enum`. 31 31 - 32 29 33 30 Description 34 31 =========== ··· 51 52 52 53 Only forward links that originate at one of the entity's source pads are 53 54 returned during the enumeration process. 54 54 - 55 55 56 56 .. c:type:: media_links_enum 57 57 ··· 80 82 - Reserved for future extensions. Drivers and applications must set 81 83 the array to zero. 82 84 83 83 - 84 85 .. c:type:: media_pad_desc 85 86 86 87 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| ··· 107 110 the array to zero. 108 111 109 112 110 110 - 111 113 .. c:type:: media_link_desc 112 114 113 115 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| ··· 132 136 - ``reserved[2]`` 133 137 - Reserved for future extensions. Drivers and applications must set 134 138 the array to zero. 135 135 - 136 139 137 140 Return Value 138 141 ============

+4 -10

Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst

reviewed

··· 1 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 2 + .. c:namespace:: MC 2 3 3 4 .. _media_ioc_g_topology: 4 5 ··· 12 11 13 12 MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties 14 13 15 15 - 16 14 Synopsis 17 15 ======== 18 16 19 19 - .. c:function:: int ioctl( int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp ) 20 20 - :name: MEDIA_IOC_G_TOPOLOGY 17 17 + .. c:macro:: MEDIA_IOC_G_TOPOLOGY 21 18 19 19 + ``int ioctl(int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp)`` 22 20 23 21 Arguments 24 22 ========= 25 23 26 24 ``fd`` 27 27 - File descriptor returned by :ref:`open() <media-func-open>`. 25 25 + File descriptor returned by :c:func:`open()`. 28 26 29 27 ``argp`` 30 28 Pointer to struct :c:type:`media_v2_topology`. 31 31 - 32 29 33 30 Description 34 31 =========== ··· 119 120 converted to a 64-bits integer. It can be zero. if zero, the ioctl 120 121 won't store the links. It will just update ``num_links`` 121 122 122 122 - 123 123 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| 124 124 125 125 .. c:type:: media_v2_entity ··· 156 158 - Reserved for future extensions. Drivers and applications must set 157 159 this array to zero. 158 160 159 159 - 160 161 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| 161 162 162 163 .. c:type:: media_v2_interface ··· 188 191 - ``devnode`` 189 192 - Used only for device node interfaces. See 190 193 :c:type:`media_v2_intf_devnode` for details. 191 191 - 192 194 193 195 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| 194 196 ··· 241 245 - Reserved for future extensions. Drivers and applications must set 242 246 this array to zero. 243 247 244 244 - 245 248 .. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| 246 249 247 250 .. c:type:: media_v2_link ··· 276 281 - ``reserved``\ [6] 277 282 - Reserved for future extensions. Drivers and applications must set 278 283 this array to zero. 279 279 - 280 284 281 285 Return Value 282 286 ============

+5 -6

Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst

reviewed

··· 1 1 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later 2 2 + .. c:namespace:: MC 2 3 3 4 .. _media_ioc_request_alloc: 4 5 ··· 12 11 13 12 MEDIA_IOC_REQUEST_ALLOC - Allocate a request 14 13 15 15 - 16 14 Synopsis 17 15 ======== 18 16 19 19 - .. c:function:: int ioctl( int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp ) 20 20 - :name: MEDIA_IOC_REQUEST_ALLOC 17 17 + .. c:macro:: MEDIA_IOC_REQUEST_ALLOC 21 18 19 19 + ``int ioctl(int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp)`` 22 20 23 21 Arguments 24 22 ========= 25 23 26 24 ``fd`` 27 27 - File descriptor returned by :ref:`open() <media-func-open>`. 25 25 + File descriptor returned by :c:func:`open()`. 28 26 29 27 ``argp`` 30 28 Pointer to an integer. 31 31 - 32 29 33 30 Description 34 31 =========== ··· 50 51 for the request to complete. 51 52 52 53 The request will remain allocated until all the file descriptors associated 53 53 - with it are closed by :ref:`close() <request-func-close>` and the driver no 54 54 + with it are closed by :c:func:`close()` and the driver no 54 55 longer uses the request internally. See also 55 56 :ref:`here <media-request-life-time>` for more information. 56 57

+4 -6

Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst

reviewed

··· 1 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 2 + .. c:namespace:: MC 2 3 3 4 .. _media_ioc_setup_link: 4 5 ··· 12 11 13 12 MEDIA_IOC_SETUP_LINK - Modify the properties of a link 14 13 15 15 - 16 14 Synopsis 17 15 ======== 18 16 19 19 - .. c:function:: int ioctl( int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp ) 20 20 - :name: MEDIA_IOC_SETUP_LINK 17 17 + .. c:macro:: MEDIA_IOC_SETUP_LINK 21 18 19 19 + ``int ioctl(int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp)`` 22 20 23 21 Arguments 24 22 ========= 25 23 26 24 ``fd`` 27 27 - File descriptor returned by :ref:`open() <media-func-open>`. 25 25 + File descriptor returned by :c:func:`open()`. 28 26 29 27 ``argp`` 30 28 Pointer to struct :c:type:`media_link_desc`. 31 31 - 32 29 33 30 Description 34 31 =========== ··· 51 52 52 53 If the specified link can't be found the driver returns with an ``EINVAL`` 53 54 error code. 54 54 - 55 55 56 56 Return Value 57 57 ============

+3 -4

Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst

reviewed

··· 1 1 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later 2 2 + .. c:namespace:: MC 2 3 3 4 .. _media_request_ioc_queue: 4 5 ··· 12 11 13 12 MEDIA_REQUEST_IOC_QUEUE - Queue a request 14 13 15 15 - 16 14 Synopsis 17 15 ======== 18 16 19 19 - .. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_QUEUE ) 20 20 - :name: MEDIA_REQUEST_IOC_QUEUE 17 17 + .. c:macro:: MEDIA_REQUEST_IOC_QUEUE 21 18 19 19 + ``int ioctl(int request_fd, MEDIA_REQUEST_IOC_QUEUE)`` 22 20 23 21 Arguments 24 22 ========= 25 23 26 24 ``request_fd`` 27 25 File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. 28 28 - 29 26 30 27 Description 31 28 ===========

+4 -4

Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst

reviewed

··· 1 1 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later 2 2 + .. c:namespace:: MC 2 3 3 4 .. _media_request_ioc_reinit: 4 5 ··· 12 11 13 12 MEDIA_REQUEST_IOC_REINIT - Re-initialize a request 14 13 15 15 - 16 14 Synopsis 17 15 ======== 18 16 19 19 - .. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_REINIT ) 20 20 - :name: MEDIA_REQUEST_IOC_REINIT 17 17 + .. c:macro:: MEDIA_REQUEST_IOC_REINIT 21 18 19 19 + ``int ioctl(int request_fd, MEDIA_REQUEST_IOC_REINIT)`` 22 20 23 21 Arguments 24 22 ========= ··· 33 33 request. 34 34 35 35 Re-initializing a request will clear any existing data from the request. 36 36 - This avoids having to :ref:`close() <request-func-close>` a completed 36 36 + This avoids having to :c:func:`close()` a completed 37 37 request and allocate a new request. Instead the completed request can just 38 38 be re-initialized and it is ready to be used again. 39 39

+3 -2

Documentation/userspace-api/media/mediactl/request-api.rst

reviewed

··· 1 1 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later 2 2 + .. c:namespace:: MC 2 3 3 4 .. _media-request-api: 4 5 ··· 94 93 Setting the same control through a request and also directly can lead to 95 94 undefined behavior! 96 95 97 97 - User-space can :ref:`poll() <request-func-poll>` a request file descriptor in 96 96 + User-space can :c:func:`poll()` a request file descriptor in 98 97 order to wait until the request completes. A request is considered complete 99 98 once all its associated buffers are available for dequeuing and all the 100 99 associated controls have been updated with the values at the time of completion. ··· 116 115 ------------------------- 117 116 118 117 Finally, a completed request can either be discarded or be reused. Calling 119 119 - :ref:`close() <request-func-close>` on a request file descriptor will make 118 118 + :c:func:`close()` on a request file descriptor will make 120 119 that file descriptor unusable and the request will be freed once it is no 121 120 longer in use by the kernel. That is, if the request is queued and then the 122 121 file descriptor is closed, then it won't be freed until the driver completed

+2 -6

Documentation/userspace-api/media/mediactl/request-func-close.rst

reviewed

··· 1 1 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later 2 2 + .. c:namespace:: MC.request 2 3 3 4 .. _request-func-close: 4 5 ··· 12 11 13 12 request-close - Close a request file descriptor 14 13 15 15 - 16 14 Synopsis 17 15 ======== 18 16 ··· 19 19 20 20 #include <unistd.h> 21 21 22 22 - 23 22 .. c:function:: int close( int fd ) 24 24 - :name: req-close 25 23 26 24 Arguments 27 25 ========= 28 26 29 27 ``fd`` 30 28 File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. 31 31 - 32 29 33 30 Description 34 31 =========== ··· 35 38 and the driver has completed the request. 36 39 See :ref:`here <media-request-life-time>` for more information. 37 40 38 38 - 39 41 Return Value 40 42 ============ 41 43 42 42 - :ref:`close() <request-func-close>` returns 0 on success. On error, -1 is 44 44 + :c:func:`close()` returns 0 on success. On error, -1 is 43 45 returned, and ``errno`` is set appropriately. Possible error codes are: 44 46 45 47 EBADF

+2 -6

Documentation/userspace-api/media/mediactl/request-func-ioctl.rst

reviewed

··· 1 1 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later 2 2 + .. c:namespace:: MC 2 3 3 4 .. _request-func-ioctl: 4 5 ··· 12 11 13 12 request-ioctl - Control a request file descriptor 14 13 15 15 - 16 14 Synopsis 17 15 ======== 18 16 ··· 19 19 20 20 #include <sys/ioctl.h> 21 21 22 22 - 23 23 - .. c:function:: int ioctl( int fd, int cmd, void *argp ) 24 24 - :name: req-ioctl 22 22 + ``int ioctl(int fd, int cmd, void *argp)`` 25 23 26 24 Arguments 27 25 ========= ··· 33 35 34 36 ``argp`` 35 37 Pointer to a request-specific structure. 36 36 - 37 38 38 39 Description 39 40 =========== ··· 48 51 their parameters are located in the media.h header file. All request ioctl 49 52 commands, their respective function and parameters are specified in 50 53 :ref:`media-user-func`. 51 51 - 52 54 53 55 Return Value 54 56 ============

+4 -8

Documentation/userspace-api/media/mediactl/request-func-poll.rst

reviewed

··· 1 1 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later 2 2 + .. c:namespace:: MC 2 3 3 4 .. _request-func-poll: 4 5 ··· 12 11 13 12 request-poll - Wait for some event on a file descriptor 14 13 15 15 - 16 14 Synopsis 17 15 ======== 18 16 ··· 19 19 20 20 #include <sys/poll.h> 21 21 22 22 - 23 22 .. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout ) 24 24 - :name: request-poll 25 23 26 24 Arguments 27 25 ========= ··· 33 35 ``timeout`` 34 36 Timeout to wait for events 35 37 36 36 - 37 38 Description 38 39 =========== 39 40 40 40 - With the :c:func:`poll() <request-func-poll>` function applications can wait 41 41 + With the :c:func:`poll()` function applications can wait 41 42 for a request to complete. 42 43 43 43 - On success :c:func:`poll() <request-func-poll>` returns the number of file 44 44 + On success :c:func:`poll()` returns the number of file 44 45 descriptors that have been selected (that is, file descriptors for which the 45 46 ``revents`` field of the respective struct :c:type:`pollfd` 46 47 is non-zero). Request file descriptor set the ``POLLPRI`` flag in ``revents`` ··· 50 53 Attempting to poll for a request that is not yet queued will 51 54 set the ``POLLERR`` flag in ``revents``. 52 55 53 53 - 54 56 Return Value 55 57 ============ 56 58 57 57 - On success, :c:func:`poll() <request-func-poll>` returns the number of 59 59 + On success, :c:func:`poll()` returns the number of 58 60 structures which have non-zero ``revents`` fields, or zero if the call 59 61 timed out. On error -1 is returned, and the ``errno`` variable is set 60 62 appropriately: