]>
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 | ||
49 | Basic Operation and Device DMA Access | |
50 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
51 | ||
52 | .. kernel-doc:: drivers/dma-buf/dma-buf.c | |
53 | :doc: dma buf device access | |
54 | ||
0959a168 DV |
55 | CPU Access to DMA Buffer Objects |
56 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
57 | ||
58 | .. kernel-doc:: drivers/dma-buf/dma-buf.c | |
59 | :doc: cpu access | |
60 | ||
2904a8c1 DV |
61 | Kernel Functions and Structures Reference |
62 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
63 | ||
868c97a8 DV |
64 | .. kernel-doc:: drivers/dma-buf/dma-buf.c |
65 | :export: | |
66 | ||
67 | .. kernel-doc:: include/linux/dma-buf.h | |
68 | :internal: | |
69 | ||
70 | Reservation Objects | |
71 | ------------------- | |
72 | ||
73 | .. kernel-doc:: drivers/dma-buf/reservation.c | |
74 | :doc: Reservation Object Overview | |
75 | ||
76 | .. kernel-doc:: drivers/dma-buf/reservation.c | |
77 | :export: | |
78 | ||
79 | .. kernel-doc:: include/linux/reservation.h | |
80 | :internal: | |
81 | ||
82 | DMA Fences | |
83 | ---------- | |
84 | ||
85 | .. kernel-doc:: drivers/dma-buf/dma-fence.c | |
86 | :export: | |
87 | ||
88 | .. kernel-doc:: include/linux/dma-fence.h | |
89 | :internal: | |
90 | ||
91 | Seqno Hardware Fences | |
92 | ~~~~~~~~~~~~~~~~~~~~~ | |
93 | ||
94 | .. kernel-doc:: drivers/dma-buf/seqno-fence.c | |
95 | :export: | |
96 | ||
97 | .. kernel-doc:: include/linux/seqno-fence.h | |
98 | :internal: | |
99 | ||
100 | DMA Fence Array | |
101 | ~~~~~~~~~~~~~~~ | |
102 | ||
103 | .. kernel-doc:: drivers/dma-buf/dma-fence-array.c | |
104 | :export: | |
105 | ||
106 | .. kernel-doc:: include/linux/dma-fence-array.h | |
107 | :internal: | |
108 | ||
109 | DMA Fence uABI/Sync File | |
110 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
111 | ||
112 | .. kernel-doc:: drivers/dma-buf/sync_file.c | |
113 | :export: | |
114 | ||
115 | .. kernel-doc:: include/linux/sync_file.h | |
116 | :internal: | |
117 |