]>
Commit | Line | Data |
---|---|---|
a7c3a0d5 MCC |
1 | .. This file is dual-licensed: you can use it either under the terms |
2 | .. of the GPL 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; either version 2 of | |
9 | .. the License, or (at your option) any later version. | |
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/media/uapi/fdl-appendix.rst. | |
24 | .. | |
25 | .. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections | |
cbb6a7f5 AC |
26 | |
27 | .. _media_request_ioc_queue: | |
28 | ||
29 | ***************************** | |
30 | ioctl MEDIA_REQUEST_IOC_QUEUE | |
31 | ***************************** | |
32 | ||
33 | Name | |
34 | ==== | |
35 | ||
36 | MEDIA_REQUEST_IOC_QUEUE - Queue a request | |
37 | ||
38 | ||
39 | Synopsis | |
40 | ======== | |
41 | ||
42 | .. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_QUEUE ) | |
43 | :name: MEDIA_REQUEST_IOC_QUEUE | |
44 | ||
45 | ||
46 | Arguments | |
47 | ========= | |
48 | ||
49 | ``request_fd`` | |
50 | File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. | |
51 | ||
52 | ||
53 | Description | |
54 | =========== | |
55 | ||
56 | If the media device supports :ref:`requests <media-request-api>`, then | |
57 | this request ioctl can be used to queue a previously allocated request. | |
58 | ||
59 | If 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 | ||
62 | If the request was already queued before, then ``EBUSY`` is returned. | |
63 | Other errors can be returned if the contents of the request contained | |
64 | invalid or inconsistent data, see the next section for a list of | |
65 | common error codes. On error both the request and driver state are unchanged. | |
66 | ||
cbb6a7f5 AC |
67 | Once a request is queued, then the driver is required to gracefully handle |
68 | errors that occur when the request is applied to the hardware. The | |
69 | exception is the ``EIO`` error which signals a fatal error that requires | |
70 | the application to stop streaming to reset the hardware state. | |
71 | ||
72 | It is not allowed to mix queuing requests with queuing buffers directly | |
15cd442e | 73 | (without a request). ``EBUSY`` will be returned if the first buffer was |
cbb6a7f5 AC |
74 | queued directly and you next try to queue a request, or vice versa. |
75 | ||
76 | A request must contain at least one buffer, otherwise this ioctl will | |
77 | return an ``ENOENT`` error. | |
78 | ||
79 | Return Value | |
80 | ============ | |
81 | ||
82 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
83 | appropriately. The generic error codes are described at the | |
84 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
85 | ||
86 | EBUSY | |
15cd442e HV |
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. | |
cbb6a7f5 AC |
90 | ENOENT |
91 | The request did not contain any buffers. All requests are required | |
d4215edb HV |
92 | to have at least one buffer. This can also be returned if some required |
93 | configuration is missing in the request. | |
cbb6a7f5 AC |
94 | ENOMEM |
95 | Out of memory when allocating internal data structures for this | |
96 | request. | |
97 | EINVAL | |
98 | The request has invalid data. | |
99 | EIO | |
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. |