From 8e4bff4cab0ddac6060645b0715210484d02ff40 Mon Sep 17 00:00:00 2001
From: Yuval Adam <_@yuv.al>
Date: Wed, 30 Aug 2017 08:25:59 +0000
Subject: Initial file dump from open source release
---
Documentation/DocBook/media/v4l/io.xml | 1487 ++++++++++++++++++++++++++++++++
1 file changed, 1487 insertions(+)
create mode 100644 Documentation/DocBook/media/v4l/io.xml
(limited to 'Documentation/DocBook/media/v4l/io.xml')
diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml
new file mode 100644
index 00000000..2c4c068d
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/io.xml
@@ -0,0 +1,1487 @@
+ Input/Output
+
+ The V4L2 API defines several different methods to read from or
+write to a device. All drivers exchanging data with applications must
+support at least one of them.
+
+ The classic I/O method using the read()
+and write() function is automatically selected
+after opening a V4L2 device. When the driver does not support this
+method attempts to read or write will fail at any time.
+
+ Other methods must be negotiated. To select the streaming I/O
+method with memory mapped or user buffers applications call the
+&VIDIOC-REQBUFS; ioctl. The asynchronous I/O method is not defined
+yet.
+
+ Video overlay can be considered another I/O method, although
+the application does not directly receive the image data. It is
+selected by initiating video overlay with the &VIDIOC-S-FMT; ioctl.
+For more information see .
+
+ Generally exactly one I/O method, including overlay, is
+associated with each file descriptor. The only exceptions are
+applications not exchanging data with a driver ("panel applications",
+see ) and drivers permitting simultaneous video capturing
+and overlay using the same file descriptor, for compatibility with V4L
+and earlier versions of V4L2.
+
+ VIDIOC_S_FMT and
+VIDIOC_REQBUFS would permit this to some degree,
+but for simplicity drivers need not support switching the I/O method
+(after first switching away from read/write) other than by closing
+and reopening the device.
+
+ The following sections describe the various I/O methods in
+more detail.
+
+
+ Read/Write
+
+ Input and output devices support the
+read() and write() function,
+respectively, when the V4L2_CAP_READWRITE flag in
+the capabilities field of &v4l2-capability;
+returned by the &VIDIOC-QUERYCAP; ioctl is set.
+
+ Drivers may need the CPU to copy the data, but they may also
+support DMA to or from user memory, so this I/O method is not
+necessarily less efficient than other methods merely exchanging buffer
+pointers. It is considered inferior though because no meta-information
+like frame counters or timestamps are passed. This information is
+necessary to recognize frame dropping and to synchronize with other
+data streams. However this is also the simplest I/O method, requiring
+little or no setup to exchange data. It permits command line stunts
+like this (the vidctrl tool is
+fictitious):
+
+
+
+> vidctrl /dev/video --input=0 --format=YUYV --size=352x288
+> dd if=/dev/video of=myimage.422 bs=202752 count=1
+
+
+
+ To read from the device applications use the
+&func-read; function, to write the &func-write; function.
+Drivers must implement one I/O method if they
+exchange data with applications, but it need not be this.
+ It would be desirable if applications could depend on
+drivers supporting all I/O interfaces, but as much as the complex
+memory mapping I/O can be inadequate for some devices we have no
+reason to require this interface, which is most useful for simple
+applications capturing still images.
+ When reading or writing is supported, the driver
+must also support the &func-select; and &func-poll;
+function.
+ At the driver level select() and
+poll() are the same, and
+select() is too important to be optional.
+
+
+
+
+ Streaming I/O (Memory Mapping)
+
+ Input and output devices support this I/O method when the
+V4L2_CAP_STREAMING flag in the
+capabilities field of &v4l2-capability;
+returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two
+streaming methods, to determine if the memory mapping flavor is
+supported applications must call the &VIDIOC-REQBUFS; ioctl.
+
+ Streaming is an I/O method where only pointers to buffers
+are exchanged between application and driver, the data itself is not
+copied. Memory mapping is primarily intended to map buffers in device
+memory into the application's address space. Device memory can be for
+example the video memory on a graphics card with a video capture
+add-on. However, being the most efficient I/O method available for a
+long time, many other drivers support streaming as well, allocating
+buffers in DMA-able main memory.
+
+ A driver can support many sets of buffers. Each set is
+identified by a unique buffer type value. The sets are independent and
+each set can hold a different type of data. To access different sets
+at the same time different file descriptors must be used.
+ One could use one file descriptor and set the buffer
+type field accordingly when calling &VIDIOC-QBUF; etc., but it makes
+the select() function ambiguous. We also like the
+clean approach of one file descriptor per logical stream. Video
+overlay for example is also a logical stream, although the CPU is not
+needed for continuous operation.
+
+
+ To allocate device buffers applications call the
+&VIDIOC-REQBUFS; ioctl with the desired number of buffers and buffer
+type, for example V4L2_BUF_TYPE_VIDEO_CAPTURE.
+This ioctl can also be used to change the number of buffers or to free
+the allocated memory, provided none of the buffers are still
+mapped.
+
+ Before applications can access the buffers they must map
+them into their address space with the &func-mmap; function. The
+location of the buffers in device memory can be determined with the
+&VIDIOC-QUERYBUF; ioctl. In the single-planar API case, the
+m.offset and length
+returned in a &v4l2-buffer; are passed as sixth and second parameter to the
+mmap() function. When using the multi-planar API,
+struct &v4l2-buffer; contains an array of &v4l2-plane; structures, each
+containing its own m.offset and
+length. When using the multi-planar API, every
+plane of every buffer has to be mapped separately, so the number of
+calls to &func-mmap; should be equal to number of buffers times number of
+planes in each buffer. The offset and length values must not be modified.
+Remember, the buffers are allocated in physical memory, as opposed to virtual
+memory, which can be swapped out to disk. Applications should free the buffers
+as soon as possible with the &func-munmap; function.
+
+
+ Mapping buffers in the single-planar API
+
+&v4l2-requestbuffers; reqbuf;
+struct {
+ void *start;
+ size_t length;
+} *buffers;
+unsigned int i;
+
+memset(&reqbuf, 0, sizeof(reqbuf));
+reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+reqbuf.memory = V4L2_MEMORY_MMAP;
+reqbuf.count = 20;
+
+if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf)) {
+ if (errno == EINVAL)
+ printf("Video capturing or mmap-streaming is not supported\n");
+ else
+ perror("VIDIOC_REQBUFS");
+
+ exit(EXIT_FAILURE);
+}
+
+/* We want at least five buffers. */
+
+if (reqbuf.count < 5) {
+ /* You may need to free the buffers here. */
+ printf("Not enough buffer memory\n");
+ exit(EXIT_FAILURE);
+}
+
+buffers = calloc(reqbuf.count, sizeof(*buffers));
+assert(buffers != NULL);
+
+for (i = 0; i < reqbuf.count; i++) {
+ &v4l2-buffer; buffer;
+
+ memset(&buffer, 0, sizeof(buffer));
+ buffer.type = reqbuf.type;
+ buffer.memory = V4L2_MEMORY_MMAP;
+ buffer.index = i;
+
+ if (-1 == ioctl (fd, &VIDIOC-QUERYBUF;, &buffer)) {
+ perror("VIDIOC_QUERYBUF");
+ exit(EXIT_FAILURE);
+ }
+
+ buffers[i].length = buffer.length; /* remember for munmap() */
+
+ buffers[i].start = mmap(NULL, buffer.length,
+ PROT_READ | PROT_WRITE, /* recommended */
+ MAP_SHARED, /* recommended */
+ fd, buffer.m.offset);
+
+ if (MAP_FAILED == buffers[i].start) {
+ /* If you do not exit here you should unmap() and free()
+ the buffers mapped so far. */
+ perror("mmap");
+ exit(EXIT_FAILURE);
+ }
+}
+
+/* Cleanup. */
+
+for (i = 0; i < reqbuf.count; i++)
+ munmap(buffers[i].start, buffers[i].length);
+
+
+
+
+ Mapping buffers in the multi-planar API
+
+&v4l2-requestbuffers; reqbuf;
+/* Our current format uses 3 planes per buffer */
+#define FMT_NUM_PLANES = 3
+
+struct {
+ void *start[FMT_NUM_PLANES];
+ size_t length[FMT_NUM_PLANES];
+} *buffers;
+unsigned int i, j;
+
+memset(&reqbuf, 0, sizeof(reqbuf));
+reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
+reqbuf.memory = V4L2_MEMORY_MMAP;
+reqbuf.count = 20;
+
+if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) < 0) {
+ if (errno == EINVAL)
+ printf("Video capturing or mmap-streaming is not supported\n");
+ else
+ perror("VIDIOC_REQBUFS");
+
+ exit(EXIT_FAILURE);
+}
+
+/* We want at least five buffers. */
+
+if (reqbuf.count < 5) {
+ /* You may need to free the buffers here. */
+ printf("Not enough buffer memory\n");
+ exit(EXIT_FAILURE);
+}
+
+buffers = calloc(reqbuf.count, sizeof(*buffers));
+assert(buffers != NULL);
+
+for (i = 0; i < reqbuf.count; i++) {
+ &v4l2-buffer; buffer;
+ &v4l2-plane; planes[FMT_NUM_PLANES];
+
+ memset(&buffer, 0, sizeof(buffer));
+ buffer.type = reqbuf.type;
+ buffer.memory = V4L2_MEMORY_MMAP;
+ buffer.index = i;
+ /* length in struct v4l2_buffer in multi-planar API stores the size
+ * of planes array. */
+ buffer.length = FMT_NUM_PLANES;
+ buffer.m.planes = planes;
+
+ if (ioctl(fd, &VIDIOC-QUERYBUF;, &buffer) < 0) {
+ perror("VIDIOC_QUERYBUF");
+ exit(EXIT_FAILURE);
+ }
+
+ /* Every plane has to be mapped separately */
+ for (j = 0; j < FMT_NUM_PLANES; j++) {
+ buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */
+
+ buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length,
+ PROT_READ | PROT_WRITE, /* recommended */
+ MAP_SHARED, /* recommended */
+ fd, buffer.m.planes[j].m.offset);
+
+ if (MAP_FAILED == buffers[i].start[j]) {
+ /* If you do not exit here you should unmap() and free()
+ the buffers and planes mapped so far. */
+ perror("mmap");
+ exit(EXIT_FAILURE);
+ }
+ }
+}
+
+/* Cleanup. */
+
+for (i = 0; i < reqbuf.count; i++)
+ for (j = 0; j < FMT_NUM_PLANES; j++)
+ munmap(buffers[i].start[j], buffers[i].length[j]);
+
+
+
+ Conceptually streaming drivers maintain two buffer queues, an incoming
+and an outgoing queue. They separate the synchronous capture or output
+operation locked to a video clock from the application which is
+subject to random disk or network delays and preemption by
+other processes, thereby reducing the probability of data loss.
+The queues are organized as FIFOs, buffers will be
+output in the order enqueued in the incoming FIFO, and were
+captured in the order dequeued from the outgoing FIFO.
+
+ The driver may require a minimum number of buffers enqueued
+at all times to function, apart of this no limit exists on the number
+of buffers applications can enqueue in advance, or dequeue and
+process. They can also enqueue in a different order than buffers have
+been dequeued, and the driver can fill enqueued
+empty buffers in any order.
+ Random enqueue order permits applications processing
+images out of order (such as video codecs) to return buffers earlier,
+reducing the probability of data loss. Random fill order allows
+drivers to reuse buffers on a LIFO-basis, taking advantage of caches
+holding scatter-gather lists and the like.
+ The index number of a buffer (&v4l2-buffer;
+index) plays no role here, it only
+identifies the buffer.
+
+ Initially all mapped buffers are in dequeued state,
+inaccessible by the driver. For capturing applications it is customary
+to first enqueue all mapped buffers, then to start capturing and enter
+the read loop. Here the application waits until a filled buffer can be
+dequeued, and re-enqueues the buffer when the data is no longer
+needed. Output applications fill and enqueue buffers, when enough
+buffers are stacked up the output is started with
+VIDIOC_STREAMON. In the write loop, when
+the application runs out of free buffers, it must wait until an empty
+buffer can be dequeued and reused.
+
+ To enqueue and dequeue a buffer applications use the
+&VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. The status of a buffer being
+mapped, enqueued, full or empty can be determined at any time using the
+&VIDIOC-QUERYBUF; ioctl. Two methods exist to suspend execution of the
+application until one or more buffers can be dequeued. By default
+VIDIOC_DQBUF blocks when no buffer is in the
+outgoing queue. When the O_NONBLOCK flag was
+given to the &func-open; function, VIDIOC_DQBUF
+returns immediately with an &EAGAIN; when no buffer is available. The
+&func-select; or &func-poll; functions are always available.
+
+ To start and stop capturing or output applications call the
+&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note
+VIDIOC_STREAMOFF removes all buffers from both
+queues as a side effect. Since there is no notion of doing anything
+"now" on a multitasking system, if an application needs to synchronize
+with another event it should examine the &v4l2-buffer;
+timestamp of captured buffers, or set the
+field before enqueuing buffers for output.
+
+ Drivers implementing memory mapping I/O must
+support the VIDIOC_REQBUFS,
+VIDIOC_QUERYBUF,
+VIDIOC_QBUF, VIDIOC_DQBUF,
+VIDIOC_STREAMON and
+VIDIOC_STREAMOFF ioctl, the
+mmap(), munmap(),
+select() and poll()
+function.
+ At the driver level select() and
+poll() are the same, and
+select() is too important to be optional. The
+rest should be evident.
+
+
+ [capture example]
+
+
+
+
+ Streaming I/O (User Pointers)
+
+ Input and output devices support this I/O method when the
+V4L2_CAP_STREAMING flag in the
+capabilities field of &v4l2-capability;
+returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user
+pointer method (not only memory mapping) is supported must be
+determined by calling the &VIDIOC-REQBUFS; ioctl.
+
+ This I/O method combines advantages of the read/write and
+memory mapping methods. Buffers (planes) are allocated by the application
+itself, and can reside for example in virtual or shared memory. Only
+pointers to data are exchanged, these pointers and meta-information
+are passed in &v4l2-buffer; (or in &v4l2-plane; in the multi-planar API case).
+The driver must be switched into user pointer I/O mode by calling the
+&VIDIOC-REQBUFS; with the desired buffer type. No buffers (planes) are allocated
+beforehand, consequently they are not indexed and cannot be queried like mapped
+buffers with the VIDIOC_QUERYBUF ioctl.
+
+
+ Initiating streaming I/O with user pointers
+
+
+&v4l2-requestbuffers; reqbuf;
+
+memset (&reqbuf, 0, sizeof (reqbuf));
+reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+reqbuf.memory = V4L2_MEMORY_USERPTR;
+
+if (ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) {
+ if (errno == EINVAL)
+ printf ("Video capturing or user pointer streaming is not supported\n");
+ else
+ perror ("VIDIOC_REQBUFS");
+
+ exit (EXIT_FAILURE);
+}
+
+
+
+ Buffer (plane) addresses and sizes are passed on the fly with the
+&VIDIOC-QBUF; ioctl. Although buffers are commonly cycled,
+applications can pass different addresses and sizes at each
+VIDIOC_QBUF call. If required by the hardware the
+driver swaps memory pages within physical memory to create a
+continuous area of memory. This happens transparently to the
+application in the virtual memory subsystem of the kernel. When buffer
+pages have been swapped out to disk they are brought back and finally
+locked in physical memory for DMA.
+ We expect that frequently used buffers are typically not
+swapped out. Anyway, the process of swapping, locking or generating
+scatter-gather lists may be time consuming. The delay can be masked by
+the depth of the incoming buffer queue, and perhaps by maintaining
+caches assuming a buffer will be soon enqueued again. On the other
+hand, to optimize memory usage drivers can limit the number of buffers
+locked in advance and recycle the most recently used buffers first. Of
+course, the pages of empty buffers in the incoming queue need not be
+saved to disk. Output buffers must be saved on the incoming and
+outgoing queue because an application may share them with other
+processes.
+
+
+ Filled or displayed buffers are dequeued with the
+&VIDIOC-DQBUF; ioctl. The driver can unlock the memory pages at any
+time between the completion of the DMA and this ioctl. The memory is
+also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or
+when the device is closed. Applications must take care not to free
+buffers without dequeuing. For once, the buffers remain locked until
+further, wasting physical memory. Second the driver will not be
+notified when the memory is returned to the application's free list
+and subsequently reused for other purposes, possibly completing the
+requested DMA and overwriting valuable data.
+
+ For capturing applications it is customary to enqueue a
+number of empty buffers, to start capturing and enter the read loop.
+Here the application waits until a filled buffer can be dequeued, and
+re-enqueues the buffer when the data is no longer needed. Output
+applications fill and enqueue buffers, when enough buffers are stacked
+up output is started. In the write loop, when the application
+runs out of free buffers it must wait until an empty buffer can be
+dequeued and reused. Two methods exist to suspend execution of the
+application until one or more buffers can be dequeued. By default
+VIDIOC_DQBUF blocks when no buffer is in the
+outgoing queue. When the O_NONBLOCK flag was
+given to the &func-open; function, VIDIOC_DQBUF
+returns immediately with an &EAGAIN; when no buffer is available. The
+&func-select; or &func-poll; function are always available.
+
+ To start and stop capturing or output applications call the
+&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note
+VIDIOC_STREAMOFF removes all buffers from both
+queues and unlocks all buffers as a side effect. Since there is no
+notion of doing anything "now" on a multitasking system, if an
+application needs to synchronize with another event it should examine
+the &v4l2-buffer; timestamp of captured
+buffers, or set the field before enqueuing buffers for output.
+
+ Drivers implementing user pointer I/O must
+support the VIDIOC_REQBUFS,
+VIDIOC_QBUF, VIDIOC_DQBUF,
+VIDIOC_STREAMON and
+VIDIOC_STREAMOFF ioctl, the
+select() and poll() function.
+ At the driver level select() and
+poll() are the same, and
+select() is too important to be optional. The
+rest should be evident.
+
+
+
+
+ Streaming I/O (DMA buffer importing)
+
+
+ Experimental
+ This is an experimental
+ interface and may change in the future.
+
+
+The DMABUF framework provides a generic method for sharing buffers
+between multiple devices. Device drivers that support DMABUF can export a DMA
+buffer to userspace as a file descriptor (known as the exporter role), import a
+DMA buffer from userspace using a file descriptor previously exported for a
+different or the same device (known as the importer role), or both. This
+section describes the DMABUF importer role API in V4L2.
+
+ Refer to DMABUF exporting for
+details about exporting V4L2 buffers as DMABUF file descriptors.
+
+Input and output devices support the streaming I/O method when the
+V4L2_CAP_STREAMING flag in the
+capabilities field of &v4l2-capability; returned by
+the &VIDIOC-QUERYCAP; ioctl is set. Whether importing DMA buffers through
+DMABUF file descriptors is supported is determined by calling the
+&VIDIOC-REQBUFS; ioctl with the memory type set to
+V4L2_MEMORY_DMABUF.
+
+ This I/O method is dedicated to sharing DMA buffers between different
+devices, which may be V4L devices or other video-related devices (e.g. DRM).
+Buffers (planes) are allocated by a driver on behalf of an application. Next,
+these buffers are exported to the application as file descriptors using an API
+which is specific for an allocator driver. Only such file descriptor are
+exchanged. The descriptors and meta-information are passed in &v4l2-buffer; (or
+in &v4l2-plane; in the multi-planar API case). The driver must be switched
+into DMABUF I/O mode by calling the &VIDIOC-REQBUFS; with the desired buffer
+type.
+
+
+ Initiating streaming I/O with DMABUF file descriptors
+
+
+&v4l2-requestbuffers; reqbuf;
+
+memset(&reqbuf, 0, sizeof (reqbuf));
+reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+reqbuf.memory = V4L2_MEMORY_DMABUF;
+reqbuf.count = 1;
+
+if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) {
+ if (errno == EINVAL)
+ printf("Video capturing or DMABUF streaming is not supported\n");
+ else
+ perror("VIDIOC_REQBUFS");
+
+ exit(EXIT_FAILURE);
+}
+
+
+
+ The buffer (plane) file descriptor is passed on the fly with the
+&VIDIOC-QBUF; ioctl. In case of multiplanar buffers, every plane can be
+associated with a different DMABUF descriptor. Although buffers are commonly
+cycled, applications can pass a different DMABUF descriptor at each
+VIDIOC_QBUF call.
+
+
+ Queueing DMABUF using single plane API
+
+
+int buffer_queue(int v4lfd, int index, int dmafd)
+{
+ &v4l2-buffer; buf;
+
+ memset(&buf, 0, sizeof buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_DMABUF;
+ buf.index = index;
+ buf.m.fd = dmafd;
+
+ if (ioctl(v4lfd, &VIDIOC-QBUF;, &buf) == -1) {
+ perror("VIDIOC_QBUF");
+ return -1;
+ }
+
+ return 0;
+}
+
+
+
+
+ Queueing DMABUF using multi plane API
+
+
+int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes)
+{
+ &v4l2-buffer; buf;
+ &v4l2-plane; planes[VIDEO_MAX_PLANES];
+ int i;
+
+ memset(&buf, 0, sizeof buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
+ buf.memory = V4L2_MEMORY_DMABUF;
+ buf.index = index;
+ buf.m.planes = planes;
+ buf.length = n_planes;
+
+ memset(&planes, 0, sizeof planes);
+
+ for (i = 0; i < n_planes; ++i)
+ buf.m.planes[i].m.fd = dmafd[i];
+
+ if (ioctl(v4lfd, &VIDIOC-QBUF;, &buf) == -1) {
+ perror("VIDIOC_QBUF");
+ return -1;
+ }
+
+ return 0;
+}
+
+
+
+ Captured or displayed buffers are dequeued with the
+&VIDIOC-DQBUF; ioctl. The driver can unlock the buffer at any
+time between the completion of the DMA and this ioctl. The memory is
+also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or
+when the device is closed.
+
+ For capturing applications it is customary to enqueue a
+number of empty buffers, to start capturing and enter the read loop.
+Here the application waits until a filled buffer can be dequeued, and
+re-enqueues the buffer when the data is no longer needed. Output
+applications fill and enqueue buffers, when enough buffers are stacked
+up output is started. In the write loop, when the application
+runs out of free buffers it must wait until an empty buffer can be
+dequeued and reused. Two methods exist to suspend execution of the
+application until one or more buffers can be dequeued. By default
+VIDIOC_DQBUF blocks when no buffer is in the
+outgoing queue. When the O_NONBLOCK flag was
+given to the &func-open; function, VIDIOC_DQBUF
+returns immediately with an &EAGAIN; when no buffer is available. The
+&func-select; and &func-poll; functions are always available.
+
+ To start and stop capturing or displaying applications call the
+&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctls. Note that
+VIDIOC_STREAMOFF removes all buffers from both queues and
+unlocks all buffers as a side effect. Since there is no notion of doing
+anything "now" on a multitasking system, if an application needs to synchronize
+with another event it should examine the &v4l2-buffer;
+timestamp of captured buffers, or set the field
+before enqueuing buffers for output.
+
+ Drivers implementing DMABUF importing I/O must support the
+VIDIOC_REQBUFS, VIDIOC_QBUF,
+VIDIOC_DQBUF, VIDIOC_STREAMON and
+VIDIOC_STREAMOFF ioctls, and the
+select() and poll() functions.
+
+
+
+
+ Asynchronous I/O
+
+ This method is not defined yet.
+
+
+
+ Buffers
+
+ A buffer contains data exchanged by application and
+driver using one of the Streaming I/O methods. In the multi-planar API, the
+data is held in planes, while the buffer structure acts as a container
+for the planes. Only pointers to buffers (planes) are exchanged, the data
+itself is not copied. These pointers, together with meta-information like
+timestamps or field parity, are stored in a struct
+v4l2_buffer, argument to
+the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl.
+In the multi-planar API, some plane-specific members of struct
+v4l2_buffer, such as pointers and sizes for each
+plane, are stored in struct v4l2_plane instead.
+In that case, struct v4l2_buffer contains an array of
+plane structures.
+
+ Nominally timestamps refer to the first data byte transmitted.
+In practice however the wide range of hardware covered by the V4L2 API
+limits timestamp accuracy. Often an interrupt routine will
+sample the system clock shortly after the field or frame was stored
+completely in memory. So applications must expect a constant
+difference up to one field or frame period plus a small (few scan
+lines) random error. The delay and error can be much
+larger due to compression or transmission over an external bus when
+the frames are not properly stamped by the sender. This is frequently
+the case with USB cameras. Here timestamps refer to the instant the
+field or frame was received by the driver, not the capture time. These
+devices identify by not enumerating any video standards, see .
+
+ Similar limitations apply to output timestamps. Typically
+the video hardware locks to a clock controlling the video timing, the
+horizontal and vertical synchronization pulses. At some point in the
+line sequence, possibly the vertical blanking, an interrupt routine
+samples the system clock, compares against the timestamp and programs
+the hardware to repeat the previous field or frame, or to display the
+buffer contents.
+
+ Apart of limitations of the video device and natural
+inaccuracies of all clocks, it should be noted system time itself is
+not perfectly stable. It can be affected by power saving cycles,
+warped to insert leap seconds, or even turned back or forth by the
+system administrator affecting long term measurements.
+ Since no other Linux multimedia
+API supports unadjusted time it would be foolish to introduce here. We
+must use a universally supported clock to synchronize different media,
+hence time of day.
+
+
+
+ struct <structname>v4l2_buffer</structname>
+
+ &cs-ustr;
+
+
+ __u32
+ index
+
+ Number of the buffer, set by the application. This
+field is only used for memory mapping I/O
+and can range from zero to the number of buffers allocated
+with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; count) minus one.
+
+
+ __u32
+ type
+
+ Type of the buffer, same as &v4l2-format;
+type or &v4l2-requestbuffers;
+type, set by the application. See
+
+
+ __u32
+ bytesused
+
+ The number of bytes occupied by the data in the
+buffer. It depends on the negotiated data format and may change with
+each buffer for compressed variable size data like JPEG images.
+Drivers must set this field when type
+refers to an input stream, applications when an output stream.
+
+
+ __u32
+ flags
+
+ Flags set by the application or driver, see .
+
+
+ __u32
+ field
+
+ Indicates the field order of the image in the
+buffer, see . This field is not used when
+the buffer contains VBI data. Drivers must set it when
+type refers to an input stream,
+applications when an output stream.
+
+
+ struct timeval
+ timestamp
+
+ For input streams this is time when the first data
+ byte was captured, as returned by the
+ clock_gettime() function for the relevant
+ clock id; see V4L2_BUF_FLAG_TIMESTAMP_* in
+ . For output streams the data
+ will not be displayed before this time, secondary to the nominal
+ frame rate determined by the current video standard in enqueued
+ order. Applications can for example zero this field to display
+ frames as soon as possible. The driver stores the time at which
+ the first data byte was actually sent out in the
+ timestamp field. This permits
+ applications to monitor the drift between the video and system
+ clock.
+
+
+ &v4l2-timecode;
+ timecode
+
+ When type is
+V4L2_BUF_TYPE_VIDEO_CAPTURE and the
+V4L2_BUF_FLAG_TIMECODE flag is set in
+flags, this structure contains a frame
+timecode. In V4L2_FIELD_ALTERNATE
+mode the top and bottom field contain the same timecode.
+Timecodes are intended to help video editing and are typically recorded on
+video tapes, but also embedded in compressed formats like MPEG. This
+field is independent of the timestamp and
+sequence fields.
+
+
+ __u32
+ sequence
+
+ Set by the driver, counting the frames (not fields!) in
+sequence. This field is set for both input and output devices.
+
+
+ In V4L2_FIELD_ALTERNATE mode the top and
+bottom field have the same sequence number. The count starts at zero
+and includes dropped or repeated frames. A dropped frame was received
+by an input device but could not be stored due to lack of free buffer
+space. A repeated frame was displayed again by an output device
+because the application did not pass new data in
+time.Note this may count the frames received
+e.g. over USB, without taking into account the frames dropped by the
+remote hardware due to limited compression throughput or bus
+bandwidth. These devices identify by not enumerating any video
+standards, see .
+
+
+ __u32
+ memory
+
+ This field must be set by applications and/or drivers
+in accordance with the selected I/O method. See
+
+
+ union
+ m
+
+
+
+ __u32
+ offset
+ For the single-planar API and when
+memory is V4L2_MEMORY_MMAP this
+is the offset of the buffer from the start of the device memory. The value is
+returned by the driver and apart of serving as parameter to the &func-mmap;
+function not useful for applications. See for details
+
+
+
+
+ unsigned long
+ userptr
+ For the single-planar API and when
+memory is V4L2_MEMORY_USERPTR
+this is a pointer to the buffer (casted to unsigned long type) in virtual
+memory, set by the application. See for details.
+
+
+
+
+ struct v4l2_plane
+ *planes
+ When using the multi-planar API, contains a userspace pointer
+ to an array of &v4l2-plane;. The size of the array should be put
+ in the length field of this
+ v4l2_buffer structure.
+
+
+
+ int
+ fd
+ For the single-plane API and when
+memory is V4L2_MEMORY_DMABUF this
+is the file descriptor associated with a DMABUF buffer.
+
+
+ __u32
+ length
+
+ Size of the buffer (not the payload) in bytes for the
+ single-planar API. For the multi-planar API the application sets
+ this to the number of elements in the planes
+ array. The driver will fill in the actual number of valid elements in
+ that array.
+
+
+
+ __u32
+ reserved2
+
+ A place holder for future extensions. Applications
+should set this to 0.
+
+
+ __u32
+ reserved
+
+ A place holder for future extensions. Applications
+should set this to 0.
+
+
+
+
+
+
+ struct <structname>v4l2_plane</structname>
+
+ &cs-ustr;
+
+
+ __u32
+ bytesused
+
+ The number of bytes occupied by data in the plane
+ (its payload).
+
+
+ __u32
+ length
+
+ Size in bytes of the plane (not its payload).
+
+
+ union
+ m
+
+
+
+
+
+ __u32
+ mem_offset
+ When the memory type in the containing &v4l2-buffer; is
+ V4L2_MEMORY_MMAP, this is the value that
+ should be passed to &func-mmap;, similar to the
+ offset field in &v4l2-buffer;.
+
+
+
+ unsigned long
+ userptr
+ When the memory type in the containing &v4l2-buffer; is
+ V4L2_MEMORY_USERPTR, this is a userspace
+ pointer to the memory allocated for this plane by an application.
+
+
+
+
+ int
+ fd
+ When the memory type in the containing &v4l2-buffer; is
+ V4L2_MEMORY_DMABUF, this is a file
+ descriptor associated with a DMABUF buffer, similar to the
+ fd field in &v4l2-buffer;.
+
+
+ __u32
+ data_offset
+
+ Offset in bytes to video data in the plane, if applicable.
+
+
+
+ __u32
+ reserved[11]
+
+ Reserved for future use. Should be zeroed by an
+ application.
+
+
+
+
+
+
+ enum v4l2_buf_type
+
+ &cs-def;
+
+
+ V4L2_BUF_TYPE_VIDEO_CAPTURE
+ 1
+ Buffer of a single-planar video capture stream, see .
+
+
+ V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE
+
+ 9
+ Buffer of a multi-planar video capture stream, see .
+
+
+ V4L2_BUF_TYPE_VIDEO_OUTPUT
+ 2
+ Buffer of a single-planar video output stream, see .
+
+
+ V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE
+
+ 10
+ Buffer of a multi-planar video output stream, see .
+
+
+ V4L2_BUF_TYPE_VIDEO_OVERLAY
+ 3
+ Buffer for video overlay, see .
+
+
+ V4L2_BUF_TYPE_VBI_CAPTURE
+ 4
+ Buffer of a raw VBI capture stream, see .
+
+
+ V4L2_BUF_TYPE_VBI_OUTPUT
+ 5
+ Buffer of a raw VBI output stream, see .
+
+
+ V4L2_BUF_TYPE_SLICED_VBI_CAPTURE
+ 6
+ Buffer of a sliced VBI capture stream, see .
+
+
+ V4L2_BUF_TYPE_SLICED_VBI_OUTPUT
+ 7
+ Buffer of a sliced VBI output stream, see .
+
+
+ V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY
+ 8
+ Buffer for video output overlay (OSD), see .
+
+
+
+
+
+
+ Buffer Flags
+
+ &cs-def;
+
+
+ V4L2_BUF_FLAG_MAPPED
+ 0x0001
+ The buffer resides in device memory and has been mapped
+into the application's address space, see for details.
+Drivers set or clear this flag when the
+VIDIOC_QUERYBUF, VIDIOC_QBUF or VIDIOC_DQBUF ioctl is called. Set by the driver.
+
+
+ V4L2_BUF_FLAG_QUEUED
+ 0x0002
+ Internally drivers maintain two buffer queues, an
+incoming and outgoing queue. When this flag is set, the buffer is
+currently on the incoming queue. It automatically moves to the
+outgoing queue after the buffer has been filled (capture devices) or
+displayed (output devices). Drivers set or clear this flag when the
+VIDIOC_QUERYBUF ioctl is called. After
+(successful) calling the VIDIOC_QBUF ioctl it is
+always set and after VIDIOC_DQBUF always
+cleared.
+
+
+ V4L2_BUF_FLAG_DONE
+ 0x0004
+ When this flag is set, the buffer is currently on
+the outgoing queue, ready to be dequeued from the driver. Drivers set
+or clear this flag when the VIDIOC_QUERYBUF ioctl
+is called. After calling the VIDIOC_QBUF or
+VIDIOC_DQBUF it is always cleared. Of course a
+buffer cannot be on both queues at the same time, the
+V4L2_BUF_FLAG_QUEUED and
+V4L2_BUF_FLAG_DONE flag are mutually exclusive.
+They can be both cleared however, then the buffer is in "dequeued"
+state, in the application domain to say so.
+
+
+ V4L2_BUF_FLAG_ERROR
+ 0x0040
+ When this flag is set, the buffer has been dequeued
+ successfully, although the data might have been corrupted.
+ This is recoverable, streaming may continue as normal and
+ the buffer may be reused normally.
+ Drivers set this flag when the VIDIOC_DQBUF
+ ioctl is called.
+
+
+ V4L2_BUF_FLAG_KEYFRAME
+ 0x0008
+ Drivers set or clear this flag when calling the
+VIDIOC_DQBUF ioctl. It may be set by video
+capture devices when the buffer contains a compressed image which is a
+key frame (or field), &ie; can be decompressed on its own.
+
+
+ V4L2_BUF_FLAG_PFRAME
+ 0x0010
+ Similar to V4L2_BUF_FLAG_KEYFRAME
+this flags predicted frames or fields which contain only differences to a
+previous key frame.
+
+
+ V4L2_BUF_FLAG_BFRAME
+ 0x0020
+ Similar to V4L2_BUF_FLAG_PFRAME
+ this is a bidirectional predicted frame or field. [ooc tbd]
+
+
+ V4L2_BUF_FLAG_TIMECODE
+ 0x0100
+ The timecode field is valid.
+Drivers set or clear this flag when the VIDIOC_DQBUF
+ioctl is called.
+
+
+ V4L2_BUF_FLAG_PREPARED
+ 0x0400
+ The buffer has been prepared for I/O and can be queued by the
+application. Drivers set or clear this flag when the
+VIDIOC_QUERYBUF, VIDIOC_PREPARE_BUF, VIDIOC_QBUF or VIDIOC_DQBUF ioctl is called.
+
+
+ V4L2_BUF_FLAG_NO_CACHE_INVALIDATE
+ 0x0800
+ Caches do not have to be invalidated for this buffer.
+Typically applications shall use this flag if the data captured in the buffer
+is not going to be touched by the CPU, instead the buffer will, probably, be
+passed on to a DMA-capable hardware unit for further processing or output.
+
+
+
+ V4L2_BUF_FLAG_NO_CACHE_CLEAN
+ 0x1000
+ Caches do not have to be cleaned for this buffer.
+Typically applications shall use this flag for output buffers if the data
+in this buffer has not been created by the CPU but by some DMA-capable unit,
+in which case caches have not been used.
+
+
+ V4L2_BUF_FLAG_TIMESTAMP_MASK
+ 0xe000
+ Mask for timestamp types below. To test the
+ timestamp type, mask out bits not belonging to timestamp
+ type by performing a logical and operation with buffer
+ flags and timestamp mask.
+
+
+ V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN
+ 0x0000
+ Unknown timestamp type. This type is used by
+ drivers before Linux 3.9 and may be either monotonic (see
+ below) or realtime (wall clock). Monotonic clock has been
+ favoured in embedded systems whereas most of the drivers
+ use the realtime clock. Either kinds of timestamps are
+ available in user space via
+ clock_gettime(2) using clock IDs
+ CLOCK_MONOTONIC and
+ CLOCK_REALTIME, respectively.
+
+
+ V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC
+ 0x2000
+ The buffer timestamp has been taken from the
+ CLOCK_MONOTONIC clock. To access the
+ same clock outside V4L2, use
+ clock_gettime(2) .
+
+
+ V4L2_BUF_FLAG_TIMESTAMP_COPY
+ 0x4000
+ The CAPTURE buffer timestamp has been taken from the
+ corresponding OUTPUT buffer. This flag applies only to mem2mem devices.
+
+
+
+
+
+
+ enum v4l2_memory
+
+ &cs-def;
+
+
+ V4L2_MEMORY_MMAP
+ 1
+ The buffer is used for memory
+mapping I/O.
+
+
+ V4L2_MEMORY_USERPTR
+ 2
+ The buffer is used for user
+pointer I/O.
+
+
+ V4L2_MEMORY_OVERLAY
+ 3
+ [to do]
+
+
+ V4L2_MEMORY_DMABUF
+ 4
+ The buffer is used for DMA shared
+buffer I/O.
+
+
+
+
+
+
+ Timecodes
+
+ The v4l2_timecode structure is
+designed to hold a or similar timecode.
+(struct timeval timestamps are stored in
+&v4l2-buffer; field timestamp.)
+
+
+ struct <structname>v4l2_timecode</structname>
+
+ &cs-str;
+
+
+ __u32
+ type
+ Frame rate the timecodes are based on, see .
+
+
+ __u32
+ flags
+ Timecode flags, see .
+
+
+ __u8
+ frames
+ Frame count, 0 ... 23/24/29/49/59, depending on the
+ type of timecode.
+
+
+ __u8
+ seconds
+ Seconds count, 0 ... 59. This is a binary, not BCD number.
+
+
+ __u8
+ minutes
+ Minutes count, 0 ... 59. This is a binary, not BCD number.
+
+
+ __u8
+ hours
+ Hours count, 0 ... 29. This is a binary, not BCD number.
+
+
+ __u8
+ userbits[4]
+ The "user group" bits from the timecode.
+
+
+
+
+
+
+ Timecode Types
+
+ &cs-def;
+
+
+ V4L2_TC_TYPE_24FPS
+ 1
+ 24 frames per second, i. e. film.
+
+
+ V4L2_TC_TYPE_25FPS
+ 2
+ 25 frames per second, &ie; PAL or SECAM video.
+
+
+ V4L2_TC_TYPE_30FPS
+ 3
+ 30 frames per second, &ie; NTSC video.
+
+
+ V4L2_TC_TYPE_50FPS
+ 4
+
+
+
+ V4L2_TC_TYPE_60FPS
+ 5
+
+
+
+
+
+
+
+ Timecode Flags
+
+ &cs-def;
+
+
+ V4L2_TC_FLAG_DROPFRAME
+ 0x0001
+ Indicates "drop frame" semantics for counting frames
+in 29.97 fps material. When set, frame numbers 0 and 1 at the start of
+each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
+count.
+
+
+ V4L2_TC_FLAG_COLORFRAME
+ 0x0002
+ The "color frame" flag.
+
+
+ V4L2_TC_USERBITS_field
+ 0x000C
+ Field mask for the "binary group flags".
+
+
+ V4L2_TC_USERBITS_USERDEFINED
+ 0x0000
+ Unspecified format.
+
+
+ V4L2_TC_USERBITS_8BITCHARS
+ 0x0008
+ 8-bit ISO characters.
+
+
+
+
+
+
+
+
+ Field Order
+
+ We have to distinguish between progressive and interlaced
+video. Progressive video transmits all lines of a video image
+sequentially. Interlaced video divides an image into two fields,
+containing only the odd and even lines of the image, respectively.
+Alternating the so called odd and even field are transmitted, and due
+to a small delay between fields a cathode ray TV displays the lines
+interleaved, yielding the original frame. This curious technique was
+invented because at refresh rates similar to film the image would
+fade out too quickly. Transmitting fields reduces the flicker without
+the necessity of doubling the frame rate and with it the bandwidth
+required for each channel.
+
+ It is important to understand a video camera does not expose
+one frame at a time, merely transmitting the frames separated into
+fields. The fields are in fact captured at two different instances in
+time. An object on screen may well move between one field and the
+next. For applications analysing motion it is of paramount importance
+to recognize which field of a frame is older, the temporal
+order.
+
+ When the driver provides or accepts images field by field
+rather than interleaved, it is also important applications understand
+how the fields combine to frames. We distinguish between top (aka odd) and
+bottom (aka even) fields, the spatial order: The first line
+of the top field is the first line of an interlaced frame, the first
+line of the bottom field is the second line of that frame.
+
+ However because fields were captured one after the other,
+arguing whether a frame commences with the top or bottom field is
+pointless. Any two successive top and bottom, or bottom and top fields
+yield a valid frame. Only when the source was progressive to begin
+with, ⪚ when transferring film to video, two fields may come from
+the same frame, creating a natural order.
+
+ Counter to intuition the top field is not necessarily the
+older field. Whether the older field contains the top or bottom lines
+is a convention determined by the video standard. Hence the
+distinction between temporal and spatial order of fields. The diagrams
+below should make this clearer.
+
+ All video capture and output devices must report the current
+field order. Some drivers may permit the selection of a different
+order, to this end applications initialize the
+field field of &v4l2-pix-format; before
+calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should
+have the value V4L2_FIELD_ANY (0).
+
+
+ enum v4l2_field
+
+ &cs-def;
+
+
+ V4L2_FIELD_ANY
+ 0
+ Applications request this field order when any
+one of the V4L2_FIELD_NONE,
+V4L2_FIELD_TOP,
+V4L2_FIELD_BOTTOM, or
+V4L2_FIELD_INTERLACED formats is acceptable.
+Drivers choose depending on hardware capabilities or e. g. the
+requested image size, and return the actual field order. &v4l2-buffer;
+field can never be
+V4L2_FIELD_ANY.
+
+
+ V4L2_FIELD_NONE
+ 1
+ Images are in progressive format, not interlaced.
+The driver may also indicate this order when it cannot distinguish
+between V4L2_FIELD_TOP and
+V4L2_FIELD_BOTTOM.
+
+
+ V4L2_FIELD_TOP
+ 2
+ Images consist of the top (aka odd) field only.
+
+
+ V4L2_FIELD_BOTTOM
+ 3
+ Images consist of the bottom (aka even) field only.
+Applications may wish to prevent a device from capturing interlaced
+images because they will have "comb" or "feathering" artefacts around
+moving objects.
+
+
+ V4L2_FIELD_INTERLACED
+ 4
+ Images contain both fields, interleaved line by
+line. The temporal order of the fields (whether the top or bottom
+field is first transmitted) depends on the current video standard.
+M/NTSC transmits the bottom field first, all other standards the top
+field first.
+
+
+ V4L2_FIELD_SEQ_TB
+ 5
+ Images contain both fields, the top field lines
+are stored first in memory, immediately followed by the bottom field
+lines. Fields are always stored in temporal order, the older one first
+in memory. Image sizes refer to the frame, not fields.
+
+
+ V4L2_FIELD_SEQ_BT
+ 6
+ Images contain both fields, the bottom field
+lines are stored first in memory, immediately followed by the top
+field lines. Fields are always stored in temporal order, the older one
+first in memory. Image sizes refer to the frame, not fields.
+
+
+ V4L2_FIELD_ALTERNATE
+ 7
+ The two fields of a frame are passed in separate
+buffers, in temporal order, &ie; the older one first. To indicate the field
+parity (whether the current field is a top or bottom field) the driver
+or application, depending on data direction, must set &v4l2-buffer;
+field to
+V4L2_FIELD_TOP or
+V4L2_FIELD_BOTTOM. Any two successive fields pair
+to build a frame. If fields are successive, without any dropped fields
+between them (fields can drop individually), can be determined from
+the &v4l2-buffer; sequence field. Image
+sizes refer to the frame, not fields. This format cannot be selected
+when using the read/write I/O method.
+
+
+ V4L2_FIELD_INTERLACED_TB
+ 8
+ Images contain both fields, interleaved line by
+line, top field first. The top field is transmitted first.
+
+
+ V4L2_FIELD_INTERLACED_BT
+ 9
+ Images contain both fields, interleaved line by
+line, top field first. The bottom field is transmitted first.
+
+
+
+
+
+
+ Field Order, Top Field First Transmitted
+
+
+
+
+
+
+
+
+
+
+
+ Field Order, Bottom Field First Transmitted
+
+
+
+
+
+
+
+
+
+
--
cgit v1.3.1