18c2ecf20Sopenharmony_ci.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later 28c2ecf20Sopenharmony_ci.. c:namespace:: MC 38c2ecf20Sopenharmony_ci 48c2ecf20Sopenharmony_ci.. _media_request_ioc_queue: 58c2ecf20Sopenharmony_ci 68c2ecf20Sopenharmony_ci***************************** 78c2ecf20Sopenharmony_ciioctl MEDIA_REQUEST_IOC_QUEUE 88c2ecf20Sopenharmony_ci***************************** 98c2ecf20Sopenharmony_ci 108c2ecf20Sopenharmony_ciName 118c2ecf20Sopenharmony_ci==== 128c2ecf20Sopenharmony_ci 138c2ecf20Sopenharmony_ciMEDIA_REQUEST_IOC_QUEUE - Queue a request 148c2ecf20Sopenharmony_ci 158c2ecf20Sopenharmony_ciSynopsis 168c2ecf20Sopenharmony_ci======== 178c2ecf20Sopenharmony_ci 188c2ecf20Sopenharmony_ci.. c:macro:: MEDIA_REQUEST_IOC_QUEUE 198c2ecf20Sopenharmony_ci 208c2ecf20Sopenharmony_ci``int ioctl(int request_fd, MEDIA_REQUEST_IOC_QUEUE)`` 218c2ecf20Sopenharmony_ci 228c2ecf20Sopenharmony_ciArguments 238c2ecf20Sopenharmony_ci========= 248c2ecf20Sopenharmony_ci 258c2ecf20Sopenharmony_ci``request_fd`` 268c2ecf20Sopenharmony_ci File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. 278c2ecf20Sopenharmony_ci 288c2ecf20Sopenharmony_ciDescription 298c2ecf20Sopenharmony_ci=========== 308c2ecf20Sopenharmony_ci 318c2ecf20Sopenharmony_ciIf the media device supports :ref:`requests <media-request-api>`, then 328c2ecf20Sopenharmony_cithis request ioctl can be used to queue a previously allocated request. 338c2ecf20Sopenharmony_ci 348c2ecf20Sopenharmony_ciIf the request was successfully queued, then the file descriptor can be 358c2ecf20Sopenharmony_ci:ref:`polled <request-func-poll>` to wait for the request to complete. 368c2ecf20Sopenharmony_ci 378c2ecf20Sopenharmony_ciIf the request was already queued before, then ``EBUSY`` is returned. 388c2ecf20Sopenharmony_ciOther errors can be returned if the contents of the request contained 398c2ecf20Sopenharmony_ciinvalid or inconsistent data, see the next section for a list of 408c2ecf20Sopenharmony_cicommon error codes. On error both the request and driver state are unchanged. 418c2ecf20Sopenharmony_ci 428c2ecf20Sopenharmony_ciOnce a request is queued, then the driver is required to gracefully handle 438c2ecf20Sopenharmony_cierrors that occur when the request is applied to the hardware. The 448c2ecf20Sopenharmony_ciexception is the ``EIO`` error which signals a fatal error that requires 458c2ecf20Sopenharmony_cithe application to stop streaming to reset the hardware state. 468c2ecf20Sopenharmony_ci 478c2ecf20Sopenharmony_ciIt is not allowed to mix queuing requests with queuing buffers directly 488c2ecf20Sopenharmony_ci(without a request). ``EBUSY`` will be returned if the first buffer was 498c2ecf20Sopenharmony_ciqueued directly and you next try to queue a request, or vice versa. 508c2ecf20Sopenharmony_ci 518c2ecf20Sopenharmony_ciA request must contain at least one buffer, otherwise this ioctl will 528c2ecf20Sopenharmony_cireturn an ``ENOENT`` error. 538c2ecf20Sopenharmony_ci 548c2ecf20Sopenharmony_ciReturn Value 558c2ecf20Sopenharmony_ci============ 568c2ecf20Sopenharmony_ci 578c2ecf20Sopenharmony_ciOn success 0 is returned, on error -1 and the ``errno`` variable is set 588c2ecf20Sopenharmony_ciappropriately. The generic error codes are described at the 598c2ecf20Sopenharmony_ci:ref:`Generic Error Codes <gen-errors>` chapter. 608c2ecf20Sopenharmony_ci 618c2ecf20Sopenharmony_ciEBUSY 628c2ecf20Sopenharmony_ci The request was already queued or the application queued the first 638c2ecf20Sopenharmony_ci buffer directly, but later attempted to use a request. It is not permitted 648c2ecf20Sopenharmony_ci to mix the two APIs. 658c2ecf20Sopenharmony_ciENOENT 668c2ecf20Sopenharmony_ci The request did not contain any buffers. All requests are required 678c2ecf20Sopenharmony_ci to have at least one buffer. This can also be returned if some required 688c2ecf20Sopenharmony_ci configuration is missing in the request. 698c2ecf20Sopenharmony_ciENOMEM 708c2ecf20Sopenharmony_ci Out of memory when allocating internal data structures for this 718c2ecf20Sopenharmony_ci request. 728c2ecf20Sopenharmony_ciEINVAL 738c2ecf20Sopenharmony_ci The request has invalid data. 748c2ecf20Sopenharmony_ciEIO 758c2ecf20Sopenharmony_ci The hardware is in a bad state. To recover, the application needs to 768c2ecf20Sopenharmony_ci stop streaming to reset the hardware state and then try to restart 778c2ecf20Sopenharmony_ci streaming. 78