1*4882a593Smuzhiyun.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later 2*4882a593Smuzhiyun.. c:namespace:: MC 3*4882a593Smuzhiyun 4*4882a593Smuzhiyun.. _media_request_ioc_queue: 5*4882a593Smuzhiyun 6*4882a593Smuzhiyun***************************** 7*4882a593Smuzhiyunioctl MEDIA_REQUEST_IOC_QUEUE 8*4882a593Smuzhiyun***************************** 9*4882a593Smuzhiyun 10*4882a593SmuzhiyunName 11*4882a593Smuzhiyun==== 12*4882a593Smuzhiyun 13*4882a593SmuzhiyunMEDIA_REQUEST_IOC_QUEUE - Queue a request 14*4882a593Smuzhiyun 15*4882a593SmuzhiyunSynopsis 16*4882a593Smuzhiyun======== 17*4882a593Smuzhiyun 18*4882a593Smuzhiyun.. c:macro:: MEDIA_REQUEST_IOC_QUEUE 19*4882a593Smuzhiyun 20*4882a593Smuzhiyun``int ioctl(int request_fd, MEDIA_REQUEST_IOC_QUEUE)`` 21*4882a593Smuzhiyun 22*4882a593SmuzhiyunArguments 23*4882a593Smuzhiyun========= 24*4882a593Smuzhiyun 25*4882a593Smuzhiyun``request_fd`` 26*4882a593Smuzhiyun File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. 27*4882a593Smuzhiyun 28*4882a593SmuzhiyunDescription 29*4882a593Smuzhiyun=========== 30*4882a593Smuzhiyun 31*4882a593SmuzhiyunIf the media device supports :ref:`requests <media-request-api>`, then 32*4882a593Smuzhiyunthis request ioctl can be used to queue a previously allocated request. 33*4882a593Smuzhiyun 34*4882a593SmuzhiyunIf the request was successfully queued, then the file descriptor can be 35*4882a593Smuzhiyun:ref:`polled <request-func-poll>` to wait for the request to complete. 36*4882a593Smuzhiyun 37*4882a593SmuzhiyunIf the request was already queued before, then ``EBUSY`` is returned. 38*4882a593SmuzhiyunOther errors can be returned if the contents of the request contained 39*4882a593Smuzhiyuninvalid or inconsistent data, see the next section for a list of 40*4882a593Smuzhiyuncommon error codes. On error both the request and driver state are unchanged. 41*4882a593Smuzhiyun 42*4882a593SmuzhiyunOnce a request is queued, then the driver is required to gracefully handle 43*4882a593Smuzhiyunerrors that occur when the request is applied to the hardware. The 44*4882a593Smuzhiyunexception is the ``EIO`` error which signals a fatal error that requires 45*4882a593Smuzhiyunthe application to stop streaming to reset the hardware state. 46*4882a593Smuzhiyun 47*4882a593SmuzhiyunIt is not allowed to mix queuing requests with queuing buffers directly 48*4882a593Smuzhiyun(without a request). ``EBUSY`` will be returned if the first buffer was 49*4882a593Smuzhiyunqueued directly and you next try to queue a request, or vice versa. 50*4882a593Smuzhiyun 51*4882a593SmuzhiyunA request must contain at least one buffer, otherwise this ioctl will 52*4882a593Smuzhiyunreturn an ``ENOENT`` error. 53*4882a593Smuzhiyun 54*4882a593SmuzhiyunReturn Value 55*4882a593Smuzhiyun============ 56*4882a593Smuzhiyun 57*4882a593SmuzhiyunOn success 0 is returned, on error -1 and the ``errno`` variable is set 58*4882a593Smuzhiyunappropriately. The generic error codes are described at the 59*4882a593Smuzhiyun:ref:`Generic Error Codes <gen-errors>` chapter. 60*4882a593Smuzhiyun 61*4882a593SmuzhiyunEBUSY 62*4882a593Smuzhiyun The request was already queued or the application queued the first 63*4882a593Smuzhiyun buffer directly, but later attempted to use a request. It is not permitted 64*4882a593Smuzhiyun to mix the two APIs. 65*4882a593SmuzhiyunENOENT 66*4882a593Smuzhiyun The request did not contain any buffers. All requests are required 67*4882a593Smuzhiyun to have at least one buffer. This can also be returned if some required 68*4882a593Smuzhiyun configuration is missing in the request. 69*4882a593SmuzhiyunENOMEM 70*4882a593Smuzhiyun Out of memory when allocating internal data structures for this 71*4882a593Smuzhiyun request. 72*4882a593SmuzhiyunEINVAL 73*4882a593Smuzhiyun The request has invalid data. 74*4882a593SmuzhiyunEIO 75*4882a593Smuzhiyun The hardware is in a bad state. To recover, the application needs to 76*4882a593Smuzhiyun stop streaming to reset the hardware state and then try to restart 77*4882a593Smuzhiyun streaming. 78