Documentation/media/uapi/mediactl/media-request-ioc-queue.rst

   1 .. This file is dual-licensed: you can use it either under the terms
   2 .. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this
   3 .. dual licensing only applies to this file, and not this project as a
   4 .. whole.
   5 ..
   6 .. a) This file is free software; you can redistribute it and/or
   7 ..    modify it under the terms of the GNU General Public License as
   8 ..    published by the Free Software Foundation version 2 of
   9 ..    the License.
  10 ..
  11 ..    This file is distributed in the hope that it will be useful,
  12 ..    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 ..    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 ..    GNU General Public License for more details.
  15 ..
  16 .. Or, alternatively,
  17 ..
  18 .. b) Permission is granted to copy, distribute and/or modify this
  19 ..    document under the terms of the GNU Free Documentation License,
  20 ..    Version 1.1 or any later version published by the Free Software
  21 ..    Foundation, with no Invariant Sections, no Front-Cover Texts
  22 ..    and no Back-Cover Texts. A copy of the license is included at
  23 ..    Documentation/media/uapi/fdl-appendix.rst.
  24 ..
  25 .. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections
  26
  27 .. _media_request_ioc_queue:
  28
  29 *****************************
  30 ioctl MEDIA_REQUEST_IOC_QUEUE
  31 *****************************
  32
  33 Name
  34 ====
  35
  36 MEDIA_REQUEST_IOC_QUEUE - Queue a request
  37
  38
  39 Synopsis
  40 ========
  41
  42 .. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_QUEUE )
  43     :name: MEDIA_REQUEST_IOC_QUEUE
  44
  45
  46 Arguments
  47 =========
  48
  49 ``request_fd``
  50     File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.
  51
  52
  53 Description
  54 ===========
  55
  56 If the media device supports :ref:`requests <media-request-api>`, then
  57 this request ioctl can be used to queue a previously allocated request.
  58
  59 If the request was successfully queued, then the file descriptor can be
  60 :ref:`polled <request-func-poll>` to wait for the request to complete.
  61
  62 If the request was already queued before, then ``EBUSY`` is returned.
  63 Other errors can be returned if the contents of the request contained
  64 invalid or inconsistent data, see the next section for a list of
  65 common error codes. On error both the request and driver state are unchanged.
  66
  67 Once a request is queued, then the driver is required to gracefully handle
  68 errors that occur when the request is applied to the hardware. The
  69 exception is the ``EIO`` error which signals a fatal error that requires
  70 the application to stop streaming to reset the hardware state.
  71
  72 It is not allowed to mix queuing requests with queuing buffers directly
  73 (without a request). ``EBUSY`` will be returned if the first buffer was
  74 queued directly and you next try to queue a request, or vice versa.
  75
  76 A request must contain at least one buffer, otherwise this ioctl will
  77 return an ``ENOENT`` error.
  78
  79 Return Value
  80 ============
  81
  82 On success 0 is returned, on error -1 and the ``errno`` variable is set
  83 appropriately. The generic error codes are described at the
  84 :ref:`Generic Error Codes <gen-errors>` chapter.
  85
  86 EBUSY
  87     The request was already queued or the application queued the first
  88     buffer directly, but later attempted to use a request. It is not permitted
  89     to mix the two APIs.
  90 ENOENT
  91     The request did not contain any buffers. All requests are required
  92     to have at least one buffer. This can also be returned if some required
  93     configuration is missing in the request.
  94 ENOMEM
  95     Out of memory when allocating internal data structures for this
  96     request.
  97 EINVAL
  98     The request has invalid data.
  99 EIO
 100     The hardware is in a bad state. To recover, the application needs to
 101     stop streaming to reset the hardware state and then try to restart
 102     streaming.