1.. This file is dual-licensed: you can use it either under the terms 2.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this 3.. dual licensing only applies to this file, and not this project as a 4.. whole. 5.. 6.. a) This file is free software; you can redistribute it and/or 7.. modify it under the terms of the GNU General Public License as 8.. published by the Free Software Foundation version 2 of 9.. the License. 10.. 11.. This file is distributed in the hope that it will be useful, 12.. but WITHOUT ANY WARRANTY; without even the implied warranty of 13.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14.. GNU General Public License for more details. 15.. 16.. Or, alternatively, 17.. 18.. b) Permission is granted to copy, distribute and/or modify this 19.. document under the terms of the GNU Free Documentation License, 20.. Version 1.1 or any later version published by the Free Software 21.. Foundation, with no Invariant Sections, no Front-Cover Texts 22.. and no Back-Cover Texts. A copy of the license is included at 23.. Documentation/userspace-api/media/fdl-appendix.rst. 24.. 25.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections 26 27.. _media_request_ioc_queue: 28 29***************************** 30ioctl MEDIA_REQUEST_IOC_QUEUE 31***************************** 32 33Name 34==== 35 36MEDIA_REQUEST_IOC_QUEUE - Queue a request 37 38 39Synopsis 40======== 41 42.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_QUEUE ) 43 :name: MEDIA_REQUEST_IOC_QUEUE 44 45 46Arguments 47========= 48 49``request_fd`` 50 File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. 51 52 53Description 54=========== 55 56If the media device supports :ref:`requests <media-request-api>`, then 57this request ioctl can be used to queue a previously allocated request. 58 59If the request was successfully queued, then the file descriptor can be 60:ref:`polled <request-func-poll>` to wait for the request to complete. 61 62If the request was already queued before, then ``EBUSY`` is returned. 63Other errors can be returned if the contents of the request contained 64invalid or inconsistent data, see the next section for a list of 65common error codes. On error both the request and driver state are unchanged. 66 67Once a request is queued, then the driver is required to gracefully handle 68errors that occur when the request is applied to the hardware. The 69exception is the ``EIO`` error which signals a fatal error that requires 70the application to stop streaming to reset the hardware state. 71 72It is not allowed to mix queuing requests with queuing buffers directly 73(without a request). ``EBUSY`` will be returned if the first buffer was 74queued directly and you next try to queue a request, or vice versa. 75 76A request must contain at least one buffer, otherwise this ioctl will 77return an ``ENOENT`` error. 78 79Return Value 80============ 81 82On success 0 is returned, on error -1 and the ``errno`` variable is set 83appropriately. The generic error codes are described at the 84:ref:`Generic Error Codes <gen-errors>` chapter. 85 86EBUSY 87 The request was already queued or the application queued the first 88 buffer directly, but later attempted to use a request. It is not permitted 89 to mix the two APIs. 90ENOENT 91 The request did not contain any buffers. All requests are required 92 to have at least one buffer. This can also be returned if some required 93 configuration is missing in the request. 94ENOMEM 95 Out of memory when allocating internal data structures for this 96 request. 97EINVAL 98 The request has invalid data. 99EIO 100 The hardware is in a bad state. To recover, the application needs to 101 stop streaming to reset the hardware state and then try to restart 102 streaming. 103