1 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1. !! 1 .. This file is dual-licensed: you can use it either under the terms
2 .. c:namespace:: MC !! 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
3 26
4 .. _media_request_ioc_queue: 27 .. _media_request_ioc_queue:
5 28
6 ***************************** 29 *****************************
7 ioctl MEDIA_REQUEST_IOC_QUEUE 30 ioctl MEDIA_REQUEST_IOC_QUEUE
8 ***************************** 31 *****************************
9 32
10 Name 33 Name
11 ==== 34 ====
12 35
13 MEDIA_REQUEST_IOC_QUEUE - Queue a request 36 MEDIA_REQUEST_IOC_QUEUE - Queue a request
14 37
>> 38
15 Synopsis 39 Synopsis
16 ======== 40 ========
17 41
18 .. c:macro:: MEDIA_REQUEST_IOC_QUEUE !! 42 .. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_QUEUE )
>> 43 :name: MEDIA_REQUEST_IOC_QUEUE
19 44
20 ``int ioctl(int request_fd, MEDIA_REQUEST_IOC_ <<
21 45
22 Arguments 46 Arguments
23 ========= 47 =========
24 48
25 ``request_fd`` 49 ``request_fd``
26 File descriptor returned by :ref:`MEDIA_IO 50 File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.
>> 51
27 52
28 Description 53 Description
29 =========== 54 ===========
30 55
31 If the media device supports :ref:`requests <m 56 If the media device supports :ref:`requests <media-request-api>`, then
32 this request ioctl can be used to queue a prev 57 this request ioctl can be used to queue a previously allocated request.
33 58
34 If the request was successfully queued, then t 59 If the request was successfully queued, then the file descriptor can be
35 :ref:`polled <request-func-poll>` to wait for 60 :ref:`polled <request-func-poll>` to wait for the request to complete.
36 61
37 If the request was already queued before, then 62 If the request was already queued before, then ``EBUSY`` is returned.
38 Other errors can be returned if the contents o 63 Other errors can be returned if the contents of the request contained
39 invalid or inconsistent data, see the next sec 64 invalid or inconsistent data, see the next section for a list of
40 common error codes. On error both the request 65 common error codes. On error both the request and driver state are unchanged.
41 66
42 Once a request is queued, then the driver is r 67 Once a request is queued, then the driver is required to gracefully handle
43 errors that occur when the request is applied 68 errors that occur when the request is applied to the hardware. The
44 exception is the ``EIO`` error which signals a 69 exception is the ``EIO`` error which signals a fatal error that requires
45 the application to stop streaming to reset the 70 the application to stop streaming to reset the hardware state.
46 71
47 It is not allowed to mix queuing requests with 72 It is not allowed to mix queuing requests with queuing buffers directly
48 (without a request). ``EBUSY`` will be returne 73 (without a request). ``EBUSY`` will be returned if the first buffer was
49 queued directly and you next try to queue a re 74 queued directly and you next try to queue a request, or vice versa.
50 75
51 A request must contain at least one buffer, ot 76 A request must contain at least one buffer, otherwise this ioctl will
52 return an ``ENOENT`` error. 77 return an ``ENOENT`` error.
53 78
54 Return Value 79 Return Value
55 ============ 80 ============
56 81
57 On success 0 is returned, on error -1 and the 82 On success 0 is returned, on error -1 and the ``errno`` variable is set
58 appropriately. The generic error codes are des 83 appropriately. The generic error codes are described at the
59 :ref:`Generic Error Codes <gen-errors>` chapte 84 :ref:`Generic Error Codes <gen-errors>` chapter.
60 85
61 EBUSY 86 EBUSY
62 The request was already queued or the appl 87 The request was already queued or the application queued the first
63 buffer directly, but later attempted to us 88 buffer directly, but later attempted to use a request. It is not permitted
64 to mix the two APIs. 89 to mix the two APIs.
65 ENOENT 90 ENOENT
66 The request did not contain any buffers. A 91 The request did not contain any buffers. All requests are required
67 to have at least one buffer. This can also 92 to have at least one buffer. This can also be returned if some required
68 configuration is missing in the request. 93 configuration is missing in the request.
69 ENOMEM 94 ENOMEM
70 Out of memory when allocating internal dat 95 Out of memory when allocating internal data structures for this
71 request. 96 request.
72 EINVAL 97 EINVAL
73 The request has invalid data. 98 The request has invalid data.
74 EIO 99 EIO
75 The hardware is in a bad state. To recover 100 The hardware is in a bad state. To recover, the application needs to
76 stop streaming to reset the hardware state 101 stop streaming to reset the hardware state and then try to restart
77 streaming. 102 streaming.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.