diff --git a/Documentation/DocBook/v4l/io.xml b/Documentation/DocBook/v4l/io.xml index f92f24323b2a..e870330cbf77 100644 --- a/Documentation/DocBook/v4l/io.xml +++ b/Documentation/DocBook/v4l/io.xml @@ -589,7 +589,8 @@ number of a video input as in &v4l2-input; field A place holder for future extensions and custom (driver defined) buffer types -V4L2_BUF_TYPE_PRIVATE and higher. +V4L2_BUF_TYPE_PRIVATE and higher. Applications +should set this to 0. diff --git a/Documentation/DocBook/v4l/vidioc-qbuf.xml b/Documentation/DocBook/v4l/vidioc-qbuf.xml index 187081778154..b843bd7b3897 100644 --- a/Documentation/DocBook/v4l/vidioc-qbuf.xml +++ b/Documentation/DocBook/v4l/vidioc-qbuf.xml @@ -54,12 +54,10 @@ to enqueue an empty (capturing) or filled (output) buffer in the driver's incoming queue. The semantics depend on the selected I/O method. - To enqueue a memory mapped -buffer applications set the type field of a -&v4l2-buffer; to the same buffer type as previously &v4l2-format; -type and &v4l2-requestbuffers; -type, the memory -field to V4L2_MEMORY_MMAP and the + To enqueue a buffer applications set the type +field of a &v4l2-buffer; to the same buffer type as was previously used +with &v4l2-format; type and &v4l2-requestbuffers; +type. Applications must also set the index field. Valid index numbers range from zero to the number of buffers allocated with &VIDIOC-REQBUFS; (&v4l2-requestbuffers; count) minus one. The @@ -70,8 +68,19 @@ intended for output (type is V4L2_BUF_TYPE_VBI_OUTPUT) applications must also initialize the bytesused, field and -timestamp fields. See for details. When +timestamp fields, see for details. +Applications must also set flags to 0. If a driver +supports capturing from specific video inputs and you want to specify a video +input, then flags should be set to +V4L2_BUF_FLAG_INPUT and the field +input must be initialized to the desired input. +The reserved field must be set to 0. + + + To enqueue a memory mapped +buffer applications set the memory +field to V4L2_MEMORY_MMAP. When VIDIOC_QBUF is called with a pointer to this structure the driver sets the V4L2_BUF_FLAG_MAPPED and @@ -81,14 +90,10 @@ structure the driver sets the &EINVAL;. To enqueue a user pointer -buffer applications set the type field of a -&v4l2-buffer; to the same buffer type as previously &v4l2-format; -type and &v4l2-requestbuffers; -type, the memory -field to V4L2_MEMORY_USERPTR and the +buffer applications set the memory +field to V4L2_MEMORY_USERPTR, the m.userptr field to the address of the -buffer and length to its size. When the -buffer is intended for output additional fields must be set as above. +buffer and length to its size. When VIDIOC_QBUF is called with a pointer to this structure the driver sets the V4L2_BUF_FLAG_QUEUED flag and clears the V4L2_BUF_FLAG_MAPPED and @@ -96,13 +101,14 @@ flag and clears the V4L2_BUF_FLAG_MAPPED and flags field, or it returns an error code. This ioctl locks the memory pages of the buffer in physical memory, they cannot be swapped out to disk. Buffers remain locked until -dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl are +dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is called, or until the device is closed. Applications call the VIDIOC_DQBUF ioctl to dequeue a filled (capturing) or displayed (output) buffer from the driver's outgoing queue. They just set the -type and memory +type, memory +and reserved fields of a &v4l2-buffer; as above, when VIDIOC_DQBUF is called with a pointer to this structure the driver fills the remaining fields or returns an error code. diff --git a/Documentation/DocBook/v4l/vidioc-querybuf.xml b/Documentation/DocBook/v4l/vidioc-querybuf.xml index d834993e6191..e649805a4908 100644 --- a/Documentation/DocBook/v4l/vidioc-querybuf.xml +++ b/Documentation/DocBook/v4l/vidioc-querybuf.xml @@ -54,12 +54,13 @@ buffer at any time after buffers have been allocated with the &VIDIOC-REQBUFS; ioctl. Applications set the type field - of a &v4l2-buffer; to the same buffer type as previously + of a &v4l2-buffer; to the same buffer type as was previously used with &v4l2-format; type and &v4l2-requestbuffers; type, and the index field. Valid index numbers range from zero to the number of buffers allocated with &VIDIOC-REQBUFS; (&v4l2-requestbuffers; count) minus one. +The reserved field should to set to 0. After calling VIDIOC_QUERYBUF with a pointer to this structure drivers return an error code or fill the rest of the structure. @@ -68,8 +69,8 @@ the structure. V4L2_BUF_FLAG_MAPPED, V4L2_BUF_FLAG_QUEUED and V4L2_BUF_FLAG_DONE flags will be valid. The -memory field will be set to -V4L2_MEMORY_MMAP, the m.offset +memory field will be set to the current +I/O method, the m.offset contains the offset of the buffer from the start of the device memory, the length field its size. The driver may or may not set the remaining fields and flags, they are meaningless in diff --git a/Documentation/DocBook/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/v4l/vidioc-reqbufs.xml index bab38084454f..1c0816372074 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.