Commit | Line | Data |
---|---|---|
caab277b | 1 | /* SPDX-License-Identifier: GPL-2.0-only */ |
d15bd7ee SS |
2 | /* |
3 | * Header file for dma buffer sharing framework. | |
4 | * | |
5 | * Copyright(C) 2011 Linaro Limited. All rights reserved. | |
6 | * Author: Sumit Semwal <sumit.semwal@ti.com> | |
7 | * | |
8 | * Many thanks to linaro-mm-sig list, and specially | |
9 | * Arnd Bergmann <arnd@arndb.de>, Rob Clark <rob@ti.com> and | |
10 | * Daniel Vetter <daniel@ffwll.ch> for their support in creation and | |
11 | * refining of this idea. | |
d15bd7ee SS |
12 | */ |
13 | #ifndef __DMA_BUF_H__ | |
14 | #define __DMA_BUF_H__ | |
15 | ||
01fd30da | 16 | #include <linux/dma-buf-map.h> |
d15bd7ee SS |
17 | #include <linux/file.h> |
18 | #include <linux/err.h> | |
d15bd7ee SS |
19 | #include <linux/scatterlist.h> |
20 | #include <linux/list.h> | |
21 | #include <linux/dma-mapping.h> | |
f9a24d1a | 22 | #include <linux/fs.h> |
f54d1867 | 23 | #include <linux/dma-fence.h> |
9b495a58 | 24 | #include <linux/wait.h> |
d15bd7ee | 25 | |
313162d0 | 26 | struct device; |
d15bd7ee SS |
27 | struct dma_buf; |
28 | struct dma_buf_attachment; | |
29 | ||
30 | /** | |
31 | * struct dma_buf_ops - operations possible on struct dma_buf | |
12c4727e SS |
32 | * @vmap: [optional] creates a virtual mapping for the buffer into kernel |
33 | * address space. Same restrictions as for vmap and friends apply. | |
34 | * @vunmap: [optional] unmaps a vmap from the buffer | |
d15bd7ee SS |
35 | */ |
36 | struct dma_buf_ops { | |
f13e143e CK |
37 | /** |
38 | * @cache_sgt_mapping: | |
39 | * | |
40 | * If true the framework will cache the first mapping made for each | |
41 | * attachment. This avoids creating mappings for attachments multiple | |
42 | * times. | |
43 | */ | |
44 | bool cache_sgt_mapping; | |
45 | ||
2904a8c1 DV |
46 | /** |
47 | * @attach: | |
48 | * | |
49 | * This is called from dma_buf_attach() to make sure that a given | |
a19741e5 CK |
50 | * &dma_buf_attachment.dev can access the provided &dma_buf. Exporters |
51 | * which support buffer objects in special locations like VRAM or | |
52 | * device-specific carveout areas should check whether the buffer could | |
53 | * be move to system memory (or directly accessed by the provided | |
54 | * device), and otherwise need to fail the attach operation. | |
2904a8c1 DV |
55 | * |
56 | * The exporter should also in general check whether the current | |
a4812d0b | 57 | * allocation fulfills the DMA constraints of the new device. If this |
2904a8c1 DV |
58 | * is not the case, and the allocation cannot be moved, it should also |
59 | * fail the attach operation. | |
60 | * | |
e9b4d7b5 DV |
61 | * Any exporter-private housekeeping data can be stored in the |
62 | * &dma_buf_attachment.priv pointer. | |
2904a8c1 DV |
63 | * |
64 | * This callback is optional. | |
65 | * | |
66 | * Returns: | |
67 | * | |
68 | * 0 on success, negative error code on failure. It might return -EBUSY | |
69 | * to signal that backing storage is already allocated and incompatible | |
70 | * with the requirements of requesting device. | |
71 | */ | |
a19741e5 | 72 | int (*attach)(struct dma_buf *, struct dma_buf_attachment *); |
d15bd7ee | 73 | |
2904a8c1 DV |
74 | /** |
75 | * @detach: | |
76 | * | |
77 | * This is called by dma_buf_detach() to release a &dma_buf_attachment. | |
78 | * Provided so that exporters can clean up any housekeeping for an | |
79 | * &dma_buf_attachment. | |
80 | * | |
81 | * This callback is optional. | |
82 | */ | |
d15bd7ee SS |
83 | void (*detach)(struct dma_buf *, struct dma_buf_attachment *); |
84 | ||
bb42df46 CK |
85 | /** |
86 | * @pin: | |
87 | * | |
85804b70 | 88 | * This is called by dma_buf_pin() and lets the exporter know that the |
5460601d GP |
89 | * DMA-buf can't be moved any more. Ideally, the exporter should |
90 | * pin the buffer so that it is generally accessible by all | |
c545781e | 91 | * devices. |
bb42df46 | 92 | * |
85804b70 | 93 | * This is called with the &dmabuf.resv object locked and is mutual |
bd2275ee | 94 | * exclusive with @cache_sgt_mapping. |
bb42df46 | 95 | * |
c545781e DV |
96 | * This is called automatically for non-dynamic importers from |
97 | * dma_buf_attach(). | |
bb42df46 | 98 | * |
89bcadc8 DV |
99 | * Note that similar to non-dynamic exporters in their @map_dma_buf |
100 | * callback the driver must guarantee that the memory is available for | |
101 | * use and cleared of any old data by the time this function returns. | |
102 | * Drivers which pipeline their buffer moves internally must wait for | |
103 | * all moves and clears to complete. | |
104 | * | |
bb42df46 CK |
105 | * Returns: |
106 | * | |
107 | * 0 on success, negative error code on failure. | |
108 | */ | |
109 | int (*pin)(struct dma_buf_attachment *attach); | |
110 | ||
111 | /** | |
112 | * @unpin: | |
113 | * | |
85804b70 | 114 | * This is called by dma_buf_unpin() and lets the exporter know that the |
bb42df46 CK |
115 | * DMA-buf can be moved again. |
116 | * | |
bd2275ee CK |
117 | * This is called with the dmabuf->resv object locked and is mutual |
118 | * exclusive with @cache_sgt_mapping. | |
bb42df46 CK |
119 | * |
120 | * This callback is optional. | |
121 | */ | |
122 | void (*unpin)(struct dma_buf_attachment *attach); | |
123 | ||
2904a8c1 DV |
124 | /** |
125 | * @map_dma_buf: | |
126 | * | |
127 | * This is called by dma_buf_map_attachment() and is used to map a | |
128 | * shared &dma_buf into device address space, and it is mandatory. It | |
bb42df46 | 129 | * can only be called if @attach has been called successfully. |
2904a8c1 DV |
130 | * |
131 | * This call may sleep, e.g. when the backing storage first needs to be | |
132 | * allocated, or moved to a location suitable for all currently attached | |
133 | * devices. | |
134 | * | |
135 | * Note that any specific buffer attributes required for this function | |
136 | * should get added to device_dma_parameters accessible via | |
e9b4d7b5 | 137 | * &device.dma_params from the &dma_buf_attachment. The @attach callback |
2904a8c1 DV |
138 | * should also check these constraints. |
139 | * | |
140 | * If this is being called for the first time, the exporter can now | |
141 | * choose to scan through the list of attachments for this buffer, | |
142 | * collate the requirements of the attached devices, and choose an | |
143 | * appropriate backing storage for the buffer. | |
144 | * | |
145 | * Based on enum dma_data_direction, it might be possible to have | |
146 | * multiple users accessing at the same time (for reading, maybe), or | |
147 | * any other kind of sharing that the exporter might wish to make | |
148 | * available to buffer-users. | |
149 | * | |
15fd552d CK |
150 | * This is always called with the dmabuf->resv object locked when |
151 | * the dynamic_mapping flag is true. | |
152 | * | |
89bcadc8 DV |
153 | * Note that for non-dynamic exporters the driver must guarantee that |
154 | * that the memory is available for use and cleared of any old data by | |
155 | * the time this function returns. Drivers which pipeline their buffer | |
156 | * moves internally must wait for all moves and clears to complete. | |
157 | * Dynamic exporters do not need to follow this rule: For non-dynamic | |
158 | * importers the buffer is already pinned through @pin, which has the | |
159 | * same requirements. Dynamic importers otoh are required to obey the | |
160 | * dma_resv fences. | |
161 | * | |
2904a8c1 DV |
162 | * Returns: |
163 | * | |
a4812d0b | 164 | * A &sg_table scatter list of the backing storage of the DMA buffer, |
2904a8c1 | 165 | * already mapped into the device address space of the &device attached |
ac80cd17 JX |
166 | * with the provided &dma_buf_attachment. The addresses and lengths in |
167 | * the scatter list are PAGE_SIZE aligned. | |
2904a8c1 DV |
168 | * |
169 | * On failure, returns a negative error value wrapped into a pointer. | |
170 | * May also return -EINTR when a signal was received while being | |
171 | * blocked. | |
84335675 DV |
172 | * |
173 | * Note that exporters should not try to cache the scatter list, or | |
174 | * return the same one for multiple calls. Caching is done either by the | |
175 | * DMA-BUF code (for non-dynamic importers) or the importer. Ownership | |
176 | * of the scatter list is transferred to the caller, and returned by | |
177 | * @unmap_dma_buf. | |
d15bd7ee SS |
178 | */ |
179 | struct sg_table * (*map_dma_buf)(struct dma_buf_attachment *, | |
2904a8c1 DV |
180 | enum dma_data_direction); |
181 | /** | |
182 | * @unmap_dma_buf: | |
183 | * | |
184 | * This is called by dma_buf_unmap_attachment() and should unmap and | |
185 | * release the &sg_table allocated in @map_dma_buf, and it is mandatory. | |
a4812d0b | 186 | * For static dma_buf handling this might also unpin the backing |
bb42df46 | 187 | * storage if this is the last mapping of the DMA buffer. |
2904a8c1 | 188 | */ |
d15bd7ee | 189 | void (*unmap_dma_buf)(struct dma_buf_attachment *, |
2904a8c1 DV |
190 | struct sg_table *, |
191 | enum dma_data_direction); | |
192 | ||
d15bd7ee SS |
193 | /* TODO: Add try_map_dma_buf version, to return immed with -EBUSY |
194 | * if the call would block. | |
195 | */ | |
196 | ||
2904a8c1 DV |
197 | /** |
198 | * @release: | |
199 | * | |
200 | * Called after the last dma_buf_put to release the &dma_buf, and | |
201 | * mandatory. | |
202 | */ | |
d15bd7ee SS |
203 | void (*release)(struct dma_buf *); |
204 | ||
0959a168 DV |
205 | /** |
206 | * @begin_cpu_access: | |
207 | * | |
208 | * This is called from dma_buf_begin_cpu_access() and allows the | |
de9114ec DV |
209 | * exporter to ensure that the memory is actually coherent for cpu |
210 | * access. The exporter also needs to ensure that cpu access is coherent | |
211 | * for the access direction. The direction can be used by the exporter | |
212 | * to optimize the cache flushing, i.e. access with a different | |
0959a168 DV |
213 | * direction (read instead of write) might return stale or even bogus |
214 | * data (e.g. when the exporter needs to copy the data to temporary | |
215 | * storage). | |
216 | * | |
de9114ec DV |
217 | * Note that this is both called through the DMA_BUF_IOCTL_SYNC IOCTL |
218 | * command for userspace mappings established through @mmap, and also | |
219 | * for kernel mappings established with @vmap. | |
0959a168 | 220 | * |
de9114ec | 221 | * This callback is optional. |
0959a168 DV |
222 | * |
223 | * Returns: | |
224 | * | |
225 | * 0 on success or a negative error code on failure. This can for | |
226 | * example fail when the backing storage can't be allocated. Can also | |
227 | * return -ERESTARTSYS or -EINTR when the call has been interrupted and | |
228 | * needs to be restarted. | |
229 | */ | |
831e9da7 | 230 | int (*begin_cpu_access)(struct dma_buf *, enum dma_data_direction); |
0959a168 DV |
231 | |
232 | /** | |
233 | * @end_cpu_access: | |
234 | * | |
235 | * This is called from dma_buf_end_cpu_access() when the importer is | |
236 | * done accessing the CPU. The exporter can use this to flush caches and | |
de9114ec | 237 | * undo anything else done in @begin_cpu_access. |
0959a168 DV |
238 | * |
239 | * This callback is optional. | |
240 | * | |
241 | * Returns: | |
242 | * | |
243 | * 0 on success or a negative error code on failure. Can return | |
244 | * -ERESTARTSYS or -EINTR when the call has been interrupted and needs | |
245 | * to be restarted. | |
246 | */ | |
18b862dc | 247 | int (*end_cpu_access)(struct dma_buf *, enum dma_data_direction); |
4c78513e | 248 | |
0959a168 DV |
249 | /** |
250 | * @mmap: | |
251 | * | |
252 | * This callback is used by the dma_buf_mmap() function | |
253 | * | |
254 | * Note that the mapping needs to be incoherent, userspace is expected | |
a4812d0b | 255 | * to bracket CPU access using the DMA_BUF_IOCTL_SYNC interface. |
0959a168 DV |
256 | * |
257 | * Because dma-buf buffers have invariant size over their lifetime, the | |
258 | * dma-buf core checks whether a vma is too large and rejects such | |
259 | * mappings. The exporter hence does not need to duplicate this check. | |
260 | * Drivers do not need to check this themselves. | |
261 | * | |
262 | * If an exporter needs to manually flush caches and hence needs to fake | |
263 | * coherency for mmap support, it needs to be able to zap all the ptes | |
264 | * pointing at the backing storage. Now linux mm needs a struct | |
265 | * address_space associated with the struct file stored in vma->vm_file | |
266 | * to do that with the function unmap_mapping_range. But the dma_buf | |
267 | * framework only backs every dma_buf fd with the anon_file struct file, | |
268 | * i.e. all dma_bufs share the same file. | |
269 | * | |
270 | * Hence exporters need to setup their own file (and address_space) | |
271 | * association by setting vma->vm_file and adjusting vma->vm_pgoff in | |
272 | * the dma_buf mmap callback. In the specific case of a gem driver the | |
273 | * exporter could use the shmem file already provided by gem (and set | |
274 | * vm_pgoff = 0). Exporters can then zap ptes by unmapping the | |
275 | * corresponding range of the struct address_space associated with their | |
276 | * own file. | |
277 | * | |
278 | * This callback is optional. | |
279 | * | |
280 | * Returns: | |
281 | * | |
282 | * 0 on success or a negative error code on failure. | |
283 | */ | |
4c78513e | 284 | int (*mmap)(struct dma_buf *, struct vm_area_struct *vma); |
98f86c9e | 285 | |
6619ccf1 | 286 | int (*vmap)(struct dma_buf *dmabuf, struct dma_buf_map *map); |
20e76f1a | 287 | void (*vunmap)(struct dma_buf *dmabuf, struct dma_buf_map *map); |
d15bd7ee SS |
288 | }; |
289 | ||
290 | /** | |
291 | * struct dma_buf - shared buffer object | |
2904a8c1 DV |
292 | * |
293 | * This represents a shared buffer, created by calling dma_buf_export(). The | |
294 | * userspace representation is a normal file descriptor, which can be created by | |
295 | * calling dma_buf_fd(). | |
296 | * | |
297 | * Shared dma buffers are reference counted using dma_buf_put() and | |
298 | * get_dma_buf(). | |
299 | * | |
f641d3b5 | 300 | * Device DMA access is handled by the separate &struct dma_buf_attachment. |
d15bd7ee SS |
301 | */ |
302 | struct dma_buf { | |
d6abed2a DV |
303 | /** |
304 | * @size: | |
305 | * | |
306 | * Size of the buffer; invariant over the lifetime of the buffer. | |
307 | */ | |
d15bd7ee | 308 | size_t size; |
d6abed2a DV |
309 | |
310 | /** | |
311 | * @file: | |
312 | * | |
313 | * File pointer used for sharing buffers across, and for refcounting. | |
314 | * See dma_buf_get() and dma_buf_put(). | |
315 | */ | |
d15bd7ee | 316 | struct file *file; |
d6abed2a DV |
317 | |
318 | /** | |
319 | * @attachments: | |
320 | * | |
321 | * List of dma_buf_attachment that denotes all devices attached, | |
322 | * protected by &dma_resv lock @resv. | |
323 | */ | |
d15bd7ee | 324 | struct list_head attachments; |
d6abed2a DV |
325 | |
326 | /** @ops: dma_buf_ops associated with this buffer object. */ | |
d15bd7ee | 327 | const struct dma_buf_ops *ops; |
d6abed2a DV |
328 | |
329 | /** | |
330 | * @lock: | |
331 | * | |
332 | * Used internally to serialize list manipulation, attach/detach and | |
333 | * vmap/unmap. Note that in many cases this is superseeded by | |
334 | * dma_resv_lock() on @resv. | |
335 | */ | |
d15bd7ee | 336 | struct mutex lock; |
d6abed2a DV |
337 | |
338 | /** | |
339 | * @vmapping_counter: | |
340 | * | |
341 | * Used internally to refcnt the vmaps returned by dma_buf_vmap(). | |
342 | * Protected by @lock. | |
343 | */ | |
f00b4dad | 344 | unsigned vmapping_counter; |
d6abed2a DV |
345 | |
346 | /** | |
347 | * @vmap_ptr: | |
348 | * The current vmap ptr if @vmapping_counter > 0. Protected by @lock. | |
349 | */ | |
01fd30da | 350 | struct dma_buf_map vmap_ptr; |
d6abed2a DV |
351 | |
352 | /** | |
353 | * @exp_name: | |
354 | * | |
355 | * Name of the exporter; useful for debugging. See the | |
356 | * DMA_BUF_SET_NAME IOCTL. | |
357 | */ | |
78df9695 | 358 | const char *exp_name; |
d6abed2a DV |
359 | |
360 | /** | |
361 | * @name: | |
362 | * | |
363 | * Userspace-provided name; useful for accounting and debugging, | |
364 | * protected by dma_resv_lock() on @resv and @name_lock for read access. | |
365 | */ | |
bb2bb903 | 366 | const char *name; |
d6abed2a DV |
367 | |
368 | /** @name_lock: Spinlock to protect name acces for read access. */ | |
0f50257f | 369 | spinlock_t name_lock; |
d6abed2a DV |
370 | |
371 | /** | |
372 | * @owner: | |
373 | * | |
374 | * Pointer to exporter module; used for refcounting when exporter is a | |
375 | * kernel module. | |
376 | */ | |
9abdffe2 | 377 | struct module *owner; |
d6abed2a DV |
378 | |
379 | /** @list_node: node for dma_buf accounting and debugging. */ | |
b89e3563 | 380 | struct list_head list_node; |
d6abed2a DV |
381 | |
382 | /** @priv: exporter specific private data for this buffer object. */ | |
d15bd7ee | 383 | void *priv; |
d6abed2a DV |
384 | |
385 | /** | |
386 | * @resv: | |
387 | * | |
388 | * Reservation object linked to this dma-buf. | |
05459351 DV |
389 | * |
390 | * IMPLICIT SYNCHRONIZATION RULES: | |
391 | * | |
392 | * Drivers which support implicit synchronization of buffer access as | |
393 | * e.g. exposed in `Implicit Fence Poll Support`_ must follow the | |
394 | * below rules. | |
395 | * | |
396 | * - Drivers must add a shared fence through dma_resv_add_shared_fence() | |
397 | * for anything the userspace API considers a read access. This highly | |
398 | * depends upon the API and window system. | |
399 | * | |
400 | * - Similarly drivers must set the exclusive fence through | |
401 | * dma_resv_add_excl_fence() for anything the userspace API considers | |
402 | * write access. | |
403 | * | |
404 | * - Drivers may just always set the exclusive fence, since that only | |
405 | * causes unecessarily synchronization, but no correctness issues. | |
406 | * | |
407 | * - Some drivers only expose a synchronous userspace API with no | |
408 | * pipelining across drivers. These do not set any fences for their | |
409 | * access. An example here is v4l. | |
410 | * | |
411 | * DYNAMIC IMPORTER RULES: | |
412 | * | |
413 | * Dynamic importers, see dma_buf_attachment_is_dynamic(), have | |
414 | * additional constraints on how they set up fences: | |
415 | * | |
416 | * - Dynamic importers must obey the exclusive fence and wait for it to | |
417 | * signal before allowing access to the buffer's underlying storage | |
418 | * through the device. | |
419 | * | |
420 | * - Dynamic importers should set fences for any access that they can't | |
421 | * disable immediately from their &dma_buf_attach_ops.move_notify | |
422 | * callback. | |
d9edf92d DV |
423 | * |
424 | * IMPORTANT: | |
425 | * | |
426 | * All drivers must obey the struct dma_resv rules, specifically the | |
427 | * rules for updating fences, see &dma_resv.fence_excl and | |
428 | * &dma_resv.fence. If these dependency rules are broken access tracking | |
429 | * can be lost resulting in use after free issues. | |
d6abed2a | 430 | */ |
52791eee | 431 | struct dma_resv *resv; |
9b495a58 | 432 | |
d6abed2a | 433 | /** @poll: for userspace poll support */ |
9b495a58 ML |
434 | wait_queue_head_t poll; |
435 | ||
dd66f56c CK |
436 | /** @cb_in: for userspace poll support */ |
437 | /** @cb_out: for userspace poll support */ | |
9b495a58 | 438 | struct dma_buf_poll_cb_t { |
f54d1867 | 439 | struct dma_fence_cb cb; |
9b495a58 ML |
440 | wait_queue_head_t *poll; |
441 | ||
01e5d556 | 442 | __poll_t active; |
6b51b02a | 443 | } cb_in, cb_out; |
bdb8d06d | 444 | #ifdef CONFIG_DMABUF_SYSFS_STATS |
d6abed2a DV |
445 | /** |
446 | * @sysfs_entry: | |
447 | * | |
448 | * For exposing information about this buffer in sysfs. See also | |
449 | * `DMA-BUF statistics`_ for the uapi this enables. | |
450 | */ | |
bdb8d06d HV |
451 | struct dma_buf_sysfs_entry { |
452 | struct kobject kobj; | |
453 | struct dma_buf *dmabuf; | |
bdb8d06d HV |
454 | } *sysfs_entry; |
455 | #endif | |
d15bd7ee SS |
456 | }; |
457 | ||
bb42df46 CK |
458 | /** |
459 | * struct dma_buf_attach_ops - importer operations for an attachment | |
bb42df46 CK |
460 | * |
461 | * Attachment operations implemented by the importer. | |
462 | */ | |
463 | struct dma_buf_attach_ops { | |
09606b54 CK |
464 | /** |
465 | * @allow_peer2peer: | |
466 | * | |
467 | * If this is set to true the importer must be able to handle peer | |
468 | * resources without struct pages. | |
469 | */ | |
470 | bool allow_peer2peer; | |
471 | ||
bb42df46 | 472 | /** |
6f49c251 | 473 | * @move_notify: [optional] notification that the DMA-buf is moving |
bb42df46 CK |
474 | * |
475 | * If this callback is provided the framework can avoid pinning the | |
476 | * backing store while mappings exists. | |
477 | * | |
478 | * This callback is called with the lock of the reservation object | |
479 | * associated with the dma_buf held and the mapping function must be | |
480 | * called with this lock held as well. This makes sure that no mapping | |
481 | * is created concurrently with an ongoing move operation. | |
482 | * | |
483 | * Mappings stay valid and are not directly affected by this callback. | |
484 | * But the DMA-buf can now be in a different physical location, so all | |
485 | * mappings should be destroyed and re-created as soon as possible. | |
486 | * | |
487 | * New mappings can be created after this callback returns, and will | |
488 | * point to the new location of the DMA-buf. | |
489 | */ | |
490 | void (*move_notify)(struct dma_buf_attachment *attach); | |
491 | }; | |
492 | ||
d15bd7ee SS |
493 | /** |
494 | * struct dma_buf_attachment - holds device-buffer attachment data | |
495 | * @dmabuf: buffer for this attachment. | |
496 | * @dev: device attached to the buffer. | |
15fd552d | 497 | * @node: list of dma_buf_attachment, protected by dma_resv lock of the dmabuf. |
f13e143e CK |
498 | * @sgt: cached mapping. |
499 | * @dir: direction of cached mapping. | |
09606b54 | 500 | * @peer2peer: true if the importer can handle peer resources without pages. |
d15bd7ee | 501 | * @priv: exporter specific attachment data. |
bb42df46 CK |
502 | * @importer_ops: importer operations for this attachment, if provided |
503 | * dma_buf_map/unmap_attachment() must be called with the dma_resv lock held. | |
504 | * @importer_priv: importer specific attachment data. | |
d15bd7ee SS |
505 | * |
506 | * This structure holds the attachment information between the dma_buf buffer | |
507 | * and its user device(s). The list contains one attachment struct per device | |
508 | * attached to the buffer. | |
2904a8c1 DV |
509 | * |
510 | * An attachment is created by calling dma_buf_attach(), and released again by | |
511 | * calling dma_buf_detach(). The DMA mapping itself needed to initiate a | |
512 | * transfer is created by dma_buf_map_attachment() and freed again by calling | |
513 | * dma_buf_unmap_attachment(). | |
d15bd7ee SS |
514 | */ |
515 | struct dma_buf_attachment { | |
516 | struct dma_buf *dmabuf; | |
517 | struct device *dev; | |
518 | struct list_head node; | |
f13e143e CK |
519 | struct sg_table *sgt; |
520 | enum dma_data_direction dir; | |
09606b54 | 521 | bool peer2peer; |
bb42df46 CK |
522 | const struct dma_buf_attach_ops *importer_ops; |
523 | void *importer_priv; | |
d15bd7ee SS |
524 | void *priv; |
525 | }; | |
526 | ||
d8fbe341 SS |
527 | /** |
528 | * struct dma_buf_export_info - holds information needed to export a dma_buf | |
9abdffe2 SS |
529 | * @exp_name: name of the exporter - useful for debugging. |
530 | * @owner: pointer to exporter module - used for refcounting kernel module | |
d8fbe341 | 531 | * @ops: Attach allocator-defined dma buf ops to the new buffer |
476b485b | 532 | * @size: Size of the buffer - invariant over the lifetime of the buffer |
d8fbe341 SS |
533 | * @flags: mode flags for the file |
534 | * @resv: reservation-object, NULL to allocate default one | |
535 | * @priv: Attach private data of allocator to this buffer | |
536 | * | |
537 | * This structure holds the information required to export the buffer. Used | |
538 | * with dma_buf_export() only. | |
539 | */ | |
540 | struct dma_buf_export_info { | |
541 | const char *exp_name; | |
9abdffe2 | 542 | struct module *owner; |
d8fbe341 SS |
543 | const struct dma_buf_ops *ops; |
544 | size_t size; | |
545 | int flags; | |
52791eee | 546 | struct dma_resv *resv; |
d8fbe341 SS |
547 | void *priv; |
548 | }; | |
549 | ||
550 | /** | |
2904a8c1 | 551 | * DEFINE_DMA_BUF_EXPORT_INFO - helper macro for exporters |
e2082e3a | 552 | * @name: export-info name |
2904a8c1 | 553 | * |
f641d3b5 | 554 | * DEFINE_DMA_BUF_EXPORT_INFO macro defines the &struct dma_buf_export_info, |
2904a8c1 | 555 | * zeroes it out and pre-populates exp_name in it. |
d8fbe341 | 556 | */ |
e2082e3a RC |
557 | #define DEFINE_DMA_BUF_EXPORT_INFO(name) \ |
558 | struct dma_buf_export_info name = { .exp_name = KBUILD_MODNAME, \ | |
9abdffe2 | 559 | .owner = THIS_MODULE } |
d8fbe341 | 560 | |
f9a24d1a RC |
561 | /** |
562 | * get_dma_buf - convenience wrapper for get_file. | |
563 | * @dmabuf: [in] pointer to dma_buf | |
564 | * | |
565 | * Increments the reference count on the dma-buf, needed in case of drivers | |
566 | * that either need to create additional references to the dmabuf on the | |
567 | * kernel side. For example, an exporter that needs to keep a dmabuf ptr | |
568 | * so that subsequent exports don't create a new dmabuf. | |
569 | */ | |
570 | static inline void get_dma_buf(struct dma_buf *dmabuf) | |
571 | { | |
572 | get_file(dmabuf->file); | |
573 | } | |
574 | ||
15fd552d CK |
575 | /** |
576 | * dma_buf_is_dynamic - check if a DMA-buf uses dynamic mappings. | |
577 | * @dmabuf: the DMA-buf to check | |
578 | * | |
579 | * Returns true if a DMA-buf exporter wants to be called with the dma_resv | |
580 | * locked for the map/unmap callbacks, false if it doesn't wants to be called | |
581 | * with the lock held. | |
582 | */ | |
583 | static inline bool dma_buf_is_dynamic(struct dma_buf *dmabuf) | |
584 | { | |
bd2275ee | 585 | return !!dmabuf->ops->pin; |
15fd552d CK |
586 | } |
587 | ||
588 | /** | |
589 | * dma_buf_attachment_is_dynamic - check if a DMA-buf attachment uses dynamic | |
a4812d0b | 590 | * mappings |
15fd552d CK |
591 | * @attach: the DMA-buf attachment to check |
592 | * | |
593 | * Returns true if a DMA-buf importer wants to call the map/unmap functions with | |
594 | * the dma_resv lock held. | |
595 | */ | |
596 | static inline bool | |
597 | dma_buf_attachment_is_dynamic(struct dma_buf_attachment *attach) | |
598 | { | |
bb42df46 | 599 | return !!attach->importer_ops; |
15fd552d CK |
600 | } |
601 | ||
d15bd7ee | 602 | struct dma_buf_attachment *dma_buf_attach(struct dma_buf *dmabuf, |
15fd552d CK |
603 | struct device *dev); |
604 | struct dma_buf_attachment * | |
605 | dma_buf_dynamic_attach(struct dma_buf *dmabuf, struct device *dev, | |
bb42df46 CK |
606 | const struct dma_buf_attach_ops *importer_ops, |
607 | void *importer_priv); | |
d15bd7ee | 608 | void dma_buf_detach(struct dma_buf *dmabuf, |
15fd552d | 609 | struct dma_buf_attachment *attach); |
bb42df46 CK |
610 | int dma_buf_pin(struct dma_buf_attachment *attach); |
611 | void dma_buf_unpin(struct dma_buf_attachment *attach); | |
78df9695 | 612 | |
d8fbe341 | 613 | struct dma_buf *dma_buf_export(const struct dma_buf_export_info *exp_info); |
78df9695 | 614 | |
55c1c4ca | 615 | int dma_buf_fd(struct dma_buf *dmabuf, int flags); |
d15bd7ee SS |
616 | struct dma_buf *dma_buf_get(int fd); |
617 | void dma_buf_put(struct dma_buf *dmabuf); | |
618 | ||
619 | struct sg_table *dma_buf_map_attachment(struct dma_buf_attachment *, | |
620 | enum dma_data_direction); | |
33ea2dcb SS |
621 | void dma_buf_unmap_attachment(struct dma_buf_attachment *, struct sg_table *, |
622 | enum dma_data_direction); | |
15fd552d | 623 | void dma_buf_move_notify(struct dma_buf *dma_buf); |
831e9da7 | 624 | int dma_buf_begin_cpu_access(struct dma_buf *dma_buf, |
fc13020e | 625 | enum dma_data_direction dir); |
18b862dc CW |
626 | int dma_buf_end_cpu_access(struct dma_buf *dma_buf, |
627 | enum dma_data_direction dir); | |
4c78513e DV |
628 | |
629 | int dma_buf_mmap(struct dma_buf *, struct vm_area_struct *, | |
630 | unsigned long); | |
6619ccf1 | 631 | int dma_buf_vmap(struct dma_buf *dmabuf, struct dma_buf_map *map); |
20e76f1a | 632 | void dma_buf_vunmap(struct dma_buf *dmabuf, struct dma_buf_map *map); |
d15bd7ee | 633 | #endif /* __DMA_BUF_H__ */ |