From 995f5fefb0c6abba3688b3aadf40e422b64b814a Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Sat, 20 Feb 2010 09:41:03 -0300 Subject: V4L/DVB: media-spec: Fix documentation mistakes regarding I/O streaming The media spec contains several errors in the description of the I/O streaming ioctls, in particular with respect to the userptr I/O method. The most important change is that you really need to set count and index in v4l2_requestbuffer and v4l2_buffer when dealing with user pointer streaming. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/v4l/vidioc-reqbufs.xml | 36 ++++++++++------------------ 1 file changed, 13 insertions(+), 23 deletions(-) (limited to 'Documentation/DocBook/v4l/vidioc-reqbufs.xml') diff --git a/Documentation/DocBook/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/v4l/vidioc-reqbufs.xml index bab38084454..1c081637207 100644 --- a/Documentation/DocBook/v4l/vidioc-reqbufs.xml +++ b/Documentation/DocBook/v4l/vidioc-reqbufs.xml @@ -54,23 +54,23 @@ I/O. Memory mapped buffers are located in device memory and must be allocated with this ioctl before they can be mapped into the application's address space. User buffers are allocated by applications themselves, and this ioctl is merely used to switch the -driver into user pointer I/O mode. +driver into user pointer I/O mode and to setup some internal structures. - To allocate device buffers applications initialize three -fields of a v4l2_requestbuffers structure. + To allocate device buffers applications initialize all +fields of the v4l2_requestbuffers structure. They set the type field to the respective stream or buffer type, the count field to -the desired number of buffers, and memory -must be set to V4L2_MEMORY_MMAP. When the ioctl -is called with a pointer to this structure the driver attempts to -allocate the requested number of buffers and stores the actual number +the desired number of buffers, memory +must be set to the requested I/O method and the reserved array +must be zeroed. When the ioctl +is called with a pointer to this structure the driver will attempt to allocate +the requested number of buffers and it stores the actual number allocated in the count field. It can be smaller than the number requested, even zero, when the driver runs out -of free memory. A larger number is possible when the driver requires -more buffers to function correctly. - For example video output requires at least two buffers, +of free memory. A larger number is also possible when the driver requires +more buffers to function correctly. For example video output requires at least two buffers, one displayed and one filled by the application. - When memory mapping I/O is not supported the ioctl + When the I/O method is not supported the ioctl returns an &EINVAL;. Applications can call VIDIOC_REQBUFS @@ -81,14 +81,6 @@ in progress, an implicit &VIDIOC-STREAMOFF;. - To negotiate user pointer I/O, applications initialize only -the type field and set -memory to -V4L2_MEMORY_USERPTR. When the ioctl is called -with a pointer to this structure the driver prepares for user pointer -I/O, when this I/O method is not supported the ioctl returns an -&EINVAL;. - struct <structname>v4l2_requestbuffers</structname> @@ -97,9 +89,7 @@ I/O, when this I/O method is not supported the ioctl returns an __u32 count - The number of buffers requested or granted. This -field is only used when memory is set to -V4L2_MEMORY_MMAP. + The number of buffers requested or granted. &v4l2-buf-type; @@ -120,7 +110,7 @@ as the &v4l2-format; type field. See reserved[2] A place holder for future extensions and custom (driver defined) buffer types V4L2_BUF_TYPE_PRIVATE and -higher. +higher. This array should be zeroed by applications. -- cgit v1.2.2