Documentation/driver-api/dma-buf.rst

4 The dma-buf subsystem provides the framework for sharing buffers for
8 This is used, for example, by drm "prime" multi-GPU support, but is of
11 The three main components of this are: (1) dma-buf, representing a
18 ------------------
20 This document serves as a guide to device-driver writers on what is the dma-buf
27 exporter, and A as buffer-user/importer.
31  - implements and manages operations in :c:type:`struct dma_buf_ops
33  - allows other users to share the buffer by using dma_buf sharing APIs,
34  - manages the details of buffer allocation, wrapped in a :c:type:`struct
36  - decides about the actual backing storage where this allocation happens,
37  - and takes care of any migration of scatterlist - for all (shared) users of
40 The buffer-user
42  - is one of (many) sharing users of the buffer.
43  - doesn't need to worry about how the buffer is allocated, or where.
44  - and needs a mechanism to get access to the scatterlist that makes up this
49 Any exporters or users of the dma-buf buffer sharing framework must have a
59 - Since kernel 3.12 the dma-buf FD supports the llseek system call, but only
62   llseek operation will report -EINVAL.
64   If llseek on dma-buf FDs isn't support the kernel will report -ESPIPE for all
65   cases. Userspace can use this to detect support for discovering the dma-buf
68 - In order to avoid fd leaks on exec, the FD_CLOEXEC flag must be set
70   potential security hole.  It could give the newly exec'd application
76   multi-threaded app[3].  The issue is made worse when it is library code
81   flag be set when the dma-buf fd is created.  So any API provided by
85 - Memory mapping the contents of the DMA buffer is also supported. See the
88 - The DMA buffer FD is also pollable, see `Implicit Fence Poll Support`_ below for
94 .. kernel-doc:: drivers/dma-buf/dma-buf.c
100 .. kernel-doc:: drivers/dma-buf/dma-buf.c
106 .. kernel-doc:: drivers/dma-buf/dma-buf.c
112 .. kernel-doc:: drivers/dma-buf/dma-buf.c
115 .. kernel-doc:: include/linux/dma-buf.h
119 -------------------
121 .. kernel-doc:: drivers/dma-buf/dma-resv.c
124 .. kernel-doc:: drivers/dma-buf/dma-resv.c
127 .. kernel-doc:: include/linux/dma-resv.h
131 ----------
133 .. kernel-doc:: drivers/dma-buf/dma-fence.c
136 DMA Fence Cross-Driver Contract
139 .. kernel-doc:: drivers/dma-buf/dma-fence.c
140    :doc: fence cross-driver contract
145 .. kernel-doc:: drivers/dma-buf/dma-fence.c
151 .. kernel-doc:: drivers/dma-buf/dma-fence.c
154 .. kernel-doc:: include/linux/dma-fence.h
160 .. kernel-doc:: include/linux/seqno-fence.h
166 .. kernel-doc:: drivers/dma-buf/dma-fence-array.c
169 .. kernel-doc:: include/linux/dma-fence-array.h
175 .. kernel-doc:: drivers/dma-buf/sync_file.c
178 .. kernel-doc:: include/linux/sync_file.h
194 * Userspace fences or gpu futexes, fine-grained locking within a command buffer
199 * Long-running compute command buffers, while still using traditional end of
205 in-kernel DMA fences does not work, even when a fallback timeout is included to
206 protect against malicious userspace:
220 .. kernel-render:: DOT
228       kernel -> userspace [label="memory management"]
229       userspace -> kernel [label="Future fence, fence proxy, ..."]