Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
af4a4d0d | 3 | .. _VIDIOC_STREAMON: |
5377d91f MH |
4 | |
5 | *************************************** | |
6 | ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF | |
7 | *************************************** | |
8 | ||
15e7d615 | 9 | Name |
586027ce | 10 | ==== |
5377d91f | 11 | |
586027ce | 12 | VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O |
5377d91f | 13 | |
15e7d615 MCC |
14 | |
15 | Synopsis | |
5377d91f MH |
16 | ======== |
17 | ||
b7e67f6c | 18 | .. cpp:function:: int ioctl( int fd, int request, const int *argp ) |
5377d91f | 19 | |
586027ce | 20 | |
15e7d615 | 21 | Arguments |
5377d91f MH |
22 | ========= |
23 | ||
24 | ``fd`` | |
25 | File descriptor returned by :ref:`open() <func-open>`. | |
26 | ||
27 | ``request`` | |
28 | VIDIOC_STREAMON, VIDIOC_STREAMOFF | |
29 | ||
30 | ``argp`` | |
31 | ||
32 | ||
15e7d615 | 33 | Description |
5377d91f MH |
34 | =========== |
35 | ||
36 | The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop | |
37 | the capture or output process during streaming | |
38 | (:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or | |
39 | :ref:`DMABUF <dmabuf>`) I/O. | |
40 | ||
41 | Capture hardware is disabled and no input buffers are filled (if there | |
42 | are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON`` | |
43 | has been called. Output hardware is disabled and no video signal is | |
44 | produced until ``VIDIOC_STREAMON`` has been called. The ioctl will | |
45 | succeed when at least one output buffer is in the incoming queue. | |
46 | ||
47 | Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has | |
48 | been called for both the capture and output stream types. | |
49 | ||
50 | If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain | |
51 | queued. | |
52 | ||
53 | The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA | |
54 | in progress, unlocks any user pointer buffers locked in physical memory, | |
55 | and it removes all buffers from the incoming and outgoing queues. That | |
56 | means all images captured but not dequeued yet will be lost, likewise | |
57 | all images enqueued for output but not transmitted yet. I/O returns to | |
58 | the same state as after calling | |
7347081e | 59 | :ref:`VIDIOC_REQBUFS` and can be restarted |
5377d91f MH |
60 | accordingly. |
61 | ||
7347081e | 62 | If buffers have been queued with :ref:`VIDIOC_QBUF` and |
5377d91f MH |
63 | ``VIDIOC_STREAMOFF`` is called without ever having called |
64 | ``VIDIOC_STREAMON``, then those queued buffers will also be removed from | |
65 | the incoming queue and all are returned to the same state as after | |
7347081e | 66 | calling :ref:`VIDIOC_REQBUFS` and can be restarted |
5377d91f MH |
67 | accordingly. |
68 | ||
69 | Both ioctls take a pointer to an integer, the desired buffer or stream | |
70 | type. This is the same as struct | |
71 | :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``. | |
72 | ||
73 | If ``VIDIOC_STREAMON`` is called when streaming is already in progress, | |
74 | or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped, | |
75 | then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``, | |
76 | but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting | |
77 | state as mentioned above. | |
78 | ||
79 | Note that applications can be preempted for unknown periods right before | |
80 | or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is | |
81 | no notion of starting or stopping "now". Buffer timestamps can be used | |
82 | to synchronize with other events. | |
83 | ||
84 | ||
15e7d615 | 85 | Return Value |
5377d91f MH |
86 | ============ |
87 | ||
88 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
89 | appropriately. The generic error codes are described at the | |
90 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
91 | ||
92 | EINVAL | |
93 | The buffer ``type`` is not supported, or no buffers have been | |
94 | allocated (memory mapping) or enqueued (output) yet. | |
95 | ||
96 | EPIPE | |
97 | The driver implements | |
98 | :ref:`pad-level format configuration <pad-level-formats>` and the | |
99 | pipeline configuration is invalid. | |
100 | ||
101 | ENOLINK | |
102 | The driver implements Media Controller interface and the pipeline | |
103 | link configuration is invalid. |