Constants

VB2_MEMORY_UNKNOWN

Buffer status is unknown or it is not used yet onuserspace.

VB2_MEMORY_MMAP

The buffers are allocated by the Kernel and it ismemory mapped via mmap() ioctl. This model isalso used when the user is using the buffers viaread() or write() system calls.

VB2_MEMORY_USERPTR

The buffers was allocated in userspace and it ismemory mapped via mmap() ioctl.

VB2_MEMORY_DMABUF

The buffers are passed to userspace via DMA buffer.

Definition:

struct vb2_mem_ops {    void *(*alloc)(struct vb2_buffer *vb, struct device *dev, unsigned long size);    void (*put)(void *buf_priv);    struct dma_buf *(*get_dmabuf)(struct vb2_buffer *vb, void *buf_priv, unsigned long flags);    void *(*get_userptr)(struct vb2_buffer *vb, struct device *dev, unsigned long vaddr, unsigned long size);    void (*put_userptr)(void *buf_priv);    void (*prepare)(void *buf_priv);    void (*finish)(void *buf_priv);    void *(*attach_dmabuf)(struct vb2_buffer *vb, struct device *dev, struct dma_buf *dbuf, unsigned long size);    void (*detach_dmabuf)(void *buf_priv);    int (*map_dmabuf)(void *buf_priv);    void (*unmap_dmabuf)(void *buf_priv);    void *(*vaddr)(struct vb2_buffer *vb, void *buf_priv);    void *(*cookie)(struct vb2_buffer *vb, void *buf_priv);    unsigned int    (*num_users)(void *buf_priv);    int (*mmap)(void *buf_priv, struct vm_area_struct *vma);};

Members

alloc

allocate video memory and, optionally, allocator private data,returnERR_PTR() on failure or a pointer to allocator private,per-buffer data on success; the returned private structurewill then be passed asbuf_priv argument to other ops in thisstructure. The size argument to this function shall bepage aligned.

put

inform the allocator that the buffer will no longer be used;usually will result in the allocator freeing the buffer (ifno other users of this buffer are present); thebuf_privargument is the allocator private per-buffer structurepreviously returned from the alloc callback.

get_dmabuf

acquire userspace memory for a hardware operation; used forDMABUF memory types.

get_userptr

acquire userspace memory for a hardware operation; used forUSERPTR memory types; vaddr is the address passed to thevideobuf2 layer when queuing a video buffer of USERPTR type;should return an allocator private per-buffer structureassociated with the buffer on success,ERR_PTR() on failure;the returned private structure will then be passed asbuf_privargument to other ops in this structure.

put_userptr

inform the allocator that a USERPTR buffer will no longerbe used.

prepare

called every time the buffer is passed from userspace to thedriver, useful for cache synchronisation, optional.

finish

called every time the buffer is passed back from the driverto the userspace, also optional.

attach_dmabuf

attach a sharedstructdma_buf for a hardware operation;used for DMABUF memory types; dev is the alloc devicedbuf is the shared dma_buf; returnsERR_PTR() on failure;allocator private per-buffer structure on success;this needs to be used for further accesses to the buffer.

detach_dmabuf

inform the exporter of the buffer that the current DMABUFbuffer is no longer used; thebuf_priv argument is theallocator private per-buffer structure previously returnedfrom the attach_dmabuf callback.

map_dmabuf

request for access to the dmabuf from allocator; the allocatorof dmabuf is informed that this driver is going to use thedmabuf.

unmap_dmabuf

releases access control to the dmabuf - allocator is notifiedthat this driver is done using the dmabuf for now.

vaddr

return a kernel virtual address to a given memory bufferassociated with the passed private structure or NULL if nosuch mapping exists.

cookie

return allocator specific cookie for a given memory bufferassociated with the passed private structure or NULL if notavailable.

num_users

return the current number of users of a memory buffer;return 1 if the videobuf2 layer (or actually the driver usingit) is the only user.

mmap

setup a userspace mapping for a given memory buffer underthe provided virtual memory region.

Note

1. Required ops for USERPTR types: get_userptr, put_userptr.

2. Required ops for MMAP types: alloc, put, num_users, mmap.

3. Required ops for read/write access types: alloc, put, num_users, vaddr.

4. Required ops for DMABUF types: attach_dmabuf, detach_dmabuf,map_dmabuf, unmap_dmabuf.

Definition:

struct vb2_plane {    void *mem_priv;    struct dma_buf          *dbuf;    unsigned int            dbuf_mapped;    bool dbuf_duplicated;    unsigned int            bytesused;    unsigned int            length;    unsigned int            min_length;    union {        unsigned int    offset;        unsigned long   userptr;        int fd;    } m;    unsigned int            data_offset;};

Members

mem_priv

private data with this plane.

dbuf

dma_buf - shared buffer object.

dbuf_mapped

flag to show whether dbuf is mapped or not

dbuf_duplicated

boolean to show whether dbuf is duplicated with aprevious plane of the buffer.

bytesused

number of bytes occupied by data in the plane (payload).

length

size of this plane (NOT the payload) in bytes. The maximumvalid size is MAX_UINT - PAGE_SIZE.

