^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) .. _userp:
^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) Streaming I/O (User Pointers)
^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) Input and output devices support this I/O method when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) ``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) :c:type:`v4l2_capability` returned by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) :ref:`VIDIOC_QUERYCAP` ioctl is set. If the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) particular user pointer method (not only memory mapping) is supported
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) must be determined by calling the :ref:`VIDIOC_REQBUFS` ioctl
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) with the memory type set to ``V4L2_MEMORY_USERPTR``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) This I/O method combines advantages of the read/write and memory mapping
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) methods. Buffers (planes) are allocated by the application itself, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) can reside for example in virtual or shared memory. Only pointers to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) data are exchanged, these pointers and meta-information are passed in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) struct :c:type:`v4l2_buffer` (or in struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) :c:type:`v4l2_plane` in the multi-planar API case). The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) driver must be switched into user pointer I/O mode by calling the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) :ref:`VIDIOC_REQBUFS` with the desired buffer type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) No buffers (planes) are allocated beforehand, consequently they are not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) indexed and cannot be queried like mapped buffers with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>` ioctl.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) Example: Initiating streaming I/O with user pointers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) ====================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) struct v4l2_requestbuffers reqbuf;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) memset (&reqbuf, 0, sizeof (reqbuf));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) reqbuf.memory = V4L2_MEMORY_USERPTR;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) if (ioctl (fd, VIDIOC_REQBUFS, &reqbuf) == -1) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) if (errno == EINVAL)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) printf ("Video capturing or user pointer streaming is not supported\\n");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) else
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) perror ("VIDIOC_REQBUFS");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) exit (EXIT_FAILURE);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) Buffer (plane) addresses and sizes are passed on the fly with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. Although buffers are commonly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) cycled, applications can pass different addresses and sizes at each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call. If required by the hardware the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) driver swaps memory pages within physical memory to create a continuous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) area of memory. This happens transparently to the application in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) virtual memory subsystem of the kernel. When buffer pages have been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) swapped out to disk they are brought back and finally locked in physical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) memory for DMA. [#f1]_
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) Filled or displayed buffers are dequeued with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The driver can unlock the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) memory pages at any time between the completion of the DMA and this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) ioctl. The memory is also unlocked when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) :ref:`VIDIOC_REQBUFS`, or when the device is closed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) Applications must take care not to free buffers without dequeuing.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) Firstly, the buffers remain locked for longer, wasting physical memory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) Secondly the driver will not be notified when the memory is returned to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) the application's free list and subsequently reused for other purposes,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) possibly completing the requested DMA and overwriting valuable data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) For capturing applications it is customary to enqueue a number of empty
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) buffers, to start capturing and enter the read loop. Here the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) application waits until a filled buffer can be dequeued, and re-enqueues
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) the buffer when the data is no longer needed. Output applications fill
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) and enqueue buffers, when enough buffers are stacked up output is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) started. In the write loop, when the application runs out of free
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) buffers it must wait until an empty buffer can be dequeued and reused.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) Two methods exist to suspend execution of the application until one or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) <VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) ``O_NONBLOCK`` flag was given to the :c:func:`open()` function,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) error code when no buffer is available. The :ref:`select()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) <func-select>` or :c:func:`poll()` function are always
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) available.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) To start and stop capturing or output applications call the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctl.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) both queues and unlocks all buffers as a side effect. Since there is no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) notion of doing anything "now" on a multitasking system, if an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) application needs to synchronize with another event it should examine
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) the struct :c:type:`v4l2_buffer` ``timestamp`` of captured or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) outputted buffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) Drivers implementing user pointer I/O must support the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) :c:func:`select()` and :c:func:`poll()` function. [#f2]_
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) .. [#f1]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) We expect that frequently used buffers are typically not swapped out.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) Anyway, the process of swapping, locking or generating scatter-gather
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) lists may be time consuming. The delay can be masked by the depth of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) the incoming buffer queue, and perhaps by maintaining caches assuming
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) a buffer will be soon enqueued again. On the other hand, to optimize
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) memory usage drivers can limit the number of buffers locked in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) advance and recycle the most recently used buffers first. Of course,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) the pages of empty buffers in the incoming queue need not be saved to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) disk. Output buffers must be saved on the incoming and outgoing queue
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) because an application may share them with other processes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) .. [#f2]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) At the driver level :c:func:`select()` and :c:func:`poll()` are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) the same, and :c:func:`select()` is too important to be optional.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) The rest should be evident.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags