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