Documentation/media/uapi/mediactl/media-ioc-request-alloc.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_ioc_request_alloc:
  28
  29 *****************************
  30 ioctl MEDIA_IOC_REQUEST_ALLOC
  31 *****************************
  32
  33 Name
  34 ====
  35
  36 MEDIA_IOC_REQUEST_ALLOC - Allocate a request
  37
  38
  39 Synopsis
  40 ========
  41
  42 .. c:function:: int ioctl( int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp )
  43     :name: MEDIA_IOC_REQUEST_ALLOC
  44
  45
  46 Arguments
  47 =========
  48
  49 ``fd``
  50     File descriptor returned by :ref:`open() <media-func-open>`.
  51
  52 ``argp``
  53     Pointer to an integer.
  54
  55
  56 Description
  57 ===========
  58
  59 If the media device supports :ref:`requests <media-request-api>`, then
  60 this ioctl can be used to allocate a request. If it is not supported, then
  61 ``errno`` is set to ``ENOTTY``. A request is accessed through a file descriptor
  62 that is returned in ``*argp``.
  63
  64 If the request was successfully allocated, then the request file descriptor
  65 can be passed to the :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
  66 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
  67 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and
  68 :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctls.
  69
  70 In addition, the request can be queued by calling
  71 :ref:`MEDIA_REQUEST_IOC_QUEUE` and re-initialized by calling
  72 :ref:`MEDIA_REQUEST_IOC_REINIT`.
  73
  74 Finally, the file descriptor can be :ref:`polled <request-func-poll>` to wait
  75 for the request to complete.
  76
  77 The request will remain allocated until all the file descriptors associated
  78 with it are closed by :ref:`close() <request-func-close>` and the driver no
  79 longer uses the request internally. See also
  80 :ref:`here <media-request-life-time>` for more information.
  81
  82 Return Value
  83 ============
  84
  85 On success 0 is returned, on error -1 and the ``errno`` variable is set
  86 appropriately. The generic error codes are described at the
  87 :ref:`Generic Error Codes <gen-errors>` chapter.
  88
  89 ENOTTY
  90     The driver has no support for requests.