min_length

minimum required size of this plane (NOT the payload) in bytes.length is always greater or equal tomin_length, and likelength, it is limited to MAX_UINT - PAGE_SIZE.

m

Union with memtype-specific data.

m.offset

when memory in the associatedstructvb2_buffer isVB2_MEMORY_MMAP, equals the offset from the start ofthe device memory for this plane (or is a “cookie” thatshould be passed to mmap() called on the video node).

m.userptr

when memory isVB2_MEMORY_USERPTR, a userspace pointerpointing to this plane.

m.fd

when memory isVB2_MEMORY_DMABUF, a userspace filedescriptor associated with this plane.

data_offset

offset in the plane to the start of data; usually 0,unless there is a header in front of the data.

Constants

VB2_MMAP

driver supports MMAP with streaming API.

VB2_USERPTR

driver supports USERPTR with streaming API.

VB2_READ

driver supports read() style access.

VB2_WRITE

driver supports write() style access.

VB2_DMABUF

driver supports DMABUF with streaming API.

Constants

VB2_BUF_STATE_DEQUEUED

buffer under userspace control.

VB2_BUF_STATE_IN_REQUEST

buffer is queued in media request.

VB2_BUF_STATE_PREPARING

buffer is being prepared in videobuf2.

VB2_BUF_STATE_QUEUED

buffer queued in videobuf2, but not in driver.

VB2_BUF_STATE_ACTIVE

buffer queued in driver and possibly usedin a hardware operation.

VB2_BUF_STATE_DONE

buffer returned from driver to videobuf2, butnot yet dequeued to userspace.

VB2_BUF_STATE_ERROR

same as above, but the operation on the bufferhas ended with an error, which will be reportedto the userspace when it is dequeued.

Definition:

struct vb2_buffer {    struct vb2_queue        *vb2_queue;    unsigned int            index;    unsigned int            type;    unsigned int            memory;    unsigned int            num_planes;    u64 timestamp;    struct media_request    *request;    struct media_request_object     req_obj;};

Members

vb2_queue

pointer tostructvb2_queue with the queue towhich this driver belongs.

index

id number of the buffer.

type

buffer type.

memory

the method, in which the actual data is passed.

num_planes

number of planes in the bufferon an internal driver queue.

timestamp

frame timestamp in ns.

request

the request this buffer is associated with.

req_obj

used to bind this buffer to a request. Thisrequest object has a refcount.

Definition:

struct vb2_ops {    int (*queue_setup)(struct vb2_queue *q, unsigned int *num_buffers, unsigned int *num_planes, unsigned int sizes[], struct device *alloc_devs[]);    void (*wait_prepare)(struct vb2_queue *q);    void (*wait_finish)(struct vb2_queue *q);    int (*buf_out_validate)(struct vb2_buffer *vb);    int (*buf_init)(struct vb2_buffer *vb);    int (*buf_prepare)(struct vb2_buffer *vb);    void (*buf_finish)(struct vb2_buffer *vb);    void (*buf_cleanup)(struct vb2_buffer *vb);    int (*prepare_streaming)(struct vb2_queue *q);    int (*start_streaming)(struct vb2_queue *q, unsigned int count);    void (*stop_streaming)(struct vb2_queue *q);    void (*unprepare_streaming)(struct vb2_queue *q);    void (*buf_queue)(struct vb2_buffer *vb);    void (*buf_request_complete)(struct vb2_buffer *vb);};

Members

queue_setup

called fromVIDIOC_REQBUFS() andVIDIOC_CREATE_BUFS()handlers before memory allocation. It can be calledtwice: if the original number of requested bufferscould not be allocated, then it will be called asecond time with the actually allocated number ofbuffers to verify if that is OK.The driver should return the required number of buffersin *num_buffers, the required number of planes perbuffer in *num_planes, the size of each plane should beset in the sizes[] array and optional per-planeallocator specific device in the alloc_devs[] array.When called fromVIDIOC_REQBUFS(), *num_planes == 0,the driver has to use the currently configured format todetermine the plane sizes and *num_buffers is the totalnumber of buffers that are being allocated. When calledfromVIDIOC_CREATE_BUFS(), *num_planes != 0 and itdescribes the requested number of planes and sizes[]contains the requested plane sizes. In this case*num_buffers are being allocated additionally tothe buffers already allocated. If either *num_planesor the requested sizes are invalid callback must return-EINVAL.

wait_prepare

release any locks taken while calling vb2 functions;it is called before an ioctl needs to wait for a newbuffer to arrive; required to avoid a deadlock inblocking access type.

wait_finish

reacquire all locks released in the previous callback;required to continue operation after sleeping whilewaiting for a new buffer to arrive.

buf_out_validate

called when the output buffer is prepared or queuedto a request; drivers can use this to validateuserspace-provided information; this is required onlyfor OUTPUT queues.

buf_init

called once after allocating a buffer (in MMAP case)or after acquiring a new USERPTR buffer; drivers mayperform additional buffer-related initialization;initialization failure (return != 0) will preventqueue setup from completing successfully; optional.

buf_prepare

