^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) .. c:namespace:: V4L
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) .. _VIDIOC_EXPBUF:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) *******************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) ioctl VIDIOC_EXPBUF
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) *******************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) Name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) ====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) VIDIOC_EXPBUF - Export a buffer as a DMABUF file descriptor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) Synopsis
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) .. c:macro:: VIDIOC_EXPBUF
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) ``int ioctl(int fd, VIDIOC_EXPBUF, struct v4l2_exportbuffer *argp)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) Arguments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) ``fd``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) File descriptor returned by :c:func:`open()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) ``argp``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) Pointer to struct :c:type:`v4l2_exportbuffer`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) Description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) This ioctl is an extension to the :ref:`memory mapping <mmap>` I/O
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) method, therefore it is available only for ``V4L2_MEMORY_MMAP`` buffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) It can be used to export a buffer as a DMABUF file at any time after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) buffers have been allocated with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) :ref:`VIDIOC_REQBUFS` ioctl.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) To export a buffer, applications fill struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) :c:type:`v4l2_exportbuffer`. The ``type`` field is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) set to the same buffer type as was previously used with struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) :c:type:`v4l2_requestbuffers` ``type``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) Applications must also set the ``index`` field. Valid index numbers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) range from zero to the number of buffers allocated with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) :ref:`VIDIOC_REQBUFS` (struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) :c:type:`v4l2_requestbuffers` ``count``) minus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) one. For the multi-planar API, applications set the ``plane`` field to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) the index of the plane to be exported. Valid planes range from zero to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) the maximal number of valid planes for the currently active format. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) the single-planar API, applications must set ``plane`` to zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) Additional flags may be posted in the ``flags`` field. Refer to a manual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) and O_RDWR are supported. All other fields must be set to zero. In the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) case of multi-planar API, every plane is exported separately using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) multiple :ref:`VIDIOC_EXPBUF` calls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) After calling :ref:`VIDIOC_EXPBUF` the ``fd`` field will be set by a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) driver. This is a DMABUF file descriptor. The application may pass it to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) other DMABUF-aware devices. Refer to :ref:`DMABUF importing <dmabuf>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) for details about importing DMABUF files into V4L2 nodes. It is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) recommended to close a DMABUF file when it is no longer used to allow
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) the associated memory to be reclaimed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) Examples
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) int buffer_export(int v4lfd, enum v4l2_buf_type bt, int index, int *dmafd)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) struct v4l2_exportbuffer expbuf;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) memset(&expbuf, 0, sizeof(expbuf));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) expbuf.type = bt;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) expbuf.index = index;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) perror("VIDIOC_EXPBUF");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) return -1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) *dmafd = expbuf.fd;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) int buffer_export_mp(int v4lfd, enum v4l2_buf_type bt, int index,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) int dmafd[], int n_planes)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) int i;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) for (i = 0; i < n_planes; ++i) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) struct v4l2_exportbuffer expbuf;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) memset(&expbuf, 0, sizeof(expbuf));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) expbuf.type = bt;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) expbuf.index = index;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) expbuf.plane = i;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) perror("VIDIOC_EXPBUF");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) while (i)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) close(dmafd[--i]);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) return -1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) dmafd[i] = expbuf.fd;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) .. c:type:: v4l2_exportbuffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) .. flat-table:: struct v4l2_exportbuffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) :widths: 1 1 2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) - ``type``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) - Type of the buffer, same as struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) :c:type:`v4l2_format` ``type`` or struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) :c:type:`v4l2_requestbuffers` ``type``, set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) by the application. See :c:type:`v4l2_buf_type`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) - ``index``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) - Number of the buffer, set by the application. This field is only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) used for :ref:`memory mapping <mmap>` I/O and can range from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) zero to the number of buffers allocated with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) :ref:`VIDIOC_REQBUFS` and/or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) :ref:`VIDIOC_CREATE_BUFS` ioctls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) - ``plane``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) - Index of the plane to be exported when using the multi-planar API.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) Otherwise this value must be set to zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) - ``flags``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) - Flags for the newly created file, currently only ``O_CLOEXEC``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) ``O_RDONLY``, ``O_WRONLY``, and ``O_RDWR`` are supported, refer to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) the manual of open() for more details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) * - __s32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) - ``fd``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) - The DMABUF file descriptor associated with a buffer. Set by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) - ``reserved[11]``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) - Reserved field for future use. Drivers and applications must set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) the array to zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) Return Value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) On success 0 is returned, on error -1 and the ``errno`` variable is set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) appropriately. The generic error codes are described at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) :ref:`Generic Error Codes <gen-errors>` chapter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) EINVAL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) A queue is not in MMAP mode or DMABUF exporting is not supported or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) ``flags`` or ``type`` or ``index`` or ``plane`` fields are invalid.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags