78 lines · plain
1.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later2.. c:namespace:: MC3 4.. _media_request_ioc_queue:5 6*****************************7ioctl MEDIA_REQUEST_IOC_QUEUE8*****************************9 10Name11====12 13MEDIA_REQUEST_IOC_QUEUE - Queue a request14 15Synopsis16========17 18.. c:macro:: MEDIA_REQUEST_IOC_QUEUE19 20``int ioctl(int request_fd, MEDIA_REQUEST_IOC_QUEUE)``21 22Arguments23=========24 25``request_fd``26 File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.27 28Description29===========30 31If the media device supports :ref:`requests <media-request-api>`, then32this request ioctl can be used to queue a previously allocated request.33 34If the request was successfully queued, then the file descriptor can be35: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 contained39invalid or inconsistent data, see the next section for a list of40common 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 handle43errors that occur when the request is applied to the hardware. The44exception is the ``EIO`` error which signals a fatal error that requires45the application to stop streaming to reset the hardware state.46 47It is not allowed to mix queuing requests with queuing buffers directly48(without a request). ``EBUSY`` will be returned if the first buffer was49queued directly and you next try to queue a request, or vice versa.50 51A request must contain at least one buffer, otherwise this ioctl will52return an ``ENOENT`` error.53 54Return Value55============56 57On success 0 is returned, on error -1 and the ``errno`` variable is set58appropriately. The generic error codes are described at the59:ref:`Generic Error Codes <gen-errors>` chapter.60 61EBUSY62 The request was already queued or the application queued the first63 buffer directly, but later attempted to use a request. It is not permitted64 to mix the two APIs.65ENOENT66 The request did not contain any buffers. All requests are required67 to have at least one buffer. This can also be returned if some required68 configuration is missing in the request.69ENOMEM70 Out of memory when allocating internal data structures for this71 request.72EINVAL73 The request has invalid data.74EIO75 The hardware is in a bad state. To recover, the application needs to76 stop streaming to reset the hardware state and then try to restart77 streaming.78