called every time the buffer is queued from userspaceand from theVIDIOC_PREPARE_BUF() ioctl; drivers mayperform any initialization required before eachhardware operation in this callback; drivers canaccess/modify the buffer here as it is still synced forthe CPU; drivers that supportVIDIOC_CREATE_BUFS() mustalso validate the buffer size; if an error is returned,the buffer will not be queued in driver; optional.

buf_finish

called before every dequeue of the buffer back touserspace; the buffer is synced for the CPU, so driverscan access/modify the buffer contents; drivers mayperform any operations required before userspaceaccesses the buffer; optional. The buffer state can beone of the following:DONE andERROR occur whilestreaming is in progress, and thePREPARED state occurswhen the queue has been canceled and all pendingbuffers are being returned to their defaultDEQUEUEDstate. Typically you only have to do something if thestate isVB2_BUF_STATE_DONE, since in all other casesthe buffer contents will be ignored anyway.

buf_cleanup

called once before the buffer is freed; drivers mayperform any additional cleanup; optional.

prepare_streaming

called once to prepare for ‘streaming’ state; this iswhere validation can be done to verify everything isokay and streaming resources can be claimed. It iscalled when the VIDIOC_STREAMON ioctl is called. Theactual streaming starts whenstart_streaming is called.Optional.

start_streaming

called once to enter ‘streaming’ state; the driver mayreceive buffers withbuf_queue callbackbeforestart_streaming is called; the driver gets thenumber of already queued buffers in count parameter;driver can return an error if hardware fails, in thatcase all buffers that have been already given bythebuf_queue callback are to be returned by the driverby callingvb2_buffer_done() withVB2_BUF_STATE_QUEUED.If you need a minimum number of buffers before you canstart streaming, then setvb2_queue->min_queued_buffers. If that is non-zerothenstart_streaming won’t be called until at leastthat many buffers have been queued up by userspace.

stop_streaming

called when ‘streaming’ state must be disabled; drivershould stop any DMA transactions or wait until theyfinish and give back all buffers it got frombuf_queuecallback by callingvb2_buffer_done() with eitherVB2_BUF_STATE_DONE orVB2_BUF_STATE_ERROR; may usevb2_wait_for_all_buffers() function

unprepare_streaming

called as counterpart toprepare_streaming; any claimedstreaming resources can be released here. It iscalled when the VIDIOC_STREAMOFF ioctls is called orwhen the streaming filehandle is closed. Optional.

buf_queue

passes buffer vb to the driver; driver may starthardware operation on this buffer; driver should givethe buffer back by callingvb2_buffer_done() function;it is always called after callingVIDIOC_STREAMON()ioctl; might be called beforestart_streaming callbackif user pre-queued buffers before callingVIDIOC_STREAMON().

buf_request_complete

a buffer that was never queued to the driver but isassociated with a queued request was canceled.The driver will have to mark associated objects in therequest as completed; required if requests aresupported.

Definition:

struct vb2_buf_ops {    int (*verify_planes_array)(struct vb2_buffer *vb, const void *pb);    void (*init_buffer)(struct vb2_buffer *vb);    void (*fill_user_buffer)(struct vb2_buffer *vb, void *pb);    int (*fill_vb2_buffer)(struct vb2_buffer *vb, struct vb2_plane *planes);    void (*copy_timestamp)(struct vb2_buffer *vb, const void *pb);};

Members

verify_planes_array

Verify that a given user space structure containsenough planes for the buffer. This is calledfor each dequeued buffer.

init_buffer

given avb2_buffer initialize the extra data afterstructvb2_buffer.For V4L2 this is astructvb2_v4l2_buffer.

fill_user_buffer

given avb2_buffer fill in the userspace structure.For V4L2 this is astructv4l2_buffer.

fill_vb2_buffer

given a userspace structure, fill in thevb2_buffer.If the userspace structure is invalid, then this opwill return an error.

copy_timestamp

copy the timestamp from a userspace structure tothestructvb2_buffer.

Definition:

struct vb2_queue {    unsigned int                    type;    unsigned int                    io_modes;    struct device                   *dev;    unsigned long                   dma_attrs;    unsigned int                    bidirectional:1;    unsigned int                    fileio_read_once:1;    unsigned int                    fileio_write_immediately:1;    unsigned int                    allow_zero_bytesused:1;    unsigned int               quirk_poll_must_check_waiting_for_buffers:1;    unsigned int                    supports_requests:1;    unsigned int                    requires_requests:1;    unsigned int                    uses_qbuf:1;    unsigned int                    uses_requests:1;    unsigned int                    allow_cache_hints:1;    unsigned int                    non_coherent_mem:1;    struct mutex                    *lock;    void *owner;    const struct vb2_ops            *ops;    const struct vb2_mem_ops        *mem_ops;    const struct vb2_buf_ops        *buf_ops;    void *drv_priv;    u32 subsystem_flags;    unsigned int                    buf_struct_size;    u32 timestamp_flags;    gfp_t gfp_flags;    u32 min_queued_buffers;    u32 min_reqbufs_allocation;    struct device                   *alloc_devs[VB2_MAX_PLANES];};

Members

type

