0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_EXPBUF:
0005
0006 *******************
0007 ioctl VIDIOC_EXPBUF
0008 *******************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_EXPBUF - Export a buffer as a DMABUF file descriptor.
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_EXPBUF
0019
0020 ``int ioctl(int fd, VIDIOC_EXPBUF, struct v4l2_exportbuffer *argp)``
0021
0022 Arguments
0023 =========
0024
0025 ``fd``
0026 File descriptor returned by :c:func:`open()`.
0027
0028 ``argp``
0029 Pointer to struct :c:type:`v4l2_exportbuffer`.
0030
0031 Description
0032 ===========
0033
0034 This ioctl is an extension to the :ref:`memory mapping <mmap>` I/O
0035 method, therefore it is available only for ``V4L2_MEMORY_MMAP`` buffers.
0036 It can be used to export a buffer as a DMABUF file at any time after
0037 buffers have been allocated with the
0038 :ref:`VIDIOC_REQBUFS` ioctl.
0039
0040 To export a buffer, applications fill struct
0041 :c:type:`v4l2_exportbuffer`. The ``type`` field is
0042 set to the same buffer type as was previously used with struct
0043 :c:type:`v4l2_requestbuffers` ``type``.
0044 Applications must also set the ``index`` field. Valid index numbers
0045 range from zero to the number of buffers allocated with
0046 :ref:`VIDIOC_REQBUFS` (struct
0047 :c:type:`v4l2_requestbuffers` ``count``) minus
0048 one. For the multi-planar API, applications set the ``plane`` field to
0049 the index of the plane to be exported. Valid planes range from zero to
0050 the maximal number of valid planes for the currently active format. For
0051 the single-planar API, applications must set ``plane`` to zero.
0052 Additional flags may be posted in the ``flags`` field. Refer to a manual
0053 for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY,
0054 and O_RDWR are supported. All other fields must be set to zero. In the
0055 case of multi-planar API, every plane is exported separately using
0056 multiple :ref:`VIDIOC_EXPBUF` calls.
0057
0058 After calling :ref:`VIDIOC_EXPBUF` the ``fd`` field will be set by a
0059 driver. This is a DMABUF file descriptor. The application may pass it to
0060 other DMABUF-aware devices. Refer to :ref:`DMABUF importing <dmabuf>`
0061 for details about importing DMABUF files into V4L2 nodes. It is
0062 recommended to close a DMABUF file when it is no longer used to allow
0063 the associated memory to be reclaimed.
0064
0065 Examples
0066 ========
0067
0068 .. code-block:: c
0069
0070 int buffer_export(int v4lfd, enum v4l2_buf_type bt, int index, int *dmafd)
0071 {
0072 struct v4l2_exportbuffer expbuf;
0073
0074 memset(&expbuf, 0, sizeof(expbuf));
0075 expbuf.type = bt;
0076 expbuf.index = index;
0077 if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {
0078 perror("VIDIOC_EXPBUF");
0079 return -1;
0080 }
0081
0082 *dmafd = expbuf.fd;
0083
0084 return 0;
0085 }
0086
0087 .. code-block:: c
0088
0089 int buffer_export_mp(int v4lfd, enum v4l2_buf_type bt, int index,
0090 int dmafd[], int n_planes)
0091 {
0092 int i;
0093
0094 for (i = 0; i < n_planes; ++i) {
0095 struct v4l2_exportbuffer expbuf;
0096
0097 memset(&expbuf, 0, sizeof(expbuf));
0098 expbuf.type = bt;
0099 expbuf.index = index;
0100 expbuf.plane = i;
0101 if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {
0102 perror("VIDIOC_EXPBUF");
0103 while (i)
0104 close(dmafd[--i]);
0105 return -1;
0106 }
0107 dmafd[i] = expbuf.fd;
0108 }
0109
0110 return 0;
0111 }
0112
0113 .. c:type:: v4l2_exportbuffer
0114
0115 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0116
0117 .. flat-table:: struct v4l2_exportbuffer
0118 :header-rows: 0
0119 :stub-columns: 0
0120 :widths: 1 1 2
0121
0122 * - __u32
0123 - ``type``
0124 - Type of the buffer, same as struct
0125 :c:type:`v4l2_format` ``type`` or struct
0126 :c:type:`v4l2_requestbuffers` ``type``, set
0127 by the application. See :c:type:`v4l2_buf_type`
0128 * - __u32
0129 - ``index``
0130 - Number of the buffer, set by the application. This field is only
0131 used for :ref:`memory mapping <mmap>` I/O and can range from
0132 zero to the number of buffers allocated with the
0133 :ref:`VIDIOC_REQBUFS` and/or
0134 :ref:`VIDIOC_CREATE_BUFS` ioctls.
0135 * - __u32
0136 - ``plane``
0137 - Index of the plane to be exported when using the multi-planar API.
0138 Otherwise this value must be set to zero.
0139 * - __u32
0140 - ``flags``
0141 - Flags for the newly created file, currently only ``O_CLOEXEC``,
0142 ``O_RDONLY``, ``O_WRONLY``, and ``O_RDWR`` are supported, refer to
0143 the manual of open() for more details.
0144 * - __s32
0145 - ``fd``
0146 - The DMABUF file descriptor associated with a buffer. Set by the
0147 driver.
0148 * - __u32
0149 - ``reserved[11]``
0150 - Reserved field for future use. Drivers and applications must set
0151 the array to zero.
0152
0153 Return Value
0154 ============
0155
0156 On success 0 is returned, on error -1 and the ``errno`` variable is set
0157 appropriately. The generic error codes are described at the
0158 :ref:`Generic Error Codes <gen-errors>` chapter.
0159
0160 EINVAL
0161 A queue is not in MMAP mode or DMABUF exporting is not supported or
0162 ``flags`` or ``type`` or ``index`` or ``plane`` fields are invalid.
