0001 .. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: MC
0003
0004 .. _media_request_ioc_queue:
0005
0006 *****************************
0007 ioctl MEDIA_REQUEST_IOC_QUEUE
0008 *****************************
0009
0010 Name
0011 ====
0012
0013 MEDIA_REQUEST_IOC_QUEUE - Queue a request
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: MEDIA_REQUEST_IOC_QUEUE
0019
0020 ``int ioctl(int request_fd, MEDIA_REQUEST_IOC_QUEUE)``
0021
0022 Arguments
0023 =========
0024
0025 ``request_fd``
0026 File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.
0027
0028 Description
0029 ===========
0030
0031 If the media device supports :ref:`requests <media-request-api>`, then
0032 this request ioctl can be used to queue a previously allocated request.
0033
0034 If the request was successfully queued, then the file descriptor can be
0035 :ref:`polled <request-func-poll>` to wait for the request to complete.
0036
0037 If the request was already queued before, then ``EBUSY`` is returned.
0038 Other errors can be returned if the contents of the request contained
0039 invalid or inconsistent data, see the next section for a list of
0040 common error codes. On error both the request and driver state are unchanged.
0041
0042 Once a request is queued, then the driver is required to gracefully handle
0043 errors that occur when the request is applied to the hardware. The
0044 exception is the ``EIO`` error which signals a fatal error that requires
0045 the application to stop streaming to reset the hardware state.
0046
0047 It is not allowed to mix queuing requests with queuing buffers directly
0048 (without a request). ``EBUSY`` will be returned if the first buffer was
0049 queued directly and you next try to queue a request, or vice versa.
0050
0051 A request must contain at least one buffer, otherwise this ioctl will
0052 return an ``ENOENT`` error.
0053
0054 Return Value
0055 ============
0056
0057 On success 0 is returned, on error -1 and the ``errno`` variable is set
0058 appropriately. The generic error codes are described at the
0059 :ref:`Generic Error Codes <gen-errors>` chapter.
0060
0061 EBUSY
0062 The request was already queued or the application queued the first
0063 buffer directly, but later attempted to use a request. It is not permitted
0064 to mix the two APIs.
0065 ENOENT
0066 The request did not contain any buffers. All requests are required
0067 to have at least one buffer. This can also be returned if some required
0068 configuration is missing in the request.
0069 ENOMEM
0070 Out of memory when allocating internal data structures for this
0071 request.
0072 EINVAL
0073 The request has invalid data.
0074 EIO
0075 The hardware is in a bad state. To recover, the application needs to
0076 stop streaming to reset the hardware state and then try to restart
0077 streaming.