private buffer type whose content is defined by the vb2-corecaller. For example, for V4L2, it should matchthe types defined onenumv4l2_buf_type.

io_modes

supported io methods (seeenumvb2_io_modes).

dev

device to use for the default allocation context if the driverdoesn’t fill in thealloc_devs array.

dma_attrs

DMA attributes to use for the DMA.

bidirectional

when this flag is set the DMA direction for the buffers ofthis queue will be overridden withDMA_BIDIRECTIONAL direction.This is useful in cases where the hardware (firmware) writes toa buffer which is mapped as read (DMA_TO_DEVICE), or reads frombuffer which is mapped for write (DMA_FROM_DEVICE) in orderto satisfy some internal hardware restrictions or adds a paddingneeded by the processing algorithm. In case the DMA mapping isnot bidirectional but the hardware (firmware) trying to accessthe buffer (in the opposite direction) this could lead to anIOMMU protection faults.

fileio_read_once

report EOF after reading the first buffer

fileio_write_immediately

queue buffer after each write() call

allow_zero_bytesused

allow bytesused == 0 to be passed to the driver

quirk_poll_must_check_waiting_for_buffers

ReturnEPOLLERR at poll when QBUFhas not been called. This is a vb1 idiom that has been adoptedalso by vb2.

supports_requests

this queue supports the Request API.

requires_requests

this queue requires the Request API. If this is set to 1,then supports_requests must be set to 1 as well.

uses_qbuf

qbuf was used directly for this queue. Set to 1 the firsttime this is called. Set to 0 when the queue is canceled.If this is 1, then you cannot queue buffers from a request.

uses_requests

requests are used for this queue. Set to 1 the first timea request is queued. Set to 0 when the queue is canceled.If this is 1, then you cannot queue buffers directly.

allow_cache_hints

when set user-space can pass cache management hints inorder to skip cache flush/invalidation on ->prepare() or/and->finish().

non_coherent_mem

when set queue will attempt to allocate buffers usingnon-coherent memory.

lock

pointer to a mutex that protects thestructvb2_queue. Thedriver can set this to a mutex to let the v4l2 core serializethe queuing ioctls. If the driver wants to handle lockingitself, then this should be set to NULL. This lock is not usedby the videobuf2 core API.

owner

The filehandle that ‘owns’ the buffers, i.e. the filehandlethat called reqbufs, create_buffers or started fileio.This field is not used by the videobuf2 core API, but it allowsdrivers to easily associate an owner filehandle with the queue.

ops

driver-specific callbacks

mem_ops

memory allocator specific callbacks

buf_ops

callbacks to deliver buffer information.between user-space and kernel-space.

drv_priv

driver private data.

subsystem_flags

Flags specific to the subsystem (V4L2/DVB/etc.). Not usedby the vb2 core.

buf_struct_size

size of the driver-specific buffer structure;“0” indicates the driver doesn’t want to use a custom bufferstructure type. In that case a subsystem-specificstructwill be used (in the case of V4L2 that issizeof(structvb2_v4l2_buffer)). The first field of thedriver-specific buffer structure must be the subsystem-specificstruct (vb2_v4l2_buffer in the case of V4L2).

timestamp_flags

Timestamp flags;V4L2_BUF_FLAG_TIMESTAMP_* andV4L2_BUF_FLAG_TSTAMP_SRC_*

gfp_flags

additional gfp flags used when allocating the buffers.Typically this is 0, but it may be e.g.GFP_DMA or__GFP_DMA32to force the buffer allocation to a specific memory zone.

min_queued_buffers

the minimum number of queued buffers needed beforestart_streaming can be called. Used when a DMA enginecannot be started unless at least this number of buffershave been queued into the driver.VIDIOC_REQBUFS will ensure at leastmin_queued_buffers + 1buffers will be allocated. Note that VIDIOC_CREATE_BUFS will notmodify the requested buffer count.

min_reqbufs_allocation

the minimum number of buffers to be allocated whencalling VIDIOC_REQBUFS. Note that VIDIOC_CREATE_BUFS willnotmodify the requested buffer count and does not use this field.Drivers can set this if there has to be a certain number ofbuffers available for the hardware to work effectively.This allows calling VIDIOC_REQBUFS with a buffer count of 1 andit will be automatically adjusted to a workable buffer count.If set, thenmin_reqbufs_allocation must be larger thanmin_queued_buffers + 1.If this field is > 3, then it is highly recommended that thedriver implements the V4L2_CID_MIN_BUFFERS_FOR_CAPTURE/OUTPUTcontrol.

alloc_devs

structdevice memory type/allocator-specific per-plane device

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue

Parameters

structvb2_buffer*vb

pointer tostructvb2_buffer to which the plane inquestion belongs to.

unsignedintplane_no

plane number for which the address is to be returned.

Description

This function returns a kernel virtual address of a given plane ifsuch a mapping exist, NULL otherwise.

Parameters

structvb2_buffer*vb

pointer tostructvb2_buffer to which the plane inquestion belongs to.

unsignedintplane_no

plane number for which the cookie is to be returned.

Description

