Lines Matching refs:the
1 An introduction to the videobuf layer
6 and user space. It handles the allocation and management of buffers for
7 the storage of video frames. There is a set of functions which can be used
8 to implement many of the standard POSIX I/O system calls, including read(),
10 implement the bulk of the V4L2 ioctl() calls related to streaming I/O,
12 control. Using videobuf imposes a few design decisions on the driver
13 author, but the payback comes in the form of reduced code in the driver and
14 a consistent implementation of the V4L2 user-space API.
18 Not all video devices use the same kind of buffers. In fact, there are (at
21 - Buffers which are scattered in both the physical and (kernel) virtual
38 Videobuf can work with all three types of buffers, but the driver author
39 must pick one at the outset and design the driver around that decision.
42 which are located within the system's video memory. The overlay
44 shows up occasionally in system-on-chip drivers where the performance
45 benefits merit the use of this technique. Overlay buffers can be handled
47 the kernel and a description of this technique is currently beyond the
52 Depending on which type of buffers are being used, the driver should
53 include one of the following files:
60 struct videobuf_queue instance for the management of the buffer queue,
61 along with a list_head for the queue of available buffers. There will also
63 the queue.
66 the management of buffers:
80 buf_setup() is called early in the I/O process, when streaming is being
81 initiated; its purpose is to tell videobuf about the I/O stream. The count
82 parameter will be a suggested number of buffers to use; the driver should
86 device. The size parameter should be set to the expected (maximum) size
89 Each buffer (in the form of a struct videobuf_buffer pointer) will be
90 passed to buf_prepare(), which should set the buffer's size, width, height,
91 and field fields properly. If the buffer's state field is
92 VIDEOBUF_NEEDS_INIT, the driver should pass it to:
97 Among other things, this call will usually allocate memory for the buffer.
98 Finally, the buf_prepare() function should set the buffer's state to
102 put it onto the driver's list of available buffers and set its state to
103 VIDEOBUF_QUEUED. Note that this function is called with the queue spinlock
105 halt. Yes, this is the voice of experience. Note also that videobuf may
106 wait on the first buffer in the queue; placing other buffers in front of it
107 could again gum up the works. So use list_add_tail() to enqueue buffers.
110 used. The driver should ensure that there is no I/O active on the buffer,
111 then pass it to the appropriate free routine(s):
129 Here, vb is the buffer, non_blocking indicates whether non-blocking I/O
130 should be used (it should be zero in the buf_release() case), and intr
135 At this point, much of the work is done; much of the rest is slipping
136 videobuf calls into the implementation of the other driver callbacks. The
137 first step is in the open() function, which must initialize the
138 videobuf queue. The function to use depends on the type of buffer used:
167 In each case, the parameters are the same: q is the queue structure for the
168 device, ops is the set of callbacks as described above, dev is the device
170 protect access to the data structures, type is the buffer type used by the
173 progressive devices), msize is the size of any containing structure used
175 shows up in the priv_data field of struct videobuf_queue. Note that these
178 V4L2 capture drivers can be written to support either of two APIs: the
179 read() system call and the rather more complicated streaming mechanism. As
181 applications have a chance of working with the device. Videobuf makes it
182 easy to do that with the same code. To implement read(), the driver need
193 Either one of these functions will read frame data into data, returning the
194 amount actually read; the difference is that videobuf_read_one() will only
196 if they are needed to satisfy the count requested by the application. A
197 typical driver read() implementation will start the capture engine, call
198 one of the above functions, then stop the engine before returning (though a
199 smarter implementation might leave the engine running for a little while in
200 anticipation of another read() call happening in the near future).
208 Note that the actual wait queue eventually used will be the one associated
209 with the first available buffer.
211 When streaming I/O is done to kernel-space buffers, the driver must support
212 the mmap() system call to enable user space to access the data. In many
213 V4L2 drivers, the often-complex mmap() implementation simplifies to a
219 Everything else is handled by the videobuf code.
227 still up to the driver to stop the capture engine. The call to
229 so, they will all be passed to the buf_release() callback. If buffers
231 purpose is clearly to cause the closing of the file descriptor to fail if
232 buffers are still mapped, but every driver in the 2.6.32 kernel cheerfully
238 the many ioctl() commands made available to user space. A number of these
251 So, for example, a VIDIOC_REQBUFS call turns into a call to the driver's
252 vidioc_reqbufs() callback which, in turn, usually only needs to locate the
259 stopping the capture engine.
264 allocated. The scatter/gather case is the most complex on this front. For
265 allocation, the driver can leave buffer allocation entirely up to the
267 user-space pages and will be very scattered indeed. If the application is
268 using user-space buffers, no allocation is needed; the videobuf layer will
269 take care of calling get_user_pages() and filling in the scatterlist array.
271 If the driver needs to do its own memory allocation, it should be done in
272 the vidioc_reqbufs() function, *after* calling videobuf_reqbufs(). The
284 populate it with pointers to the pieces of the allocated buffer; sglen
285 should be set to the length of the array.
287 Drivers using the vmalloc() method need not (and cannot) concern themselves
290 allocate the buffers (with dma_alloc_coherent()) when it sees fit. That
302 Filling the buffers
305 the portion of the code which actually puts frame data into the buffers,
306 usually in response to interrupts from the device. For all types of
309 - Obtain the next available buffer and make sure that somebody is actually
312 - Get a pointer to the memory and put video data there.
314 - Mark the buffer as done and wake up the process waiting for it.
316 Step (1) above is done by looking at the driver-managed list_head structure
317 - the one which is filled in the buf_queue() callback. Because starting
318 the engine and enqueueing buffers are done in separate steps, it's possible
319 for the engine to be running without any buffers available - in the
320 vmalloc() case especially. So the driver should be prepared for the list
321 to be empty. It is equally possible that nobody is yet interested in the
322 buffer; the driver should not remove it from the list or fill it until a
323 process is waiting on it. That test can be done by examining the buffer's
327 DMA; that ensures that the videobuf layer will not try to do anything with
328 it while the device is transferring data.
330 For scatter/gather drivers, the needed memory pointers will be found in the
331 scatterlist structure described above. Drivers using the vmalloc() method
336 For contiguous DMA drivers, the function to use is:
340 The contiguous DMA API goes out of its way to hide the kernel-space address
341 of the DMA buffer from drivers.
343 The final step is to set the size field of the relevant videobuf_buffer
344 structure to the actual size of the captured image, set state to
345 VIDEOBUF_DONE, then call wake_up() on the done queue. At this point, the
346 buffer is owned by the videobuf layer and the driver should not touch it
349 Developers who are interested in more information can go into the relevant
351 not been talked about here. Also worthwhile is the vivi driver
353 drivers should be written. Vivi only uses the vmalloc() API, but it's good