Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst

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