This function returns an allocator specific cookie for a given plane ifavailable, NULL otherwise. The allocator should provide some simple staticinline function, which would convert this cookie to the allocator specifictype that can be used directly by the driver to access the buffer. This canbe for example physical address, pointer to scatter list or IOMMU mapping.

Parameters

structvb2_buffer*vb

pointer tostructvb2_buffer to be used.

enumvb2_buffer_statestate

state of the buffer, as defined byenumvb2_buffer_state.EitherVB2_BUF_STATE_DONE if the operation finishedsuccessfully,VB2_BUF_STATE_ERROR if the operation finishedwith an error orVB2_BUF_STATE_QUEUED.

Description

This function should be called by the driver after a hardware operation ona buffer is finished and the buffer may be returned to userspace. The drivercannot use this buffer anymore until it is queued back to it by videobufby the means ofvb2_ops->buf_queue callback. Only buffers previously queuedto the driver byvb2_ops->buf_queue can be passed to this function.

While streaming a buffer can only be returned in state DONE or ERROR.Thevb2_ops->start_streaming op can also return them in case the DMA enginecannot be started for some reason. In that case the buffers should bereturned with state QUEUED to put them back into the queue.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

Description

This function is intended to be used with suspend/resume operations. Itdiscards all ‘done’ buffers as they would be too old to be requested afterresume.

Drivers must stop the hardware and synchronize with interrupt handlers and/ordelayed works before calling this function to make sure no buffer will betouched by the driver and/or hardware.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

Description

This function will wait until all buffers that have been given to the driverbyvb2_ops->buf_queue are given back to vb2 withvb2_buffer_done(). Itdoesn’t callvb2_ops->wait_prepare/vb2_ops->wait_finish pair.It is intended to be called with all locks taken, for example fromvb2_ops->stop_streaming callback.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

structvb2_buffer*vb

pointer to structvb2_buffer.

void*pb

bufferstructpassed from userspace.

Description

Videobuf2 core helper to implementVIDIOC_QUERYBUF() operation. It is calledinternally by VB2 by an API-specific handler, likevideobuf2-v4l2.h.

The passed buffer should have been verified.

This function fills the relevant information for the userspace.

Return

returns zero on success; an error code otherwise.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

enumvb2_memorymemory

memory type, as defined byenumvb2_memory.

unsignedintflags

auxiliary queue/buffer management flags. Currently, the onlyused flag isV4L2_MEMORY_FLAG_NON_COHERENT.

unsignedint*count

requested buffer count.

Description

Videobuf2 core helper to implementVIDIOC_REQBUF() operation. It is calledinternally by VB2 by an API-specific handler, likevideobuf2-v4l2.h.

This function:

1. verifies streaming parameters passed from the userspace;

2. sets up the queue;

3. negotiates number of buffers and planes per buffer with the driverto be used during streaming;

4. allocates internal buffer structures (structvb2_buffer), according tothe agreed parameters;

5. for MMAP memory type, allocates actual video memory, using thememory handling/allocation routines provided during queue initialization.

If req->count is 0, all the memory will be freed instead.

If the queue has been allocated previously by a previousvb2_core_reqbufs()call and the queue is not busy, memory will be reallocated.

Return

returns zero on success; an error code otherwise.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

enumvb2_memorymemory

memory type, as defined byenumvb2_memory.

unsignedintflags

auxiliary queue/buffer management flags.

unsignedint*count

requested buffer count.

unsignedintrequested_planes

number of planes requested.

constunsignedintrequested_sizes[]

array with the size of the planes.

unsignedint*first_index

index of the first created buffer, all allocated buffers haveindices in the range [first_index..first_index+count-1]

Description

Videobuf2 core helper to implementVIDIOC_CREATE_BUFS() operation. It iscalled internally by VB2 by an API-specific handler, likevideobuf2-v4l2.h.

This function:

1. verifies parameter sanity;

2. calls thevb2_ops->queue_setup queue operation;

3. performs any necessary memory allocations.

Return

returns zero on success; an error code otherwise.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

structvb2_buffer*vb

pointer to structvb2_buffer.

void*pb

buffer structure passed from userspace tov4l2_ioctl_ops->vidioc_prepare_buf handler in driver.

Description

Videobuf2 core helper to implementVIDIOC_PREPARE_BUF() operation. It iscalled internally by VB2 by an API-specific handler, likevideobuf2-v4l2.h.

The passed buffer should have been verified.

This function calls vb2_ops->buf_prepare callback in the driver(if provided), in which driver-specific buffer initialization canbe performed.

Return

returns zero on success; an error code otherwise.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

unsignedintstart

first index of the range of buffers to remove.

unsignedintcount

number of buffers to remove.

Return

returns zero on success; an error code otherwise.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

structvb2_buffer*vb

pointer to structvb2_buffer.

void*pb

buffer structure passed from userspace tov4l2_ioctl_ops->vidioc_qbuf handler in driver

structmedia_request*req

pointer tostructmedia_request, may be NULL.

Description

Videobuf2 core helper to implementVIDIOC_QBUF() operation. It is calledinternally by VB2 by an API-specific handler, likevideobuf2-v4l2.h.

This function:

