1 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections
3 .. _media_request_ioc_queue:
5 *****************************
6 ioctl MEDIA_REQUEST_IOC_QUEUE
7 *****************************
12 MEDIA_REQUEST_IOC_QUEUE - Queue a request
18 .. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_QUEUE )
19 :name: MEDIA_REQUEST_IOC_QUEUE
26 File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.
32 If the media device supports :ref:`requests <media-request-api>`, then
33 this request ioctl can be used to queue a previously allocated request.
35 If the request was successfully queued, then the file descriptor can be
36 :ref:`polled <request-func-poll>` to wait for the request to complete.
38 If the request was already queued before, then ``EBUSY`` is returned.
39 Other errors can be returned if the contents of the request contained
40 invalid or inconsistent data, see the next section for a list of
41 common error codes. On error both the request and driver state are unchanged.
43 Once a request is queued, then the driver is required to gracefully handle
44 errors that occur when the request is applied to the hardware. The
45 exception is the ``EIO`` error which signals a fatal error that requires
46 the application to stop streaming to reset the hardware state.
48 It is not allowed to mix queuing requests with queuing buffers directly
49 (without a request). ``EBUSY`` will be returned if the first buffer was
50 queued directly and you next try to queue a request, or vice versa.
52 A request must contain at least one buffer, otherwise this ioctl will
53 return an ``ENOENT`` error.
58 On success 0 is returned, on error -1 and the ``errno`` variable is set
59 appropriately. The generic error codes are described at the
60 :ref:`Generic Error Codes <gen-errors>` chapter.
63 The request was already queued or the application queued the first
64 buffer directly, but later attempted to use a request. It is not permitted
67 The request did not contain any buffers. All requests are required
68 to have at least one buffer. This can also be returned if some required
69 configuration is missing in the request.
71 Out of memory when allocating internal data structures for this
74 The request has invalid data.
76 The hardware is in a bad state. To recover, the application needs to
77 stop streaming to reset the hardware state and then try to restart