1 .. -*- coding: utf-8; mode: rst -*-
12 VIDIOC_REQBUFS - Initiate Memory Mapping, User Pointer I/O or DMA buffer I/O
18 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_requestbuffers *argp )
25 File descriptor returned by :ref:`open() <func-open>`.
36 This ioctl is used to initiate :ref:`memory mapped <mmap>`,
37 :ref:`user pointer <userp>` or :ref:`DMABUF <dmabuf>` based I/O.
38 Memory mapped buffers are located in device memory and must be allocated
39 with this ioctl before they can be mapped into the application's address
40 space. User buffers are allocated by applications themselves, and this
41 ioctl is merely used to switch the driver into user pointer I/O mode and
42 to setup some internal structures. Similarly, DMABUF buffers are
43 allocated by applications through a device driver, and this ioctl only
44 configures the driver into DMABUF I/O mode without performing any direct
47 To allocate device buffers applications initialize all fields of the
48 :ref:`struct v4l2_requestbuffers <v4l2-requestbuffers>` structure. They set the ``type``
49 field to the respective stream or buffer type, the ``count`` field to
50 the desired number of buffers, ``memory`` must be set to the requested
51 I/O method and the ``reserved`` array must be zeroed. When the ioctl is
52 called with a pointer to this structure the driver will attempt to
53 allocate the requested number of buffers and it stores the actual number
54 allocated in the ``count`` field. It can be smaller than the number
55 requested, even zero, when the driver runs out of free memory. A larger
56 number is also possible when the driver requires more buffers to
57 function correctly. For example video output requires at least two
58 buffers, one displayed and one filled by the application.
60 When the I/O method is not supported the ioctl returns an ``EINVAL`` error
63 Applications can call :ref:`VIDIOC_REQBUFS` again to change the number of
64 buffers, however this cannot succeed when any buffers are still mapped.
65 A ``count`` value of zero frees all buffers, after aborting or finishing
66 any DMA in progress, an implicit
67 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`.
70 .. _v4l2-requestbuffers:
72 .. flat-table:: struct v4l2_requestbuffers
84 - The number of buffers requested or granted.
92 - Type of the stream or buffers, this is the same as the struct
93 :ref:`v4l2_format <v4l2-format>` ``type`` field. See
94 :ref:`v4l2-buf-type` for valid values.
102 - Applications set this field to ``V4L2_MEMORY_MMAP``,
103 ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See
112 - A place holder for future extensions. Drivers and applications
113 must set the array to zero.
119 On success 0 is returned, on error -1 and the ``errno`` variable is set
120 appropriately. The generic error codes are described at the
121 :ref:`Generic Error Codes <gen-errors>` chapter.
124 The buffer type (``type`` field) or the requested I/O method
125 (``memory``) is not supported.