1. Ifreq is non-NULL, then the buffer will be bound to thismedia request and it returns. The buffer will be prepared andqueued to the driver (i.e. the next two steps) when the requestitself is queued.

2. if necessary, callsvb2_ops->buf_prepare callback in the driver(if provided), in which driver-specific buffer initialization canbe performed;

3. if streaming is on, queues the buffer in driver by the means ofvb2_ops->buf_queue callback for processing.

Return

returns zero on success; an error code otherwise.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue

unsignedint*pindex

pointer to the buffer index. May be NULL

void*pb

buffer structure passed from userspace tov4l2_ioctl_ops->vidioc_dqbuf handler in driver.

boolnonblocking

if true, this call will not sleep waiting for a buffer if nobuffers ready for dequeuing are present. Normally the driverwould be passing (file->f_flags & O_NONBLOCK) here.

Description

Videobuf2 core helper to implementVIDIOC_DQBUF() operation. It is calledinternally by VB2 by an API-specific handler, likevideobuf2-v4l2.h.

This function:

1. calls buf_finish callback in the driver (if provided), in whichdriver can perform any additional operations that may be required beforereturning the buffer to userspace, such as cache sync,

2. the bufferstructmembers are filled with relevant information forthe userspace.

Return

returns zero on success; an error code otherwise.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue

unsignedinttype

type of the queue to be started.For V4L2, this is defined byenumv4l2_buf_type type.

Description

Videobuf2 core helper to implementVIDIOC_STREAMON() operation. It is calledinternally by VB2 by an API-specific handler, likevideobuf2-v4l2.h.

Return

returns zero on success; an error code otherwise.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue

unsignedinttype

type of the queue to be started.For V4L2, this is defined byenumv4l2_buf_type type.

Description

Videobuf2 core helper to implementVIDIOC_STREAMOFF() operation. It iscalled internally by VB2 by an API-specific handler, likevideobuf2-v4l2.h.

Return

returns zero on success; an error code otherwise.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

int*fd

pointer to the file descriptor associated with DMABUF(set by driver).

unsignedinttype

buffer type.

structvb2_buffer*vb

pointer to structvb2_buffer.

unsignedintplane

index of the plane to be exported, 0 for single plane queues

unsignedintflags

file flags for newly created file, as defined atinclude/uapi/asm-generic/fcntl.h.Currently, the only used flag isO_CLOEXEC.is supported, refer to manual of open syscall for more details.

Description

Videobuf2 core helper to implementVIDIOC_EXPBUF() operation. It is calledinternally by VB2 by an API-specific handler, likevideobuf2-v4l2.h.

Return

returns zero on success; an error code otherwise.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.This structure should be allocated in driver

Description

Thevb2_queue structure should be allocated by the driver. The driver isresponsible of clearing it’s content and setting initial values for somerequired entries before calling this function.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

Description

This function stops streaming and performs necessary clean ups, includingfreeing video buffer memory. The driver is responsible for freeingthestructvb2_queue itself.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

Description

Flag that a fatal unrecoverable error has occurred and wake up all processeswaiting on the queue. Polling will now setEPOLLERR and queuing and dequeuingbuffers will return-EIO.

The error flag will be cleared when canceling the queue, either fromvb2_streamoff() orvb2_queue_release(). Drivers should thus not call thisfunction before starting the stream, otherwise the error flag will remain setuntil the queue is released when closing the device node.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

structvm_area_struct*vma

pointer tostructvm_area_struct with the vma passedto the mmap file operation handler in the driver.

Description

Should be called from mmap file operation handler of a driver.This function maps one plane of one of the available video buffers touserspace. To map whole video memory allocated on reqbufs, this functionhas to be called once per each plane per each buffer previously allocated.

When the userspace application calls mmap, it passes to it an offset returnedto it earlier by the means ofv4l2_ioctl_ops->vidioc_querybuf handler.That offset acts as a “cookie”, which is then used to identify the planeto be mapped.

This function finds a plane with a matching offset and a mapping is performedby the means of a provided memory operation.

The return values from this function are intended to be directly returnedfrom the mmap handler in driver.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

unsignedlongaddr

memory address.

unsignedlonglen

buffer size.

unsignedlongpgoff

page offset.

unsignedlongflags

memory flags.

Description

This function is used in noMMU platforms to propose address mappingfor a given buffer. It’s intended to be used as a handler for thefile_operations->get_unmapped_area operation.

This is called by the mmap() syscall routines will call thisto get a proposed address for the mapping, when!CONFIG_MMU.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

structfile*file

structfile argument passed to the pollfile operation handler.

poll_table*wait

poll_table wait argument passed to the pollfile operation handler.

Description

This function implements poll file operation handler for a driver.For CAPTURE queues, if a buffer is ready to be dequeued, the userspace willbe informed that the file descriptor of a video device is available forreading.For OUTPUT queues, if a buffer is ready to be dequeued, the file descriptorwill be reported as available for writing.

The return values from this function are intended to be directly returnedfrom poll handler in driver.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

char__user*data

pointed to target userspace buffer

size_tcount

number of bytes to read

loff_t*ppos

file handle position tracking pointer

intnonblock

mode selector (1 means blocking calls, 0 means nonblocking)

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

