1.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
2.. c:namespace:: MC
3
4.. _media_request_ioc_queue:
5
6*****************************
7ioctl MEDIA_REQUEST_IOC_QUEUE
8*****************************
9
10Name
11====
12
13MEDIA_REQUEST_IOC_QUEUE - Queue a request
14
15Synopsis
16========
17
18.. c:macro:: MEDIA_REQUEST_IOC_QUEUE
19
20``int ioctl(int request_fd, MEDIA_REQUEST_IOC_QUEUE)``
21
22Arguments
23=========
24
25``request_fd``
26    File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.
27
28Description
29===========
30
31If the media device supports :ref:`requests <media-request-api>`, then
32this request ioctl can be used to queue a previously allocated request.
33
34If the request was successfully queued, then the file descriptor can be
35:ref:`polled <request-func-poll>` to wait for the request to complete.
36
37If the request was already queued before, then ``EBUSY`` is returned.
38Other errors can be returned if the contents of the request contained
39invalid or inconsistent data, see the next section for a list of
40common error codes. On error both the request and driver state are unchanged.
41
42Once a request is queued, then the driver is required to gracefully handle
43errors that occur when the request is applied to the hardware. The
44exception is the ``EIO`` error which signals a fatal error that requires
45the application to stop streaming to reset the hardware state.
46
47It is not allowed to mix queuing requests with queuing buffers directly
48(without a request). ``EBUSY`` will be returned if the first buffer was
49queued directly and you next try to queue a request, or vice versa.
50
51A request must contain at least one buffer, otherwise this ioctl will
52return an ``ENOENT`` error.
53
54Return Value
55============
56
57On success 0 is returned, on error -1 and the ``errno`` variable is set
58appropriately. The generic error codes are described at the
59:ref:`Generic Error Codes <gen-errors>` chapter.
60
61EBUSY
62    The request was already queued or the application queued the first
63    buffer directly, but later attempted to use a request. It is not permitted
64    to mix the two APIs.
65ENOENT
66    The request did not contain any buffers. All requests are required
67    to have at least one buffer. This can also be returned if some required
68    configuration is missing in the request.
69ENOMEM
70    Out of memory when allocating internal data structures for this
71    request.
72EINVAL
73    The request has invalid data.
74EIO
75    The hardware is in a bad state. To recover, the application needs to
76    stop streaming to reset the hardware state and then try to restart
77    streaming.
78