^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) .. _vb_framework:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) Videobuf Framework
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) Author: Jonathan Corbet <corbet@lwn.net>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) Current as of 2.6.33
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) The videobuf framework was deprecated in favor of videobuf2. Shouldn't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) be used on new drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) The videobuf layer functions as a sort of glue layer between a V4L2 driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) and user space. It handles the allocation and management of buffers for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) the storage of video frames. There is a set of functions which can be used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) to implement many of the standard POSIX I/O system calls, including read(),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) poll(), and, happily, mmap(). Another set of functions can be used to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) implement the bulk of the V4L2 ioctl() calls related to streaming I/O,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) including buffer allocation, queueing and dequeueing, and streaming
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) control. Using videobuf imposes a few design decisions on the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) author, but the payback comes in the form of reduced code in the driver and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) a consistent implementation of the V4L2 user-space API.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) Buffer types
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) Not all video devices use the same kind of buffers. In fact, there are (at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) least) three common variations:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) - Buffers which are scattered in both the physical and (kernel) virtual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) address spaces. (Almost) all user-space buffers are like this, but it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) makes great sense to allocate kernel-space buffers this way as well when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) it is possible. Unfortunately, it is not always possible; working with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) this kind of buffer normally requires hardware which can do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) scatter/gather DMA operations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) - Buffers which are physically scattered, but which are virtually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) contiguous; buffers allocated with vmalloc(), in other words. These
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) buffers are just as hard to use for DMA operations, but they can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) useful in situations where DMA is not available but virtually-contiguous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) buffers are convenient.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) - Buffers which are physically contiguous. Allocation of this kind of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) buffer can be unreliable on fragmented systems, but simpler DMA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) controllers cannot deal with anything else.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) Videobuf can work with all three types of buffers, but the driver author
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) must pick one at the outset and design the driver around that decision.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) [It's worth noting that there's a fourth kind of buffer: "overlay" buffers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) which are located within the system's video memory. The overlay
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) functionality is considered to be deprecated for most use, but it still
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) shows up occasionally in system-on-chip drivers where the performance
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) benefits merit the use of this technique. Overlay buffers can be handled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) as a form of scattered buffer, but there are very few implementations in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) the kernel and a description of this technique is currently beyond the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) scope of this document.]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) Data structures, callbacks, and initialization
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) ----------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) Depending on which type of buffers are being used, the driver should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) include one of the following files:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) <media/videobuf-dma-sg.h> /* Physically scattered */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) <media/videobuf-vmalloc.h> /* vmalloc() buffers */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) <media/videobuf-dma-contig.h> /* Physically contiguous */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) The driver's data structure describing a V4L2 device should include a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) struct videobuf_queue instance for the management of the buffer queue,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) along with a list_head for the queue of available buffers. There will also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) need to be an interrupt-safe spinlock which is used to protect (at least)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) the queue.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) The next step is to write four simple callbacks to help videobuf deal with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) the management of buffers:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) struct videobuf_queue_ops {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) int (*buf_setup)(struct videobuf_queue *q,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) unsigned int *count, unsigned int *size);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) int (*buf_prepare)(struct videobuf_queue *q,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) struct videobuf_buffer *vb,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) enum v4l2_field field);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) void (*buf_queue)(struct videobuf_queue *q,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) struct videobuf_buffer *vb);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) void (*buf_release)(struct videobuf_queue *q,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) struct videobuf_buffer *vb);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) buf_setup() is called early in the I/O process, when streaming is being
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) initiated; its purpose is to tell videobuf about the I/O stream. The count
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) parameter will be a suggested number of buffers to use; the driver should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) check it for rationality and adjust it if need be. As a practical rule, a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) minimum of two buffers are needed for proper streaming, and there is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) usually a maximum (which cannot exceed 32) which makes sense for each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) device. The size parameter should be set to the expected (maximum) size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) for each frame of data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) Each buffer (in the form of a struct videobuf_buffer pointer) will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) passed to buf_prepare(), which should set the buffer's size, width, height,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) and field fields properly. If the buffer's state field is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) VIDEOBUF_NEEDS_INIT, the driver should pass it to:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) int videobuf_iolock(struct videobuf_queue* q, struct videobuf_buffer *vb,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) struct v4l2_framebuffer *fbuf);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) Among other things, this call will usually allocate memory for the buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) Finally, the buf_prepare() function should set the buffer's state to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) VIDEOBUF_PREPARED.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) When a buffer is queued for I/O, it is passed to buf_queue(), which should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) put it onto the driver's list of available buffers and set its state to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) VIDEOBUF_QUEUED. Note that this function is called with the queue spinlock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) held; if it tries to acquire it as well things will come to a screeching
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) halt. Yes, this is the voice of experience. Note also that videobuf may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) wait on the first buffer in the queue; placing other buffers in front of it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) could again gum up the works. So use list_add_tail() to enqueue buffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) Finally, buf_release() is called when a buffer is no longer intended to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) used. The driver should ensure that there is no I/O active on the buffer,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) then pass it to the appropriate free routine(s):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) /* Scatter/gather drivers */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) int videobuf_dma_unmap(struct videobuf_queue *q,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) struct videobuf_dmabuf *dma);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) int videobuf_dma_free(struct videobuf_dmabuf *dma);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) /* vmalloc drivers */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) void videobuf_vmalloc_free (struct videobuf_buffer *buf);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) /* Contiguous drivers */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) void videobuf_dma_contig_free(struct videobuf_queue *q,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) struct videobuf_buffer *buf);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) One way to ensure that a buffer is no longer under I/O is to pass it to:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) int videobuf_waiton(struct videobuf_buffer *vb, int non_blocking, int intr);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) Here, vb is the buffer, non_blocking indicates whether non-blocking I/O
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) should be used (it should be zero in the buf_release() case), and intr
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) controls whether an interruptible wait is used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) File operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) At this point, much of the work is done; much of the rest is slipping
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) videobuf calls into the implementation of the other driver callbacks. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) first step is in the open() function, which must initialize the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) videobuf queue. The function to use depends on the type of buffer used:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) void videobuf_queue_sg_init(struct videobuf_queue *q,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) struct videobuf_queue_ops *ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) struct device *dev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) spinlock_t *irqlock,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) enum v4l2_buf_type type,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) enum v4l2_field field,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) unsigned int msize,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) void *priv);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) void videobuf_queue_vmalloc_init(struct videobuf_queue *q,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) struct videobuf_queue_ops *ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) struct device *dev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) spinlock_t *irqlock,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) enum v4l2_buf_type type,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) enum v4l2_field field,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) unsigned int msize,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) void *priv);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) void videobuf_queue_dma_contig_init(struct videobuf_queue *q,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) struct videobuf_queue_ops *ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) struct device *dev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) spinlock_t *irqlock,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) enum v4l2_buf_type type,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) enum v4l2_field field,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) unsigned int msize,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) void *priv);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) In each case, the parameters are the same: q is the queue structure for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) device, ops is the set of callbacks as described above, dev is the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) structure for this video device, irqlock is an interrupt-safe spinlock to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) protect access to the data structures, type is the buffer type used by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) device (cameras will use V4L2_BUF_TYPE_VIDEO_CAPTURE, for example), field
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) describes which field is being captured (often V4L2_FIELD_NONE for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) progressive devices), msize is the size of any containing structure used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) around struct videobuf_buffer, and priv is a private data pointer which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) shows up in the priv_data field of struct videobuf_queue. Note that these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) are void functions which, evidently, are immune to failure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) V4L2 capture drivers can be written to support either of two APIs: the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) read() system call and the rather more complicated streaming mechanism. As
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) a general rule, it is necessary to support both to ensure that all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) applications have a chance of working with the device. Videobuf makes it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) easy to do that with the same code. To implement read(), the driver need
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) only make a call to one of:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) ssize_t videobuf_read_one(struct videobuf_queue *q,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) char __user *data, size_t count,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) loff_t *ppos, int nonblocking);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) ssize_t videobuf_read_stream(struct videobuf_queue *q,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) char __user *data, size_t count,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) loff_t *ppos, int vbihack, int nonblocking);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) Either one of these functions will read frame data into data, returning the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) amount actually read; the difference is that videobuf_read_one() will only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) read a single frame, while videobuf_read_stream() will read multiple frames
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) if they are needed to satisfy the count requested by the application. A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) typical driver read() implementation will start the capture engine, call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) one of the above functions, then stop the engine before returning (though a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) smarter implementation might leave the engine running for a little while in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) anticipation of another read() call happening in the near future).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) The poll() function can usually be implemented with a direct call to:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) unsigned int videobuf_poll_stream(struct file *file,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) struct videobuf_queue *q,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) poll_table *wait);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) Note that the actual wait queue eventually used will be the one associated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) with the first available buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) When streaming I/O is done to kernel-space buffers, the driver must support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) the mmap() system call to enable user space to access the data. In many
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) V4L2 drivers, the often-complex mmap() implementation simplifies to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) single call to:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) int videobuf_mmap_mapper(struct videobuf_queue *q,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) struct vm_area_struct *vma);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) Everything else is handled by the videobuf code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) The release() function requires two separate videobuf calls:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) void videobuf_stop(struct videobuf_queue *q);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) int videobuf_mmap_free(struct videobuf_queue *q);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) The call to videobuf_stop() terminates any I/O in progress - though it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) still up to the driver to stop the capture engine. The call to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) videobuf_mmap_free() will ensure that all buffers have been unmapped; if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) so, they will all be passed to the buf_release() callback. If buffers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) remain mapped, videobuf_mmap_free() returns an error code instead. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) purpose is clearly to cause the closing of the file descriptor to fail if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) buffers are still mapped, but every driver in the 2.6.32 kernel cheerfully
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) ignores its return value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) ioctl() operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) The V4L2 API includes a very long list of driver callbacks to respond to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) the many ioctl() commands made available to user space. A number of these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) - those associated with streaming I/O - turn almost directly into videobuf
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) calls. The relevant helper functions are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) int videobuf_reqbufs(struct videobuf_queue *q,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) struct v4l2_requestbuffers *req);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) int videobuf_querybuf(struct videobuf_queue *q, struct v4l2_buffer *b);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) int videobuf_qbuf(struct videobuf_queue *q, struct v4l2_buffer *b);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) int videobuf_dqbuf(struct videobuf_queue *q, struct v4l2_buffer *b,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) int nonblocking);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) int videobuf_streamon(struct videobuf_queue *q);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) int videobuf_streamoff(struct videobuf_queue *q);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) So, for example, a VIDIOC_REQBUFS call turns into a call to the driver's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) vidioc_reqbufs() callback which, in turn, usually only needs to locate the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) proper struct videobuf_queue pointer and pass it to videobuf_reqbufs().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) These support functions can replace a great deal of buffer management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) boilerplate in a lot of V4L2 drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) The vidioc_streamon() and vidioc_streamoff() functions will be a bit more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) complex, of course, since they will also need to deal with starting and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) stopping the capture engine.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) Buffer allocation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) Thus far, we have talked about buffers, but have not looked at how they are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) allocated. The scatter/gather case is the most complex on this front. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) allocation, the driver can leave buffer allocation entirely up to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) videobuf layer; in this case, buffers will be allocated as anonymous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) user-space pages and will be very scattered indeed. If the application is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) using user-space buffers, no allocation is needed; the videobuf layer will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) take care of calling get_user_pages() and filling in the scatterlist array.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) If the driver needs to do its own memory allocation, it should be done in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) the vidioc_reqbufs() function, *after* calling videobuf_reqbufs(). The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) first step is a call to:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) struct videobuf_dmabuf *videobuf_to_dma(struct videobuf_buffer *buf);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) The returned videobuf_dmabuf structure (defined in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) <media/videobuf-dma-sg.h>) includes a couple of relevant fields:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) struct scatterlist *sglist;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) int sglen;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) The driver must allocate an appropriately-sized scatterlist array and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) populate it with pointers to the pieces of the allocated buffer; sglen
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) should be set to the length of the array.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) Drivers using the vmalloc() method need not (and cannot) concern themselves
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) with buffer allocation at all; videobuf will handle those details. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) same is normally true of contiguous-DMA drivers as well; videobuf will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) allocate the buffers (with dma_alloc_coherent()) when it sees fit. That
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) means that these drivers may be trying to do high-order allocations at any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) time, an operation which is not always guaranteed to work. Some drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) play tricks by allocating DMA space at system boot time; videobuf does not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) currently play well with those drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) As of 2.6.31, contiguous-DMA drivers can work with a user-supplied buffer,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) as long as that buffer is physically contiguous. Normal user-space
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) allocations will not meet that criterion, but buffers obtained from other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) kernel drivers, or those contained within huge pages, will work with these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) Filling the buffers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) The final part of a videobuf implementation has no direct callback - it's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) the portion of the code which actually puts frame data into the buffers,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) usually in response to interrupts from the device. For all types of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) drivers, this process works approximately as follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) - Obtain the next available buffer and make sure that somebody is actually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) waiting for it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) - Get a pointer to the memory and put video data there.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) - Mark the buffer as done and wake up the process waiting for it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) Step (1) above is done by looking at the driver-managed list_head structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) - the one which is filled in the buf_queue() callback. Because starting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) the engine and enqueueing buffers are done in separate steps, it's possible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) for the engine to be running without any buffers available - in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) vmalloc() case especially. So the driver should be prepared for the list
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) to be empty. It is equally possible that nobody is yet interested in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) buffer; the driver should not remove it from the list or fill it until a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) process is waiting on it. That test can be done by examining the buffer's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) done field (a wait_queue_head_t structure) with waitqueue_active().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) A buffer's state should be set to VIDEOBUF_ACTIVE before being mapped for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) DMA; that ensures that the videobuf layer will not try to do anything with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) it while the device is transferring data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) For scatter/gather drivers, the needed memory pointers will be found in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) scatterlist structure described above. Drivers using the vmalloc() method
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) can get a memory pointer with:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) void *videobuf_to_vmalloc(struct videobuf_buffer *buf);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) For contiguous DMA drivers, the function to use is:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) .. code-block:: none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) dma_addr_t videobuf_to_dma_contig(struct videobuf_buffer *buf);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) The contiguous DMA API goes out of its way to hide the kernel-space address
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) of the DMA buffer from drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) The final step is to set the size field of the relevant videobuf_buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) structure to the actual size of the captured image, set state to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) VIDEOBUF_DONE, then call wake_up() on the done queue. At this point, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) buffer is owned by the videobuf layer and the driver should not touch it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) again.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) Developers who are interested in more information can go into the relevant
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) header files; there are a few low-level functions declared there which have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) not been talked about here. Note also that all of these calls are exported
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) GPL-only, so they will not be available to non-GPL kernel modules.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags