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