Documentation/driver-api/dma-buf.rst

1 Buffer Sharing and Synchronization (dma-buf)
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
91 - The DMA buffer FD also supports a few dma-buf-specific ioctls, see
97 .. kernel-doc:: drivers/dma-buf/dma-buf.c
103 .. kernel-doc:: drivers/dma-buf/dma-buf.c
109 .. kernel-doc:: drivers/dma-buf/dma-buf.c
112 DMA-BUF statistics
114 .. kernel-doc:: drivers/dma-buf/dma-buf-sysfs-stats.c
120 .. kernel-doc:: include/uapi/linux/dma-buf.h
122 DMA-BUF locking convention
125 .. kernel-doc:: drivers/dma-buf/dma-buf.c
131 .. kernel-doc:: drivers/dma-buf/dma-buf.c
134 .. kernel-doc:: include/linux/dma-buf.h
138 -------------------
140 .. kernel-doc:: drivers/dma-buf/dma-resv.c
143 .. kernel-doc:: drivers/dma-buf/dma-resv.c
146 .. kernel-doc:: include/linux/dma-resv.h
150 ----------
152 .. kernel-doc:: drivers/dma-buf/dma-fence.c
155 DMA Fence Cross-Driver Contract
158 .. kernel-doc:: drivers/dma-buf/dma-fence.c
159    :doc: fence cross-driver contract
164 .. kernel-doc:: drivers/dma-buf/dma-fence.c
170 .. kernel-doc:: drivers/dma-buf/dma-fence.c
176 .. kernel-doc:: drivers/dma-buf/dma-fence.c
179 .. kernel-doc:: include/linux/dma-fence.h
185 .. kernel-doc:: drivers/dma-buf/dma-fence-array.c
188 .. kernel-doc:: include/linux/dma-fence-array.h
194 .. kernel-doc:: drivers/dma-buf/dma-fence-chain.c
197 .. kernel-doc:: include/linux/dma-fence-chain.h
203 .. kernel-doc:: include/linux/dma-fence-unwrap.h
209 .. kernel-doc:: drivers/dma-buf/sync_file.c
212 .. kernel-doc:: include/linux/sync_file.h
218 .. kernel-doc:: include/uapi/linux/sync_file.h
234 * Userspace fences or gpu futexes, fine-grained locking within a command buffer
239 * Long-running compute command buffers, while still using traditional end of
245 in-kernel DMA fences does not work, even when a fallback timeout is included to
246 protect against malicious userspace:
260 .. kernel-render:: DOT
268       kernel -> userspace [label="memory management"]
269       userspace -> kernel [label="Future fence, fence proxy, ..."]
310 on-demand fill a memory request. For now this means recoverable page
318 - The 3D workload might need to wait for the compute job to finish and release
321 - The compute workload might be stuck in a page fault, because the memory
327 - Compute workloads can always be preempted, even when a page fault is pending
330 - DMA fence workloads and workloads which need page fault handling have
335 - The reservation approach could be further refined by only reserving the
336   hardware resources for DMA fence workloads when they are in-flight. This must
340 - As a last resort, if the hardware provides no useful reservation mechanics,
348 - Only a fairly theoretical option would be to untangle these dependencies when
365 hit a page fault which holds up a userspace fence - supporting page faults on