There are lots of ioctls mentioned there that aren't cross-referenced.
Convert the const to cross references. That makes it visually
better, and improves navigation along the document.
While here, remove bad whitespaces.
Signed-off-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>
---
Documentation/linux_tv/media/v4l/mmap.rst | 195 +++++++++++++++---------------
1 file changed, 98 insertions(+), 97 deletions(-)
diff --git a/Documentation/linux_tv/media/v4l/mmap.rst b/Documentation/linux_tv/media/v4l/mmap.rst
index 976bd2cf247b..2171b18c1aab 100644
--- a/Documentation/linux_tv/media/v4l/mmap.rst
+++ b/Documentation/linux_tv/media/v4l/mmap.rst
@@ -58,8 +58,8 @@ possible with the :ref:`munmap() <func-munmap>` function.
struct v4l2_requestbuffers reqbuf;
struct {
- void *start;
- size_t length;
+ void *start;
+ size_t length;
} *buffers;
unsigned int i;
@@ -69,57 +69,57 @@ possible with the :ref:`munmap() <func-munmap>` function.
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");
+ if (errno == EINVAL)
+ printf("Video capturing or mmap-streaming is not supported\\n");
+ else
+ 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);
+ /* 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++) {
- struct v4l2_buffer buffer;
+ struct v4l2_buffer buffer;
- memset(&buffer, 0, sizeof(buffer));
- buffer.type = reqbuf.type;
- buffer.memory = V4L2_MEMORY_MMAP;
- buffer.index = i;
+ 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);
- }
+ if (-1 == ioctl (fd, VIDIOC_QUERYBUF, &buffer)) {
+ perror("VIDIOC_QUERYBUF");
+ exit(EXIT_FAILURE);
+ }
- buffers[i].length = buffer.length; /* remember for munmap() */
+ 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);
- }
+ 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);
+ munmap(buffers[i].start, buffers[i].length);
.. code-block:: c
@@ -130,8 +130,8 @@ possible with the :ref:`munmap() <func-munmap>` function.
#define FMT_NUM_PLANES = 3
struct {
- void *start[FMT_NUM_PLANES];
- size_t length[FMT_NUM_PLANES];
+ void *start[FMT_NUM_PLANES];
+ size_t length[FMT_NUM_PLANES];
} *buffers;
unsigned int i, j;
@@ -141,66 +141,66 @@ possible with the :ref:`munmap() <func-munmap>` function.
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");
+ if (errno == EINVAL)
+ printf("Video capturing or mmap-streaming is not supported\\n");
+ else
+ 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);
+ /* 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++) {
- struct v4l2_buffer buffer;
- struct v4l2_plane planes[FMT_NUM_PLANES];
+ struct v4l2_buffer buffer;
+ struct 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;
+ 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);
- }
+ 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() */
+ /* 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);
+ 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);
- }
- }
+ 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]);
+ 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
@@ -224,37 +224,38 @@ 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.
+up the output is started with :ref:`VIDIOC_STREAMON <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
-:ref:`VIDIOC_QBUF` and
-:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The status of a buffer being
-mapped, enqueued, full or empty can be determined at any time using the
-:ref:`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
-:ref:`open() <func-open>` function, ``VIDIOC_DQBUF`` returns
-immediately with an ``EAGAIN`` error code when no buffer is available. The
-:ref:`select() <func-select>` or :ref:`poll() <func-poll>` functions
-are always available.
+To enqueue and dequeue a buffer applications use the :ref:`VIDIOC_QBUF`
+and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The status of a buffer
+being mapped, enqueued, full or empty can be determined at any time
+using the :ref:`VIDIOC_QUERYBUF` ioctl. Two methods exist to suspend
+execution of the application until one or more buffers can be dequeued.
+By default :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` blocks when no buffer is
+in the outgoing queue. When the ``O_NONBLOCK`` flag was given to the
+:ref:`open() <func-open>` function, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`
+returns immediately with an ``EAGAIN`` error code when no buffer is
+available. The :ref:`select() <func-select>` or :ref:`poll()
+<func-poll>` functions are always available.
To start and stop capturing or output applications call the
-:ref:`VIDIOC_STREAMON` and
-:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` 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 struct :ref:`v4l2_buffer <v4l2-buffer>`
-``timestamp`` of captured or outputted buffers.
+:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF
+<VIDIOC_STREAMON>` ioctl. Note :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
+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 struct ::ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured
+or outputted buffers.
Drivers implementing memory mapping I/O must support the
-``VIDIOC_REQBUFS``, ``VIDIOC_QUERYBUF``, ``VIDIOC_QBUF``,
-``VIDIOC_DQBUF``, ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl,
-the :ref:`mmap() <func-mmap>`, :ref:`munmap() <func-munmap>`, :ref:`select() <func-select>` and
-:ref:`poll() <func-poll>` function. [3]_
+:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QUERYBUF
+<VIDIOC_QUERYBUF>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF
+<VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
+and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the :ref:`mmap()
+<func-mmap>`, :ref:`munmap() <func-munmap>`, :ref:`select()
+<func-select>` and :ref:`poll() <func-poll>` function. [3]_
[capture example]
--
2.7.4
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
