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