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-qbuf.xml | 168 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 staging-specs/v4l/vidioc-qbuf.xml (limited to 'staging-specs/v4l/vidioc-qbuf.xml') diff --git a/staging-specs/v4l/vidioc-qbuf.xml b/staging-specs/v4l/vidioc-qbuf.xml new file mode 100644 index 000000000..187081778 --- /dev/null +++ b/staging-specs/v4l/vidioc-qbuf.xml @@ -0,0 +1,168 @@ + + + ioctl VIDIOC_QBUF, VIDIOC_DQBUF + &manvol; + + + + VIDIOC_QBUF + VIDIOC_DQBUF + Exchange a buffer with the driver + + + + + + int ioctl + int fd + int request + struct v4l2_buffer *argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_QBUF, VIDIOC_DQBUF + + + + argp + + + + + + + + + Description + + Applications call the VIDIOC_QBUF ioctl +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 +index field. Valid index numbers range from +zero to the number of buffers allocated with &VIDIOC-REQBUFS; +(&v4l2-requestbuffers; count) minus one. The +contents of the struct v4l2_buffer returned +by a &VIDIOC-QUERYBUF; ioctl will do as well. When the buffer is +intended for output (type is +V4L2_BUF_TYPE_VIDEO_OUTPUT or +V4L2_BUF_TYPE_VBI_OUTPUT) applications must also +initialize the bytesused, +field and +timestamp fields. See for details. When +VIDIOC_QBUF is called with a pointer to this +structure the driver sets the +V4L2_BUF_FLAG_MAPPED and +V4L2_BUF_FLAG_QUEUED flags and clears the +V4L2_BUF_FLAG_DONE flag in the +flags field, or it returns an +&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 +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. +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 +V4L2_BUF_FLAG_DONE flags in the +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 +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 +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. + + By default VIDIOC_DQBUF blocks when no +buffer is in the outgoing queue. When the +O_NONBLOCK flag was given to the &func-open; +function, VIDIOC_DQBUF returns immediately +with an &EAGAIN; when no buffer is available. + + The v4l2_buffer structure is +specified in . + + + + &return-value; + + + + EAGAIN + + Non-blocking I/O has been selected using +O_NONBLOCK and no buffer was in the outgoing +queue. + + + + EINVAL + + The buffer type is not +supported, or the index is out of bounds, +or no buffers have been allocated yet, or the +userptr or +length are invalid. + + + + ENOMEM + + Not enough physical or virtual memory was available to +enqueue a user pointer buffer. + + + + EIO + + VIDIOC_DQBUF failed due to an +internal error. Can also indicate temporary problems like signal +loss. Note the driver might dequeue an (empty) buffer despite +returning an error, or even stop capturing. + + + + + + + -- cgit v1.2.3