dma_buf Struct Reference

#include <dma-buf.h>

Collaboration diagram for dma_buf:

Classes
struct	dma_buf_poll_cb_t

Public Attributes
size_t	size
struct file *	file
struct list_head	attachments
const struct dma_buf_ops *	ops
unsigned	vmapping_counter
struct iosys_map	vmap_ptr
const char *	exp_name
:
Userspace-provided name. Default value is NULL. If not NULL, length cannot be longer than DMA_BUF_NAME_LEN, including NIL char. Useful for accounting and debugging. Read/Write accesses are protected by @name_lock See the IOCTLs DMA_BUF_SET_NAME or DMA_BUF_SET_NAME_A/B
const char *	name
spinlock_t	name_lock
struct module *	owner
struct list_head	list_node
void *	priv
struct dma_resv *	resv
wait_queue_head_t	poll
struct dma_buf::dma_buf_poll_cb_t	cb_in
struct dma_buf::dma_buf_poll_cb_t	cb_out

Detailed Description

struct dma_buf - shared buffer object

This represents a shared buffer, created by calling dma_buf_export(). The userspace representation is a normal file descriptor, which can be created by calling dma_buf_fd().

Shared dma buffers are reference counted using dma_buf_put() and get_dma_buf().

Device DMA access is handled by the separate &struct dma_buf_attachment.

Member Data Documentation

attachments

struct list_head dma_buf::attachments

@attachments:

List of dma_buf_attachment that denotes all devices attached, protected by &dma_resv lock @resv.

cb_in

struct dma_buf::dma_buf_poll_cb_t dma_buf::cb_in

cb_out

struct dma_buf::dma_buf_poll_cb_t dma_buf::cb_out

exp_name

const char* dma_buf::exp_name

@exp_name:

Name of the exporter; useful for debugging. Must not be NULL

file

struct file* dma_buf::file

list_node

struct list_head dma_buf::list_node

@list_node: node for dma_buf accounting and debugging.

name

const char* dma_buf::name

name_lock

spinlock_t dma_buf::name_lock

@name_lock: Spinlock to protect name access for read access.

ops

const struct dma_buf_ops* dma_buf::ops

@ops: dma_buf_ops associated with this buffer object.

owner

struct module* dma_buf::owner

@owner:

Pointer to exporter module; used for refcounting when exporter is a kernel module.

poll

wait_queue_head_t dma_buf::poll

@poll: for userspace poll support

priv

void* dma_buf::priv

@priv: exporter specific private data for this buffer object.

resv

struct dma_resv* dma_buf::resv

@resv:

Reservation object linked to this dma-buf.

IMPLICIT SYNCHRONIZATION RULES:

Drivers which support implicit synchronization of buffer access as e.g. exposed in Implicit Fence Poll Support_ must follow the below rules.

• Drivers must add a read fence through dma_resv_add_fence() with the DMA_RESV_USAGE_READ flag for anything the userspace API considers a read access. This highly depends upon the API and window system.
• Similarly drivers must add a write fence through dma_resv_add_fence() with the DMA_RESV_USAGE_WRITE flag for anything the userspace API considers write access.
• Drivers may just always add a write fence, since that only causes unnecessary synchronization, but no correctness issues.
• Some drivers only expose a synchronous userspace API with no pipelining across drivers. These do not set any fences for their access. An example here is v4l.
• Driver should use dma_resv_usage_rw() when retrieving fences as dependency for implicit synchronization.

DYNAMIC IMPORTER RULES:

Dynamic importers, see dma_buf_attachment_is_dynamic(), have additional constraints on how they set up fences:

• Dynamic importers must obey the write fences and wait for them to signal before allowing access to the buffer's underlying storage through the device.
• Dynamic importers should set fences for any access that they can't disable immediately from their &dma_buf_attach_ops.invalidate_mappings callback.

IMPORTANT:

All drivers and memory management related functions must obey the struct dma_resv rules, specifically the rules for updating and obeying fences. See enum dma_resv_usage for further descriptions.

size

size_t dma_buf::size

@size:

Size of the buffer; invariant over the lifetime of the buffer.

vmap_ptr

struct iosys_map dma_buf::vmap_ptr

@vmap_ptr: The current vmap ptr if @vmapping_counter > 0. Protected by @resv.

vmapping_counter

unsigned dma_buf::vmapping_counter

@vmapping_counter:

Used internally to refcnt the vmaps returned by dma_buf_vmap(). Protected by @resv.

---

The documentation for this struct was generated from the following file:

• XenevaOS/BaseHdr/linux/dma-buf.h