X-Git-Url: https://git.openpandora.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=Documentation%2FDocBook%2Fv4l%2Fio.xml;h=227e7ac45a06c4dbf3ac91973e492c3301df983f;hb=9f34217c846a96dea03f4418e2f27423658d3542;hp=d424886beda051a7f9bbe6db441c1d76bdb62250;hpb=f7ddc2b6cd880a259db338925d03bdc01f1d26c1;p=pandora-kernel.git
diff --git a/Documentation/DocBook/v4l/io.xml b/Documentation/DocBook/v4l/io.xml
index d424886beda0..227e7ac45a06 100644
--- a/Documentation/DocBook/v4l/io.xml
+++ b/Documentation/DocBook/v4l/io.xml
@@ -121,18 +121,22 @@ 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. The m.offset and
-length returned in a &v4l2-buffer; are
-passed as sixth and second parameter to the
-mmap() function. 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.
+&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
-
+ Mapping buffers in the single-planar API
&v4l2-requestbuffers; reqbuf;
struct {
@@ -141,63 +145,145 @@ struct {
} *buffers;
unsigned int i;
-memset (&reqbuf, 0, sizeof (reqbuf));
+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");
+ printf("Video capturing or mmap-streaming is not supported\n");
else
- perror ("VIDIOC_REQBUFS");
+ perror("VIDIOC_REQBUFS");
- exit (EXIT_FAILURE);
+ 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);
+ printf("Not enough buffer memory\n");
+ exit(EXIT_FAILURE);
}
-buffers = calloc (reqbuf.count, sizeof (*buffers));
-assert (buffers != NULL);
+buffers = calloc(reqbuf.count, sizeof(*buffers));
+assert(buffers != NULL);
for (i = 0; i < reqbuf.count; i++) {
&v4l2-buffer; buffer;
- memset (&buffer, 0, sizeof (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);
+ 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);
+ 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);
+ 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++)
- munmap (buffers[i].start, buffers[i].length);
+ for (j = 0; j < FMT_NUM_PLANES; j++)
+ munmap(buffers[i].start[j], buffers[i].length[j]);
@@ -286,13 +372,13 @@ 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 are allocated by the application
+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;. The driver must be switched
-into user pointer I/O mode by calling the &VIDIOC-REQBUFS; with the
-desired buffer type. No buffers are allocated beforehands,
-consequently they are not indexed and cannot be queried like mapped
+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.
@@ -316,7 +402,7 @@ if (ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) {
- Buffer addresses and sizes are passed on the fly with the
+ 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
@@ -396,11 +482,18 @@ rest should be evident.
Buffers
A buffer contains data exchanged by application and
-driver using one of the Streaming I/O methods. Only pointers to
-buffers 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.
+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
@@ -551,26 +644,40 @@ in accordance with the selected I/O method.
__u32
offset
- 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.
+ 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
- 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.
+ 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.
__u32
length
- Size of the buffer (not the payload) in bytes.
+ Size of the buffer (not the payload) in bytes for the
+ single-planar API. For the multi-planar API should contain the
+ number of elements in the planes array.
+
__u32
@@ -596,6 +703,66 @@ 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.
+
+
+
+ __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
@@ -604,13 +771,27 @@ should set this to 0.
V4L2_BUF_TYPE_VIDEO_CAPTURE
1
- Buffer of a video capture stream, see 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 video output stream, see 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 .