Commit | Line | Data |
---|---|---|
868c97a8 DV |
1 | Buffer Sharing and Synchronization |
2 | ================================== | |
3 | ||
4 | The dma-buf subsystem provides the framework for sharing buffers for | |
5 | hardware (DMA) access across multiple device drivers and subsystems, and | |
6 | for synchronizing asynchronous hardware access. | |
7 | ||
8 | This is used, for example, by drm "prime" multi-GPU support, but is of | |
9 | course not limited to GPU use cases. | |
10 | ||
11 | The three main components of this are: (1) dma-buf, representing a | |
12 | sg_table and exposed to userspace as a file descriptor to allow passing | |
13 | between devices, (2) fence, which provides a mechanism to signal when | |
14 | one device as finished access, and (3) reservation, which manages the | |
15 | shared or exclusive fence(s) associated with the buffer. | |
16 | ||
17 | Shared DMA Buffers | |
18 | ------------------ | |
19 | ||
2904a8c1 DV |
20 | This document serves as a guide to device-driver writers on what is the dma-buf |
21 | buffer sharing API, how to use it for exporting and using shared buffers. | |
22 | ||
23 | Any device driver which wishes to be a part of DMA buffer sharing, can do so as | |
24 | either the 'exporter' of buffers, or the 'user' or 'importer' of buffers. | |
25 | ||
26 | Say a driver A wants to use buffers created by driver B, then we call B as the | |
27 | exporter, and A as buffer-user/importer. | |
28 | ||
29 | The exporter | |
30 | ||
31 | - implements and manages operations in :c:type:`struct dma_buf_ops | |
32 | <dma_buf_ops>` for the buffer, | |
33 | - allows other users to share the buffer by using dma_buf sharing APIs, | |
34 | - manages the details of buffer allocation, wrapped int a :c:type:`struct | |
35 | dma_buf <dma_buf>`, | |
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 | |
38 | this buffer. | |
39 | ||
40 | The buffer-user | |
41 | ||
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 | |
45 | buffer in memory, mapped into its own address space, so it can access the | |
46 | same area of memory. This interface is provided by :c:type:`struct | |
47 | dma_buf_attachment <dma_buf_attachment>`. | |
48 | ||
e7e21c72 DV |
49 | Any exporters or users of the dma-buf buffer sharing framework must have a |
50 | 'select DMA_SHARED_BUFFER' in their respective Kconfigs. | |
51 | ||
52 | Userspace Interface Notes | |
53 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | |
54 | ||
55 | Mostly a DMA buffer file descriptor is simply an opaque object for userspace, | |
56 | and hence the generic interface exposed is very minimal. There's a few things to | |
57 | consider though: | |
58 | ||
59 | - Since kernel 3.12 the dma-buf FD supports the llseek system call, but only | |
60 | with offset=0 and whence=SEEK_END|SEEK_SET. SEEK_SET is supported to allow | |
61 | the usual size discover pattern size = SEEK_END(0); SEEK_SET(0). Every other | |
62 | llseek operation will report -EINVAL. | |
63 | ||
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 | |
66 | size using llseek. | |
67 | ||
68 | - In order to avoid fd leaks on exec, the FD_CLOEXEC flag must be set | |
69 | on the file descriptor. This is not just a resource leak, but a | |
70 | potential security hole. It could give the newly exec'd application | |
71 | access to buffers, via the leaked fd, to which it should otherwise | |
72 | not be permitted access. | |
73 | ||
74 | The problem with doing this via a separate fcntl() call, versus doing it | |
75 | atomically when the fd is created, is that this is inherently racy in a | |
76 | multi-threaded app[3]. The issue is made worse when it is library code | |
77 | opening/creating the file descriptor, as the application may not even be | |
78 | aware of the fd's. | |
79 | ||
80 | To avoid this problem, userspace must have a way to request O_CLOEXEC | |
81 | flag be set when the dma-buf fd is created. So any API provided by | |
82 | the exporting driver to create a dmabuf fd must provide a way to let | |
83 | userspace control setting of O_CLOEXEC flag passed in to dma_buf_fd(). | |
84 | ||
85 | - Memory mapping the contents of the DMA buffer is also supported. See the | |
86 | discussion below on `CPU Access to DMA Buffer Objects`_ for the full details. | |
87 | ||
88 | - The DMA buffer FD is also pollable, see `Fence Poll Support`_ below for | |
89 | details. | |
90 | ||
2904a8c1 DV |
91 | Basic Operation and Device DMA Access |
92 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
93 | ||
94 | .. kernel-doc:: drivers/dma-buf/dma-buf.c | |
95 | :doc: dma buf device access | |
96 | ||
0959a168 DV |
97 | CPU Access to DMA Buffer Objects |
98 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
99 | ||
100 | .. kernel-doc:: drivers/dma-buf/dma-buf.c | |
101 | :doc: cpu access | |
102 | ||
e7e21c72 DV |
103 | Fence Poll Support |
104 | ~~~~~~~~~~~~~~~~~~ | |
105 | ||
106 | .. kernel-doc:: drivers/dma-buf/dma-buf.c | |
107 | :doc: fence polling | |
108 | ||
2904a8c1 DV |
109 | Kernel Functions and Structures Reference |
110 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
111 | ||
868c97a8 DV |
112 | .. kernel-doc:: drivers/dma-buf/dma-buf.c |
113 | :export: | |
114 | ||
115 | .. kernel-doc:: include/linux/dma-buf.h | |
116 | :internal: | |
117 | ||
118 | Reservation Objects | |
119 | ------------------- | |
120 | ||
121 | .. kernel-doc:: drivers/dma-buf/reservation.c | |
122 | :doc: Reservation Object Overview | |
123 | ||
124 | .. kernel-doc:: drivers/dma-buf/reservation.c | |
125 | :export: | |
126 | ||
127 | .. kernel-doc:: include/linux/reservation.h | |
128 | :internal: | |
129 | ||
130 | DMA Fences | |
131 | ---------- | |
132 | ||
133 | .. kernel-doc:: drivers/dma-buf/dma-fence.c | |
134 | :export: | |
135 | ||
136 | .. kernel-doc:: include/linux/dma-fence.h | |
137 | :internal: | |
138 | ||
139 | Seqno Hardware Fences | |
140 | ~~~~~~~~~~~~~~~~~~~~~ | |
141 | ||
142 | .. kernel-doc:: drivers/dma-buf/seqno-fence.c | |
143 | :export: | |
144 | ||
145 | .. kernel-doc:: include/linux/seqno-fence.h | |
146 | :internal: | |
147 | ||
148 | DMA Fence Array | |
149 | ~~~~~~~~~~~~~~~ | |
150 | ||
151 | .. kernel-doc:: drivers/dma-buf/dma-fence-array.c | |
152 | :export: | |
153 | ||
154 | .. kernel-doc:: include/linux/dma-fence-array.h | |
155 | :internal: | |
156 | ||
157 | DMA Fence uABI/Sync File | |
158 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
159 | ||
160 | .. kernel-doc:: drivers/dma-buf/sync_file.c | |
161 | :export: | |
162 | ||
163 | .. kernel-doc:: include/linux/sync_file.h | |
164 | :internal: | |
165 |