Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 1 | .. -*- coding: utf-8; mode: rst -*- |
| 2 | |
Mauro Carvalho Chehab | af4a4d0 | 2016-07-01 13:42:29 -0300 | [diff] [blame] | 3 | .. _VIDIOC_CREATE_BUFS: |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 4 | |
| 5 | ************************ |
| 6 | ioctl VIDIOC_CREATE_BUFS |
| 7 | ************************ |
| 8 | |
| 9 | *man VIDIOC_CREATE_BUFS(2)* |
| 10 | |
| 11 | Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O |
| 12 | |
| 13 | |
| 14 | Synopsis |
| 15 | ======== |
| 16 | |
Mauro Carvalho Chehab | b7e67f6 | 2016-07-02 09:49:16 -0300 | [diff] [blame] | 17 | .. cpp:function:: int ioctl( int fd, int request, struct v4l2_create_buffers *argp ) |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 18 | |
| 19 | Arguments |
| 20 | ========= |
| 21 | |
| 22 | ``fd`` |
| 23 | File descriptor returned by :ref:`open() <func-open>`. |
| 24 | |
| 25 | ``request`` |
| 26 | VIDIOC_CREATE_BUFS |
| 27 | |
| 28 | ``argp`` |
| 29 | |
| 30 | |
| 31 | Description |
| 32 | =========== |
| 33 | |
| 34 | This ioctl is used to create buffers for :ref:`memory mapped <mmap>` |
| 35 | or :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. It |
| 36 | can be used as an alternative or in addition to the |
Mauro Carvalho Chehab | 7347081 | 2016-07-01 13:58:44 -0300 | [diff] [blame] | 37 | :ref:`VIDIOC_REQBUFS` ioctl, when a tighter control |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 38 | over buffers is required. This ioctl can be called multiple times to |
| 39 | create buffers of different sizes. |
| 40 | |
| 41 | To allocate the device buffers applications must initialize the relevant |
Mauro Carvalho Chehab | acf309a | 2016-07-03 13:28:28 -0300 | [diff] [blame^] | 42 | fields of the :ref:`struct v4l2_create_buffers <v4l2-create-buffers>` structure. The |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 43 | ``count`` field must be set to the number of requested buffers, the |
| 44 | ``memory`` field specifies the requested I/O method and the ``reserved`` |
| 45 | array must be zeroed. |
| 46 | |
| 47 | The ``format`` field specifies the image format that the buffers must be |
| 48 | able to handle. The application has to fill in this struct |
| 49 | :ref:`v4l2_format <v4l2-format>`. Usually this will be done using the |
Mauro Carvalho Chehab | af4a4d0 | 2016-07-01 13:42:29 -0300 | [diff] [blame] | 50 | :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` or |
Mauro Carvalho Chehab | 4e03cb7 | 2016-07-03 10:02:29 -0300 | [diff] [blame] | 51 | :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctls to ensure that the |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 52 | requested format is supported by the driver. Based on the format's |
| 53 | ``type`` field the requested buffer size (for single-planar) or plane |
| 54 | sizes (for multi-planar formats) will be used for the allocated buffers. |
| 55 | The driver may return an error if the size(s) are not supported by the |
| 56 | hardware (usually because they are too small). |
| 57 | |
| 58 | The buffers created by this ioctl will have as minimum size the size |
| 59 | defined by the ``format.pix.sizeimage`` field (or the corresponding |
| 60 | fields for other format types). Usually if the ``format.pix.sizeimage`` |
| 61 | field is less than the minimum required for the given format, then an |
| 62 | error will be returned since drivers will typically not allow this. If |
| 63 | it is larger, then the value will be used as-is. In other words, the |
| 64 | driver may reject the requested size, but if it is accepted the driver |
| 65 | will use it unchanged. |
| 66 | |
| 67 | When the ioctl is called with a pointer to this structure the driver |
| 68 | will attempt to allocate up to the requested number of buffers and store |
| 69 | the actual number allocated and the starting index in the ``count`` and |
| 70 | the ``index`` fields respectively. On return ``count`` can be smaller |
| 71 | than the number requested. |
| 72 | |
| 73 | |
| 74 | .. _v4l2-create-buffers: |
| 75 | |
| 76 | .. flat-table:: struct v4l2_create_buffers |
| 77 | :header-rows: 0 |
| 78 | :stub-columns: 0 |
| 79 | :widths: 1 1 2 |
| 80 | |
| 81 | |
| 82 | - .. row 1 |
| 83 | |
| 84 | - __u32 |
| 85 | |
| 86 | - ``index`` |
| 87 | |
| 88 | - The starting buffer index, returned by the driver. |
| 89 | |
| 90 | - .. row 2 |
| 91 | |
| 92 | - __u32 |
| 93 | |
| 94 | - ``count`` |
| 95 | |
| 96 | - The number of buffers requested or granted. If count == 0, then |
Mauro Carvalho Chehab | 2212ff2 | 2016-07-01 14:33:56 -0300 | [diff] [blame] | 97 | :ref:`VIDIOC_CREATE_BUFS` will set ``index`` to the current number of |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 98 | created buffers, and it will check the validity of ``memory`` and |
| 99 | ``format.type``. If those are invalid -1 is returned and errno is |
Mauro Carvalho Chehab | cdb4af0 | 2016-07-03 11:53:09 -0300 | [diff] [blame] | 100 | set to ``EINVAL`` error code, otherwise :ref:`VIDIOC_CREATE_BUFS` returns |
| 101 | 0. It will never set errno to ``EBUSY`` error code in this particular |
Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 102 | case. |
| 103 | |
| 104 | - .. row 3 |
| 105 | |
| 106 | - __u32 |
| 107 | |
| 108 | - ``memory`` |
| 109 | |
| 110 | - Applications set this field to ``V4L2_MEMORY_MMAP``, |
| 111 | ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See |
| 112 | :ref:`v4l2-memory` |
| 113 | |
| 114 | - .. row 4 |
| 115 | |
| 116 | - struct :ref:`v4l2_format <v4l2-format>` |
| 117 | |
| 118 | - ``format`` |
| 119 | |
| 120 | - Filled in by the application, preserved by the driver. |
| 121 | |
| 122 | - .. row 5 |
| 123 | |
| 124 | - __u32 |
| 125 | |
| 126 | - ``reserved``\ [8] |
| 127 | |
| 128 | - A place holder for future extensions. Drivers and applications |
| 129 | must set the array to zero. |
| 130 | |
| 131 | |
| 132 | |
| 133 | Return Value |
| 134 | ============ |
| 135 | |
| 136 | On success 0 is returned, on error -1 and the ``errno`` variable is set |
| 137 | appropriately. The generic error codes are described at the |
| 138 | :ref:`Generic Error Codes <gen-errors>` chapter. |
| 139 | |
| 140 | ENOMEM |
| 141 | No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O. |
| 142 | |
| 143 | EINVAL |
| 144 | The buffer type (``format.type`` field), requested I/O method |
| 145 | (``memory``) or format (``format`` field) is not valid. |
| 146 | |
| 147 | |
| 148 | .. ------------------------------------------------------------------------------ |
| 149 | .. This file was automatically converted from DocBook-XML with the dbxml |
| 150 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes |
| 151 | .. from the linux kernel, refer to: |
| 152 | .. |
| 153 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook |
| 154 | .. ------------------------------------------------------------------------------ |