From 4266129964b8238526936d723de65b419d8069c6 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 31 May 2011 16:27:44 -0300 Subject: [media] DocBook: Move all media docbook stuff into its own directory This patch addresses several issues pointed by Randy Dunlap at changeset ece722c: - In the generated index.html file, "media" is listed first, but it should be listed in alphabetical order, not first. - The generated files are (hidden) in .tmpmedia/ - The link from the top-level index.html file to "media" is to media/index.html, but the file is actually in .tmpmedia/media/index.html - Please build docs with and without using "O=builddir" and test that. - Would it be possible for media to have its own Makefile instead of merging into this one? Due to the way cleandocs target works, I had to rename the media DocBook to media_api, otherwise cleandocs would remove the /media directory. Thanks-to: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/io.xml | 1265 ++++++++++++++++++++++++++++++++ 1 file changed, 1265 insertions(+) create mode 100644 Documentation/DocBook/media/v4l/io.xml (limited to 'Documentation/DocBook/media/v4l/io.xml') diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml new file mode 100644 index 0000000..227e7ac --- /dev/null +++ b/Documentation/DocBook/media/v4l/io.xml @@ -0,0 +1,1265 @@ + Input/Output + + The V4L2 API defines several different methods to read from or +write to a device. All drivers exchanging data with applications must +support at least one of them. + + The classic I/O method using the read() +and write() function is automatically selected +after opening a V4L2 device. When the driver does not support this +method attempts to read or write will fail at any time. + + Other methods must be negotiated. To select the streaming I/O +method with memory mapped or user buffers applications call the +&VIDIOC-REQBUFS; ioctl. The asynchronous I/O method is not defined +yet. + + Video overlay can be considered another I/O method, although +the application does not directly receive the image data. It is +selected by initiating video overlay with the &VIDIOC-S-FMT; ioctl. +For more information see . + + Generally exactly one I/O method, including overlay, is +associated with each file descriptor. The only exceptions are +applications not exchanging data with a driver ("panel applications", +see ) and drivers permitting simultaneous video capturing +and overlay using the same file descriptor, for compatibility with V4L +and earlier versions of V4L2. + + VIDIOC_S_FMT and +VIDIOC_REQBUFS would permit this to some degree, +but for simplicity drivers need not support switching the I/O method +(after first switching away from read/write) other than by closing +and reopening the device. + + The following sections describe the various I/O methods in +more detail. + +
+ Read/Write + + Input and output devices support the +read() and write() function, +respectively, when the V4L2_CAP_READWRITE flag in +the capabilities field of &v4l2-capability; +returned by the &VIDIOC-QUERYCAP; ioctl is set. + + Drivers may need the CPU to copy the data, but they may also +support DMA to or from user memory, so this I/O method is not +necessarily less efficient than other methods merely exchanging buffer +pointers. It is considered inferior though because no meta-information +like frame counters or timestamps are passed. This information is +necessary to recognize frame dropping and to synchronize with other +data streams. However this is also the simplest I/O method, requiring +little or no setup to exchange data. It permits command line stunts +like this (the vidctrl tool is +fictitious): + + + +> vidctrl /dev/video --input=0 --format=YUYV --size=352x288 +> dd if=/dev/video of=myimage.422 bs=202752 count=1 + + + + To read from the device applications use the +&func-read; function, to write the &func-write; function. +Drivers must implement one I/O method if they +exchange data with applications, but it need not be this. + It would be desirable if applications could depend on +drivers supporting all I/O interfaces, but as much as the complex +memory mapping I/O can be inadequate for some devices we have no +reason to require this interface, which is most useful for simple +applications capturing still images. + When reading or writing is supported, the driver +must also support the &func-select; and &func-poll; +function. + At the driver level select() and +poll() are the same, and +select() is too important to be optional. + +
+ +
+ Streaming I/O (Memory Mapping) + + Input and output devices support this I/O method when the +V4L2_CAP_STREAMING flag in the +capabilities field of &v4l2-capability; +returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two +streaming methods, to determine if the memory mapping flavor is +supported applications must call the &VIDIOC-REQBUFS; ioctl. + + Streaming is an I/O method where only pointers to buffers +are exchanged between application and driver, the data itself is not +copied. Memory mapping is primarily intended to map buffers in device +memory into the application's address space. Device memory can be for +example the video memory on a graphics card with a video capture +add-on. However, being the most efficient I/O method available for a +long time, many other drivers support streaming as well, allocating +buffers in DMA-able main memory. + + A driver can support many sets of buffers. Each set is +identified by a unique buffer type value. The sets are independent and +each set can hold a different type of data. To access different sets +at the same time different file descriptors must be used. + One could use one file descriptor and set the buffer +type field accordingly when calling &VIDIOC-QBUF; etc., but it makes +the select() function ambiguous. We also like the +clean approach of one file descriptor per logical stream. Video +overlay for example is also a logical stream, although the CPU is not +needed for continuous operation. + + + To allocate device buffers applications call the +&VIDIOC-REQBUFS; ioctl with the desired number of buffers and buffer +type, for example V4L2_BUF_TYPE_VIDEO_CAPTURE. +This ioctl can also be used to change the number of buffers or to free +the allocated memory, provided none of the buffers are still +mapped. + + Before applications can access the buffers they must map +them into their address space with the &func-mmap; function. The +location of the buffers in device memory can be determined with the +&VIDIOC-QUERYBUF; ioctl. In the single-planar API case, the +m.offset and length +returned in a &v4l2-buffer; are passed as sixth and second parameter to the +mmap() function. When using the multi-planar API, +struct &v4l2-buffer; contains an array of &v4l2-plane; structures, each +containing its own m.offset and +length. When using the multi-planar API, every +plane of every buffer has to be mapped separately, so the number of +calls to &func-mmap; should be equal to number of buffers times number of +planes in each buffer. The offset and length values must not be modified. +Remember, the buffers are allocated in physical memory, as opposed to virtual +memory, which can be swapped out to disk. Applications should free the buffers +as soon as possible with the &func-munmap; function. + + + Mapping buffers in the single-planar API + +&v4l2-requestbuffers; reqbuf; +struct { + void *start; + size_t length; +} *buffers; +unsigned int i; + +memset(&reqbuf, 0, sizeof(reqbuf)); +reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; +reqbuf.memory = V4L2_MEMORY_MMAP; +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"); + + 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); +} + +buffers = calloc(reqbuf.count, sizeof(*buffers)); +assert(buffers != NULL); + +for (i = 0; i < reqbuf.count; i++) { + &v4l2-buffer; buffer; + + 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); + } + + 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); + + 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); + + + + + Mapping buffers in the multi-planar API + +&v4l2-requestbuffers; reqbuf; +/* Our current format uses 3 planes per buffer */ +#define FMT_NUM_PLANES = 3; + +struct { + void *start[FMT_NUM_PLANES]; + size_t length[FMT_NUM_PLANES]; +} *buffers; +unsigned int i, j; + +memset(&reqbuf, 0, sizeof(reqbuf)); +reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; +reqbuf.memory = V4L2_MEMORY_MMAP; +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"); + + 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); +} + +buffers = calloc(reqbuf.count, sizeof(*buffers)); +assert(buffers != NULL); + +for (i = 0; i < reqbuf.count; i++) { + &v4l2-buffer; buffer; + &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; + + 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() */ + + 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); + } + } +} + +/* 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]); + + + + Conceptually streaming drivers maintain two buffer queues, an incoming +and an outgoing queue. They separate the synchronous capture or output +operation locked to a video clock from the application which is +subject to random disk or network delays and preemption by +other processes, thereby reducing the probability of data loss. +The queues are organized as FIFOs, buffers will be +output in the order enqueued in the incoming FIFO, and were +captured in the order dequeued from the outgoing FIFO. + + The driver may require a minimum number of buffers enqueued +at all times to function, apart of this no limit exists on the number +of buffers applications can enqueue in advance, or dequeue and +process. They can also enqueue in a different order than buffers have +been dequeued, and the driver can fill enqueued +empty buffers in any order. + Random enqueue order permits applications processing +images out of order (such as video codecs) to return buffers earlier, +reducing the probability of data loss. Random fill order allows +drivers to reuse buffers on a LIFO-basis, taking advantage of caches +holding scatter-gather lists and the like. + The index number of a buffer (&v4l2-buffer; +index) plays no role here, it only +identifies the buffer. + + Initially all mapped buffers are in dequeued state, +inaccessible by the driver. For capturing applications it is customary +to first enqueue all 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. + + To enqueue and dequeue a buffer applications use the +&VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. The status of a buffer being +mapped, enqueued, full or empty can be determined at any time using the +&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 &func-open; function, VIDIOC_DQBUF +returns immediately with an &EAGAIN; when no buffer is available. The +&func-select; or &func-poll; function are always available. + + To start and stop capturing or output applications call the +&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; 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 &v4l2-buffer; +timestamp of captured buffers, or set the +field before enqueuing buffers for output. + + Drivers implementing memory mapping I/O must +support the VIDIOC_REQBUFS, +VIDIOC_QUERYBUF, +VIDIOC_QBUF, VIDIOC_DQBUF, +VIDIOC_STREAMON and +VIDIOC_STREAMOFF ioctl, the +mmap(), munmap(), +select() and poll() +function. + At the driver level select() and +poll() are the same, and +select() is too important to be optional. The +rest should be evident. + + + [capture example] + +
+ +
+ Streaming I/O (User Pointers) + + Input and output devices support this I/O method when the +V4L2_CAP_STREAMING flag in the +capabilities field of &v4l2-capability; +returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user +pointer method (not only memory mapping) is supported must be +determined by calling the &VIDIOC-REQBUFS; ioctl. + + This I/O method combines advantages of the read/write and +memory mapping methods. Buffers (planes) are allocated by the application +itself, and can reside for example in virtual or shared memory. Only +pointers to data are exchanged, these pointers and meta-information +are passed in &v4l2-buffer; (or in &v4l2-plane; in the multi-planar API case). +The driver must be switched into user pointer I/O mode by calling the +&VIDIOC-REQBUFS; with the desired buffer type. No buffers (planes) are allocated +beforehand, consequently they are not indexed and cannot be queried like mapped +buffers with the VIDIOC_QUERYBUF ioctl. + + + Initiating streaming I/O with user pointers + + +&v4l2-requestbuffers; reqbuf; + +memset (&reqbuf, 0, sizeof (reqbuf)); +reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; +reqbuf.memory = V4L2_MEMORY_USERPTR; + +if (ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) { + if (errno == EINVAL) + printf ("Video capturing or user pointer streaming is not supported\n"); + else + perror ("VIDIOC_REQBUFS"); + + exit (EXIT_FAILURE); +} + + + + Buffer (plane) addresses and sizes are passed on the fly with the +&VIDIOC-QBUF; ioctl. Although buffers are commonly cycled, +applications can pass different addresses and sizes at each +VIDIOC_QBUF call. If required by the hardware the +driver swaps memory pages within physical memory to create a +continuous area of memory. This happens transparently to the +application in the virtual memory subsystem of the kernel. When buffer +pages have been swapped out to disk they are brought back and finally +locked in physical memory for DMA. + We expect that frequently used buffers are typically not +swapped out. Anyway, the process of swapping, locking or generating +scatter-gather lists may be time consuming. The delay can be masked by +the depth of the incoming buffer queue, and perhaps by maintaining +caches assuming a buffer will be soon enqueued again. On the other +hand, to optimize memory usage drivers can limit the number of buffers +locked in advance and recycle the most recently used buffers first. Of +course, the pages of empty buffers in the incoming queue need not be +saved to disk. Output buffers must be saved on the incoming and +outgoing queue because an application may share them with other +processes. + + + Filled or displayed buffers are dequeued with the +&VIDIOC-DQBUF; ioctl. The driver can unlock the memory pages at any +time between the completion of the DMA and this ioctl. The memory is +also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or +when the device is closed. Applications must take care not to free +buffers without dequeuing. For once, the buffers remain locked until +further, wasting physical memory. Second the driver will not be +notified when the memory is returned to the application's free list +and subsequently reused for other purposes, possibly completing the +requested DMA and overwriting valuable data. + + For capturing applications it is customary to enqueue a +number of empty buffers, 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 output is started. In the write loop, when the application +runs out of free buffers it must wait until an empty buffer can be +dequeued and reused. 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 &func-open; function, VIDIOC_DQBUF +returns immediately with an &EAGAIN; when no buffer is available. The +&func-select; or &func-poll; function are always available. + + To start and stop capturing or output applications call the +&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note +VIDIOC_STREAMOFF removes all buffers from both +queues and unlocks all buffers 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 &v4l2-buffer; timestamp of captured +buffers, or set the field before enqueuing buffers for output. + + Drivers implementing user pointer I/O must +support the VIDIOC_REQBUFS, +VIDIOC_QBUF, VIDIOC_DQBUF, +VIDIOC_STREAMON and +VIDIOC_STREAMOFF ioctl, the +select() and poll() function. + At the driver level select() and +poll() are the same, and +select() is too important to be optional. The +rest should be evident. + +
+ +
+ Asynchronous I/O + + This method is not defined yet. +
+ +
+ Buffers + + A buffer contains data exchanged by application and +driver using one of the Streaming I/O methods. In the multi-planar API, the +data is held in planes, while the buffer structure acts as a container +for the planes. Only pointers to buffers (planes) are exchanged, the data +itself is not copied. These pointers, together with meta-information like +timestamps or field parity, are stored in a struct +v4l2_buffer, argument to +the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. +In the multi-planar API, some plane-specific members of struct +v4l2_buffer, such as pointers and sizes for each +plane, are stored in struct v4l2_plane instead. +In that case, struct v4l2_buffer contains an array of +plane structures. + + Nominally timestamps refer to the first data byte transmitted. +In practice however the wide range of hardware covered by the V4L2 API +limits timestamp accuracy. Often an interrupt routine will +sample the system clock shortly after the field or frame was stored +completely in memory. So applications must expect a constant +difference up to one field or frame period plus a small (few scan +lines) random error. The delay and error can be much +larger due to compression or transmission over an external bus when +the frames are not properly stamped by the sender. This is frequently +the case with USB cameras. Here timestamps refer to the instant the +field or frame was received by the driver, not the capture time. These +devices identify by not enumerating any video standards, see . + + Similar limitations apply to output timestamps. Typically +the video hardware locks to a clock controlling the video timing, the +horizontal and vertical synchronization pulses. At some point in the +line sequence, possibly the vertical blanking, an interrupt routine +samples the system clock, compares against the timestamp and programs +the hardware to repeat the previous field or frame, or to display the +buffer contents. + + Apart of limitations of the video device and natural +inaccuracies of all clocks, it should be noted system time itself is +not perfectly stable. It can be affected by power saving cycles, +warped to insert leap seconds, or even turned back or forth by the +system administrator affecting long term measurements. + Since no other Linux multimedia +API supports unadjusted time it would be foolish to introduce here. We +must use a universally supported clock to synchronize different media, +hence time of day. + + + + struct <structname>v4l2_buffer</structname> + + &cs-ustr; + + + __u32 + index + + Number of the buffer, set by the application. This +field is only used for memory mapping I/O +and can range from zero to the number of buffers allocated +with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; count) minus one. + + + &v4l2-buf-type; + type + + Type of the buffer, same as &v4l2-format; +type or &v4l2-requestbuffers; +type, set by the application. + + + __u32 + bytesused + + The number of bytes occupied by the data in the +buffer. It depends on the negotiated data format and may change with +each buffer for compressed variable size data like JPEG images. +Drivers must set this field when type +refers to an input stream, applications when an output stream. + + + __u32 + flags + + Flags set by the application or driver, see . + + + &v4l2-field; + field + + Indicates the field order of the image in the +buffer, see . This field is not used when +the buffer contains VBI data. Drivers must set it when +type refers to an input stream, +applications when an output stream. + + + struct timeval + timestamp + + For input streams this is the +system time (as returned by the gettimeofday() +function) when the first data byte was captured. For output streams +the data will not be displayed before this time, secondary to the +nominal frame rate determined by the current video standard in +enqueued order. Applications can for example zero this field to +display frames as soon as possible. The driver stores the time at +which the first data byte was actually sent out in the +timestamp field. This permits +applications to monitor the drift between the video and system +clock. + + + &v4l2-timecode; + timecode + + When type is +V4L2_BUF_TYPE_VIDEO_CAPTURE and the +V4L2_BUF_FLAG_TIMECODE flag is set in +flags, this structure contains a frame +timecode. In V4L2_FIELD_ALTERNATE +mode the top and bottom field contain the same timecode. +Timecodes are intended to help video editing and are typically recorded on +video tapes, but also embedded in compressed formats like MPEG. This +field is independent of the timestamp and +sequence fields. + + + __u32 + sequence + + Set by the driver, counting the frames in the +sequence. + + + In V4L2_FIELD_ALTERNATE mode the top and +bottom field have the same sequence number. The count starts at zero +and includes dropped or repeated frames. A dropped frame was received +by an input device but could not be stored due to lack of free buffer +space. A repeated frame was displayed again by an output device +because the application did not pass new data in +time.Note this may count the frames received +e.g. over USB, without taking into account the frames dropped by the +remote hardware due to limited compression throughput or bus +bandwidth. These devices identify by not enumerating any video +standards, see . + + + &v4l2-memory; + memory + + This field must be set by applications and/or drivers +in accordance with the selected I/O method. + + + union + m + + + + __u32 + offset + For the single-planar API and when +memory is V4L2_MEMORY_MMAP this +is the offset of the buffer from the start of the device memory. The value is +returned by the driver and apart of serving as parameter to the &func-mmap; +function not useful for applications. See for details + + + + + unsigned long + userptr + For the single-planar API and when +memory is V4L2_MEMORY_USERPTR +this is a pointer to the buffer (casted to unsigned long type) in virtual +memory, set by the application. See for details. + + + + + struct v4l2_plane + *planes + When using the multi-planar API, contains a userspace pointer + to an array of &v4l2-plane;. The size of the array should be put + in the length field of this + v4l2_buffer structure. + + + __u32 + length + + Size of the buffer (not the payload) in bytes for the + single-planar API. For the multi-planar API should contain the + number of elements in the planes array. + + + + __u32 + input + + Some video capture drivers support rapid and +synchronous video input changes, a function useful for example in +video surveillance applications. For this purpose applications set the +V4L2_BUF_FLAG_INPUT flag, and this field to the +number of a video input as in &v4l2-input; field +index. + + + __u32 + reserved + + A place holder for future extensions and custom +(driver defined) buffer types +V4L2_BUF_TYPE_PRIVATE and higher. Applications +should set this to 0. + + + +
+ + + struct <structname>v4l2_plane</structname> + + &cs-ustr; + + + __u32 + bytesused + + The number of bytes occupied by data in the plane + (its payload). + + + __u32 + length + + Size in bytes of the plane (not its payload). + + + union + m + + + + + + __u32 + mem_offset + When the memory type in the containing &v4l2-buffer; is + V4L2_MEMORY_MMAP, this is the value that + should be passed to &func-mmap;, similar to the + offset field in &v4l2-buffer;. + + + + __unsigned long + userptr + When the memory type in the containing &v4l2-buffer; is + V4L2_MEMORY_USERPTR, this is a userspace + pointer to the memory allocated for this plane by an application. + + + + __u32 + data_offset + + Offset in bytes to video data in the plane, if applicable. + + + + __u32 + reserved[11] + + Reserved for future use. Should be zeroed by an + application. + + + +
+ + + enum v4l2_buf_type + + &cs-def; + + + V4L2_BUF_TYPE_VIDEO_CAPTURE + 1 + Buffer of a single-planar video capture stream, see . + + + V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE + + 9 + Buffer of a multi-planar video capture stream, see . + + + V4L2_BUF_TYPE_VIDEO_OUTPUT + 2 + Buffer of a single-planar video output stream, see . + + + V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE + + 10 + Buffer of a multi-planar video output stream, see . + + + V4L2_BUF_TYPE_VIDEO_OVERLAY + 3 + Buffer for video overlay, see . + + + V4L2_BUF_TYPE_VBI_CAPTURE + 4 + Buffer of a raw VBI capture stream, see . + + + V4L2_BUF_TYPE_VBI_OUTPUT + 5 + Buffer of a raw VBI output stream, see . + + + V4L2_BUF_TYPE_SLICED_VBI_CAPTURE + 6 + Buffer of a sliced VBI capture stream, see . + + + V4L2_BUF_TYPE_SLICED_VBI_OUTPUT + 7 + Buffer of a sliced VBI output stream, see . + + + V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY + 8 + Buffer for video output overlay (OSD), see . Status: Experimental. + + + V4L2_BUF_TYPE_PRIVATE + 0x80 + This and higher values are reserved for custom +(driver defined) buffer types. + + + +
+ + + Buffer Flags + + &cs-def; + + + V4L2_BUF_FLAG_MAPPED + 0x0001 + The buffer resides in device memory and has been mapped +into the application's address space, see for details. +Drivers set or clear this flag when the +VIDIOC_QUERYBUF, VIDIOC_QBUF or VIDIOC_DQBUF ioctl is called. Set by the driver. + + + V4L2_BUF_FLAG_QUEUED + 0x0002 + Internally drivers maintain two buffer queues, an +incoming and outgoing queue. When this flag is set, the buffer is +currently on the incoming queue. It automatically moves to the +outgoing queue after the buffer has been filled (capture devices) or +displayed (output devices). Drivers set or clear this flag when the +VIDIOC_QUERYBUF ioctl is called. After +(successful) calling the VIDIOC_QBUF ioctl it is +always set and after VIDIOC_DQBUF always +cleared. + + + V4L2_BUF_FLAG_DONE + 0x0004 + When this flag is set, the buffer is currently on +the outgoing queue, ready to be dequeued from the driver. Drivers set +or clear this flag when the VIDIOC_QUERYBUF ioctl +is called. After calling the VIDIOC_QBUF or +VIDIOC_DQBUF it is always cleared. Of course a +buffer cannot be on both queues at the same time, the +V4L2_BUF_FLAG_QUEUED and +V4L2_BUF_FLAG_DONE flag are mutually exclusive. +They can be both cleared however, then the buffer is in "dequeued" +state, in the application domain to say so. + + + V4L2_BUF_FLAG_ERROR + 0x0040 + When this flag is set, the buffer has been dequeued + successfully, although the data might have been corrupted. + This is recoverable, streaming may continue as normal and + the buffer may be reused normally. + Drivers set this flag when the VIDIOC_DQBUF + ioctl is called. + + + V4L2_BUF_FLAG_KEYFRAME + 0x0008 + Drivers set or clear this flag when calling the +VIDIOC_DQBUF ioctl. It may be set by video +capture devices when the buffer contains a compressed image which is a +key frame (or field), &ie; can be decompressed on its own. + + + V4L2_BUF_FLAG_PFRAME + 0x0010 + Similar to V4L2_BUF_FLAG_KEYFRAME +this flags predicted frames or fields which contain only differences to a +previous key frame. + + + V4L2_BUF_FLAG_BFRAME + 0x0020 + Similar to V4L2_BUF_FLAG_PFRAME + this is a bidirectional predicted frame or field. [ooc tbd] + + + V4L2_BUF_FLAG_TIMECODE + 0x0100 + The timecode field is valid. +Drivers set or clear this flag when the VIDIOC_DQBUF +ioctl is called. + + + V4L2_BUF_FLAG_INPUT + 0x0200 + The input field is valid. +Applications set or clear this flag before calling the +VIDIOC_QBUF ioctl. + + + +
+ + + enum v4l2_memory + + &cs-def; + + + V4L2_MEMORY_MMAP + 1 + The buffer is used for memory +mapping I/O. + + + V4L2_MEMORY_USERPTR + 2 + The buffer is used for user +pointer I/O. + + + V4L2_MEMORY_OVERLAY + 3 + [to do] + + + +
+ +
+ Timecodes + + The v4l2_timecode structure is +designed to hold a or similar timecode. +(struct timeval timestamps are stored in +&v4l2-buffer; field timestamp.) + + + struct <structname>v4l2_timecode</structname> + + &cs-str; + + + __u32 + type + Frame rate the timecodes are based on, see . + + + __u32 + flags + Timecode flags, see . + + + __u8 + frames + Frame count, 0 ... 23/24/29/49/59, depending on the + type of timecode. + + + __u8 + seconds + Seconds count, 0 ... 59. This is a binary, not BCD number. + + + __u8 + minutes + Minutes count, 0 ... 59. This is a binary, not BCD number. + + + __u8 + hours + Hours count, 0 ... 29. This is a binary, not BCD number. + + + __u8 + userbits[4] + The "user group" bits from the timecode. + + + +
+ + + Timecode Types + + &cs-def; + + + V4L2_TC_TYPE_24FPS + 1 + 24 frames per second, i. e. film. + + + V4L2_TC_TYPE_25FPS + 2 + 25 frames per second, &ie; PAL or SECAM video. + + + V4L2_TC_TYPE_30FPS + 3 + 30 frames per second, &ie; NTSC video. + + + V4L2_TC_TYPE_50FPS + 4 + + + + V4L2_TC_TYPE_60FPS + 5 + + + + +
+ + + Timecode Flags + + &cs-def; + + + V4L2_TC_FLAG_DROPFRAME + 0x0001 + Indicates "drop frame" semantics for counting frames +in 29.97 fps material. When set, frame numbers 0 and 1 at the start of +each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the +count. + + + V4L2_TC_FLAG_COLORFRAME + 0x0002 + The "color frame" flag. + + + V4L2_TC_USERBITS_field + 0x000C + Field mask for the "binary group flags". + + + V4L2_TC_USERBITS_USERDEFINED + 0x0000 + Unspecified format. + + + V4L2_TC_USERBITS_8BITCHARS + 0x0008 + 8-bit ISO characters. + + + +
+
+
+ +
+ Field Order + + We have to distinguish between progressive and interlaced +video. Progressive video transmits all lines of a video image +sequentially. Interlaced video divides an image into two fields, +containing only the odd and even lines of the image, respectively. +Alternating the so called odd and even field are transmitted, and due +to a small delay between fields a cathode ray TV displays the lines +interleaved, yielding the original frame. This curious technique was +invented because at refresh rates similar to film the image would +fade out too quickly. Transmitting fields reduces the flicker without +the necessity of doubling the frame rate and with it the bandwidth +required for each channel. + + It is important to understand a video camera does not expose +one frame at a time, merely transmitting the frames separated into +fields. The fields are in fact captured at two different instances in +time. An object on screen may well move between one field and the +next. For applications analysing motion it is of paramount importance +to recognize which field of a frame is older, the temporal +order. + + When the driver provides or accepts images field by field +rather than interleaved, it is also important applications understand +how the fields combine to frames. We distinguish between top (aka odd) and +bottom (aka even) fields, the spatial order: The first line +of the top field is the first line of an interlaced frame, the first +line of the bottom field is the second line of that frame. + + However because fields were captured one after the other, +arguing whether a frame commences with the top or bottom field is +pointless. Any two successive top and bottom, or bottom and top fields +yield a valid frame. Only when the source was progressive to begin +with, ⪚ when transferring film to video, two fields may come from +the same frame, creating a natural order. + + Counter to intuition the top field is not necessarily the +older field. Whether the older field contains the top or bottom lines +is a convention determined by the video standard. Hence the +distinction between temporal and spatial order of fields. The diagrams +below should make this clearer. + + All video capture and output devices must report the current +field order. Some drivers may permit the selection of a different +order, to this end applications initialize the +field field of &v4l2-pix-format; before +calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should +have the value V4L2_FIELD_ANY (0). + + + enum v4l2_field + + &cs-def; + + + V4L2_FIELD_ANY + 0 + Applications request this field order when any +one of the V4L2_FIELD_NONE, +V4L2_FIELD_TOP, +V4L2_FIELD_BOTTOM, or +V4L2_FIELD_INTERLACED formats is acceptable. +Drivers choose depending on hardware capabilities or e. g. the +requested image size, and return the actual field order. &v4l2-buffer; +field can never be +V4L2_FIELD_ANY. + + + V4L2_FIELD_NONE + 1 + Images are in progressive format, not interlaced. +The driver may also indicate this order when it cannot distinguish +between V4L2_FIELD_TOP and +V4L2_FIELD_BOTTOM. + + + V4L2_FIELD_TOP + 2 + Images consist of the top (aka odd) field only. + + + V4L2_FIELD_BOTTOM + 3 + Images consist of the bottom (aka even) field only. +Applications may wish to prevent a device from capturing interlaced +images because they will have "comb" or "feathering" artefacts around +moving objects. + + + V4L2_FIELD_INTERLACED + 4 + Images contain both fields, interleaved line by +line. The temporal order of the fields (whether the top or bottom +field is first transmitted) depends on the current video standard. +M/NTSC transmits the bottom field first, all other standards the top +field first. + + + V4L2_FIELD_SEQ_TB + 5 + Images contain both fields, the top field lines +are stored first in memory, immediately followed by the bottom field +lines. Fields are always stored in temporal order, the older one first +in memory. Image sizes refer to the frame, not fields. + + + V4L2_FIELD_SEQ_BT + 6 + Images contain both fields, the bottom field +lines are stored first in memory, immediately followed by the top +field lines. Fields are always stored in temporal order, the older one +first in memory. Image sizes refer to the frame, not fields. + + + V4L2_FIELD_ALTERNATE + 7 + The two fields of a frame are passed in separate +buffers, in temporal order, &ie; the older one first. To indicate the field +parity (whether the current field is a top or bottom field) the driver +or application, depending on data direction, must set &v4l2-buffer; +field to +V4L2_FIELD_TOP or +V4L2_FIELD_BOTTOM. Any two successive fields pair +to build a frame. If fields are successive, without any dropped fields +between them (fields can drop individually), can be determined from +the &v4l2-buffer; sequence field. Image +sizes refer to the frame, not fields. This format cannot be selected +when using the read/write I/O method. + + + V4L2_FIELD_INTERLACED_TB + 8 + Images contain both fields, interleaved line by +line, top field first. The top field is transmitted first. + + + V4L2_FIELD_INTERLACED_BT + 9 + Images contain both fields, interleaved line by +line, top field first. The bottom field is transmitted first. + + + +
+ +
+ Field Order, Top Field First Transmitted + + + + + + + + +
+ +
+ Field Order, Bottom Field First Transmitted + + + + + + + + +
+
+ + -- cgit v1.1 From 55093284fb6f9009a339e522773417bdd54ec144 Mon Sep 17 00:00:00 2001 From: Guennadi Liakhovetski Date: Wed, 28 Sep 2011 08:10:58 -0300 Subject: [media] V4L: document the new VIDIOC_CREATE_BUFS and VIDIOC_PREPARE_BUF ioctl()s [mchehab@redhat.com: remove emacs format crap at the end of the new files] Signed-off-by: Guennadi Liakhovetski Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/io.xml | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'Documentation/DocBook/media/v4l/io.xml') diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index c57d1ec..3f47df1 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -927,6 +927,33 @@ ioctl is called. Applications set or clear this flag before calling the VIDIOC_QBUF ioctl. + + V4L2_BUF_FLAG_PREPARED + 0x0400 + The buffer has been prepared for I/O and can be queued by the +application. Drivers set or clear this flag when the +VIDIOC_QUERYBUF, VIDIOC_PREPARE_BUF, VIDIOC_QBUF or VIDIOC_DQBUF ioctl is called. + + + V4L2_BUF_FLAG_NO_CACHE_INVALIDATE + 0x0400 + Caches do not have to be invalidated for this buffer. +Typically applications shall use this flag if the data captured in the buffer +is not going to be touched by the CPU, instead the buffer will, probably, be +passed on to a DMA-capable hardware unit for further processing or output. + + + + V4L2_BUF_FLAG_NO_CACHE_CLEAN + 0x0800 + Caches do not have to be cleaned for this buffer. +Typically applications shall use this flag for output buffers if the data +in this buffer has not been created by the CPU but by some DMA-capable unit, +in which case caches have not been used. + -- cgit v1.1