constchar__user*data

pointed to target userspace buffer

size_tcount

number of bytes to write

loff_t*ppos

file handle position tracking pointer

intnonblock

mode selector (1 means blocking calls, 0 means nonblocking)

Parameters

structvb2_buffer*vb

pointer to structvb2_buffer.

void*priv

pointer to a private data.

Description

This is called whenever a buffer is dequeued in the thread.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

vb2_thread_fncfnc

vb2_thread_fnc callback function.

void*priv

priv pointer passed to the callback function.

constchar*thread_name

the name of the thread. This will be prefixed with “vb2-“.

Description

This starts a thread that will queue and dequeue until an error occursorvb2_thread_stop() is called.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

Description

This returns true if read() or write() is used to stream the dataas opposed to stream I/O. This is almost never an important distinction,except in rare cases. One such case is that using read() or write() tostream a format usingV4L2_FIELD_ALTERNATE is not allowed since thereis no way you can pass the field information of each buffer to/fromuserspace. A driver that supports this field format should check forthis in thevb2_ops->queue_setup op and reject it if this function returnstrue.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

Description

This function checks if queue has any buffers allocated.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

Parameters

structvb2_buffer*vb

pointer tostructvb2_buffer to which the plane inquestion belongs to.

unsignedintplane_no

plane number for which payload should be set.

unsignedlongsize

payload in bytes.

Parameters

structvb2_buffer*vb

pointer tostructvb2_buffer to which the plane inquestion belongs to.

unsignedintplane_no

plane number for which payload should be set.

Parameters

structvb2_buffer*vb

pointer tostructvb2_buffer to which the plane inquestion belongs to.

unsignedintplane_no

plane number for which size should be returned.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

unsignedintindex

buffer index

Description

This function obtains a buffer from a queue, by its index.Keep in mind that there is no refcounting involved in thisoperation, so the buffer lifetime should be taken intoconsideration.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

structvb2_buffer*vb

buffer for which plane size should be returned.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

enumvb2_memorymemory

memory model, as defined by enumvb2_memory.

unsignedinttype

private buffer type whose content is defined by the vb2-corecaller. For example, for V4L2, it should matchthe types defined on enumv4l2_buf_type.

Parameters

structmedia_request_object*obj

the request object.

Parameters

structmedia_request*req

the request.

Definition:

struct vb2_v4l2_buffer {    struct vb2_buffer       vb2_buf;    __u32 flags;    __u32 field;    struct v4l2_timecode    timecode;    __u32 sequence;    __s32 request_fd;    bool is_held;    struct vb2_plane        planes[VB2_MAX_PLANES];};

Members

vb2_buf

embedded structvb2_buffer.

flags

buffer informational flags.

field

field order of the image in the buffer, as defined byenumv4l2_field.

timecode

frame timecode.

sequence

sequence count of this frame.

request_fd

the request_fd associated with this buffer

is_held

if true, then this capture buffer was held

planes

plane information (userptr/fd, length, bytesused, data_offset).

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

u64timestamp

the timestamp to find.

Description

Returns the buffer with the giventimestamp, or NULL if not found.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

structv4l2_requestbuffers*req

structv4l2_requestbuffers passed from userspace tov4l2_ioctl_ops->vidioc_reqbufs handler in driver.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

structv4l2_create_buffers*create

creation parameters, passed from userspace tov4l2_ioctl_ops->vidioc_create_bufs handler in driver

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

structmedia_device*mdev

pointer tostructmedia_device, may be NULL.

structv4l2_buffer*b

buffer structure passed from userspace tov4l2_ioctl_ops->vidioc_prepare_buf handler in driver

Description

Should be called fromv4l2_ioctl_ops->vidioc_prepare_buf ioctl handlerof a driver.

This function:

1. verifies the passed buffer,

2. callsvb2_ops->buf_prepare callback in the driver (if provided),in which driver-specific buffer initialization can be performed.

3. ifb->request_fd is non-zero andmdev->ops->req_queue is set,then bind the prepared buffer to the request.

The return values from this function are intended to be directly returnedfromv4l2_ioctl_ops->vidioc_prepare_buf handler in driver.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

structmedia_device*mdev

pointer tostructmedia_device, may be NULL.

structv4l2_buffer*b

buffer structure passed from userspace tov4l2_ioctl_ops->vidioc_qbuf handler in driver

Description

Should be called fromv4l2_ioctl_ops->vidioc_qbuf handler of a driver.

This function:

1. verifies the passed buffer;

2. ifb->request_fd is non-zero andmdev->ops->req_queue is set,then bind the buffer to the request.

3. if necessary, callsvb2_ops->buf_prepare callback in the driver(if provided), in which driver-specific buffer initialization canbe performed;

4. if streaming is on, queues the buffer in driver by the means ofvb2_ops->buf_queue callback for processing.

The return values from this function are intended to be directly returnedfromv4l2_ioctl_ops->vidioc_qbuf handler in driver.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

structv4l2_exportbuffer*eb

export buffer structure passed from userspace tov4l2_ioctl_ops->vidioc_expbuf handler in driver

Description

