From f4980c5e8ea66cca3a0966a35b36ba5932e5dca1 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 13 Sep 2009 20:45:57 -0300 Subject: staging-specs: Add a staging tree for Documentation/DocBook From: Mauro Carvalho Chehab This patch basically copies V4L and DVB DocBook specs into a single file, under a temporary staging tree. This is meant to add the set of V4L/DVB API specifications at Linux Kernel. For now, it just renames the *sgml files to *xml and creates a common body for both API's, dividing them into two parts. Later patches will add some glue for the two specs, move IR to a common part (since IR keycodes are common to both API's) and add it into linux/Documentation/DocBook. Comments and reviews are welcome. Priority: normal Signed-off-by: Mauro Carvalho Chehab --- staging-specs/v4l/vidioc-reqbufs.xml | 160 +++++++++++++++++++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 staging-specs/v4l/vidioc-reqbufs.xml (limited to 'staging-specs/v4l/vidioc-reqbufs.xml') diff --git a/staging-specs/v4l/vidioc-reqbufs.xml b/staging-specs/v4l/vidioc-reqbufs.xml new file mode 100644 index 000000000..bab380844 --- /dev/null +++ b/staging-specs/v4l/vidioc-reqbufs.xml @@ -0,0 +1,160 @@ + + + ioctl VIDIOC_REQBUFS + &manvol; + + + + VIDIOC_REQBUFS + Initiate Memory Mapping or User Pointer I/O + + + + + + int ioctl + int fd + int request + struct v4l2_requestbuffers *argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_REQBUFS + + + + argp + + + + + + + + + Description + + This ioctl is used to initiate memory +mapped or user pointer +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. + + To allocate device buffers applications initialize three +fields of a 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 +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, +one displayed and one filled by the application. + When memory mapping I/O is not supported the ioctl +returns an &EINVAL;. + + Applications can call VIDIOC_REQBUFS +again to change the number of buffers, however this cannot succeed +when any buffers are still mapped. A count +value of zero frees all buffers, after aborting or finishing any DMA +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> + + &cs-str; + + + __u32 + count + The number of buffers requested or granted. This +field is only used when memory is set to +V4L2_MEMORY_MMAP. + + + &v4l2-buf-type; + type + Type of the stream or buffers, this is the same +as the &v4l2-format; type field. See for valid values. + + + &v4l2-memory; + memory + Applications set this field to +V4L2_MEMORY_MMAP or +V4L2_MEMORY_USERPTR. + + + __u32 + reserved[2] + A place holder for future extensions and custom +(driver defined) buffer types V4L2_BUF_TYPE_PRIVATE and +higher. + + + +
+ + + + &return-value; + + + + EBUSY + + The driver supports multiple opens and I/O is already +in progress, or reallocation of buffers was attempted although one or +more are still mapped. + + + + EINVAL + + The buffer type (type field) or the +requested I/O method (memory) is not +supported. + + + + + + + -- cgit v1.2.3