The return values from this function are intended to be directly returnedfromv4l2_ioctl_ops->vidioc_expbuf handler in driver.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

structv4l2_buffer*b

buffer structure passed from userspace tov4l2_ioctl_ops->vidioc_dqbuf handler in driver

boolnonblocking

if true, this call will not sleep waiting for a buffer if nobuffers ready for dequeuing are present. Normally the driverwould be passing (file->f_flags &O_NONBLOCK) here

Description

Should be called fromv4l2_ioctl_ops->vidioc_dqbuf ioctl handlerof a driver.

This function:

1. verifies the passed buffer;

2. callsvb2_ops->buf_finish callback in the driver (if provided), in whichdriver can perform any additional operations that may be required beforereturning the buffer to userspace, such as cache sync;

3. the bufferstructmembers are filled with relevant information forthe userspace.

The return values from this function are intended to be directly returnedfromv4l2_ioctl_ops->vidioc_dqbuf handler in driver.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

enumv4l2_buf_typetype

type argument passed from userspace to vidioc_streamon handler,as defined byenumv4l2_buf_type.

Description

Should be called fromv4l2_ioctl_ops->vidioc_streamon handler of a driver.

This function:

1. verifies current state

2. passes any previously queued buffers to the driver and starts streaming

The return values from this function are intended to be directly returnedfromv4l2_ioctl_ops->vidioc_streamon handler in the driver.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

enumv4l2_buf_typetype

type argument passed from userspace to vidioc_streamoff handler

Description

Should be called from vidioc_streamoff handler of a driver.

This function:

1. verifies current state,

2. stop streaming and dequeues any queued buffers, including those previouslypassed to the driver (after waiting for the driver to finish).

This call can be used for pausing playback.The return values from this function are intended to be directly returnedfrom vidioc_streamoff handler in the driver

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

Description

The vb2_queue structure should be allocated by the driver. The driver isresponsible of clearing it’s content and setting initial values for somerequired entries before calling this function.q->ops, q->mem_ops, q->type and q->io_modes are mandatory. Please referto thestructvb2_queue description in include/media/videobuf2-core.hfor more information.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

constchar*name

the queue name

Description

This function initializes the vb2_queue exactly likevb2_queue_init(),and additionally sets the queue name. The queue name is used for loggingpurpose, and should uniquely identify the queue within the context of thedevice it belongs to. This is useful to attribute kernel log messages to theright queue for m2m devices or other devices that handle multiple queues.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

Description

This function stops streaming and performs necessary clean ups, includingfreeing video buffer memory. The driver is responsible for freeingthe vb2_queue structure itself.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

unsignedinttype

the type to change to (V4L2_BUF_TYPE_VIDEO_*)

Description

This function changes the type of the vb2_queue. This is only possibleif the queue is not busy (i.e. no buffers have been allocated).

vb2_queue_change_type() can be used to support multiple buffer types usingthe same queue. The driver can implement v4l2_ioctl_ops.vidioc_reqbufs andv4l2_ioctl_ops.vidioc_create_bufs functions and callvb2_queue_change_type()before callingvb2_ioctl_reqbufs() orvb2_ioctl_create_bufs(), and thus“lock” the buffer type until the buffers have been released.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

structfile*file

file argument passed to the poll file operation handler

poll_table*wait

wait argument passed to the poll file operation handler

Description

This function implements poll file operation handler for a driver.For CAPTURE queues, if a buffer is ready to be dequeued, the userspace willbe informed that the file descriptor of a video device is available forreading.For OUTPUT queues, if a buffer is ready to be dequeued, the file descriptorwill be reported as available for writing.

If the driver usesstructv4l2_fh, thenvb2_poll() will also check for anypending events.

The return values from this function are intended to be directly returnedfrom poll handler in driver.

Parameters

structvb2_queue*q

pointer tostructvb2_queue with videobuf2 queue.

structfile*file

file through which the vb2 queue access is performed

Description

The queue is considered busy if it has an owner and the owner is not thefile.

Queue ownership is acquired and checked by some of the v4l2_ioctl_ops helpersbelow. Drivers can also use this function directly when they need toopen-code ioctl handlers, for instance to add additional checks between thequeue ownership test and the call to the corresponding vb2 operation.

Parameters

structvideo_device*vdev

pointer tostructvideo_device

Description

If the driver usesvb2_fop_release()/_vb2_fop_release(), then it should usevb2_video_unregister_device() instead ofvideo_unregister_device().

This function will callvideo_unregister_device() and then release thevb2_queue if streaming is in progress. This will stop streaming andthis will simplify the unbind sequence since after this call all subdevswill have stopped streaming as well.

Parameters

structvb2_queue*vq

pointer tostructvb2_queue

Description

..note:: only use if vq->lock is non-NULL.

Parameters

structvb2_queue*vq

pointer tostructvb2_queue

Description

..note:: only use if vq->lock is non-NULL.

Definition:

struct vb2_vmarea_handler {    refcount_t *refcount;    void (*put)(void *arg);    void *arg;};

Members

refcount

pointer torefcount_t entry in the buffer.

put

callback to function that decreases buffer refcount.

arg

argument forput callback.