]>
Commit | Line | Data |
---|---|---|
36c682f6 MCC |
1 | ============== |
2 | DMA attributes | |
3 | ============== | |
a75b0a2f AK |
4 | |
5 | This document describes the semantics of the DMA attributes that are | |
00085f1e | 6 | defined in linux/dma-mapping.h. |
a75b0a2f | 7 | |
1ed6af73 MN |
8 | DMA_ATTR_WEAK_ORDERING |
9 | ---------------------- | |
10 | ||
11 | DMA_ATTR_WEAK_ORDERING specifies that reads and writes to the mapping | |
12 | may be weakly ordered, that is that reads and writes may pass each other. | |
13 | ||
14 | Since it is optional for platforms to implement DMA_ATTR_WEAK_ORDERING, | |
15 | those that do not will simply ignore the attribute and exhibit default | |
16 | behavior. | |
8a413432 MS |
17 | |
18 | DMA_ATTR_WRITE_COMBINE | |
19 | ---------------------- | |
20 | ||
21 | DMA_ATTR_WRITE_COMBINE specifies that writes to the mapping may be | |
22 | buffered to improve performance. | |
23 | ||
24 | Since it is optional for platforms to implement DMA_ATTR_WRITE_COMBINE, | |
25 | those that do not will simply ignore the attribute and exhibit default | |
26 | behavior. | |
64d70fe5 MS |
27 | |
28 | DMA_ATTR_NON_CONSISTENT | |
29 | ----------------------- | |
30 | ||
31 | DMA_ATTR_NON_CONSISTENT lets the platform to choose to return either | |
32 | consistent or non-consistent memory as it sees fit. By using this API, | |
33 | you are guaranteeing to the platform that you have all the correct and | |
34 | necessary sync points for this memory in the driver. | |
d5724f17 MS |
35 | |
36 | DMA_ATTR_NO_KERNEL_MAPPING | |
37 | -------------------------- | |
38 | ||
39 | DMA_ATTR_NO_KERNEL_MAPPING lets the platform to avoid creating a kernel | |
40 | virtual mapping for the allocated buffer. On some architectures creating | |
41 | such mapping is non-trivial task and consumes very limited resources | |
42 | (like kernel virtual address space or dma consistent address space). | |
43 | Buffers allocated with this attribute can be only passed to user space | |
44 | by calling dma_mmap_attrs(). By using this API, you are guaranteeing | |
45 | that you won't dereference the pointer returned by dma_alloc_attr(). You | |
bf038227 | 46 | can treat it as a cookie that must be passed to dma_mmap_attrs() and |
d5724f17 MS |
47 | dma_free_attrs(). Make sure that both of these also get this attribute |
48 | set on each call. | |
49 | ||
50 | Since it is optional for platforms to implement | |
51 | DMA_ATTR_NO_KERNEL_MAPPING, those that do not will simply ignore the | |
52 | attribute and exhibit default behavior. | |
bdf5e487 MS |
53 | |
54 | DMA_ATTR_SKIP_CPU_SYNC | |
55 | ---------------------- | |
56 | ||
57 | By default dma_map_{single,page,sg} functions family transfer a given | |
58 | buffer from CPU domain to device domain. Some advanced use cases might | |
59 | require sharing a buffer between more than one device. This requires | |
60 | having a mapping created separately for each device and is usually | |
61 | performed by calling dma_map_{single,page,sg} function more than once | |
62 | for the given buffer with device pointer to each device taking part in | |
63 | the buffer sharing. The first call transfers a buffer from 'CPU' domain | |
64 | to 'device' domain, what synchronizes CPU caches for the given region | |
65 | (usually it means that the cache has been flushed or invalidated | |
66 | depending on the dma direction). However, next calls to | |
67 | dma_map_{single,page,sg}() for other devices will perform exactly the | |
bf038227 | 68 | same synchronization operation on the CPU cache. CPU cache synchronization |
bdf5e487 MS |
69 | might be a time consuming operation, especially if the buffers are |
70 | large, so it is highly recommended to avoid it if possible. | |
71 | DMA_ATTR_SKIP_CPU_SYNC allows platform code to skip synchronization of | |
72 | the CPU cache for the given buffer assuming that it has been already | |
73 | transferred to 'device' domain. This attribute can be also used for | |
74 | dma_unmap_{single,page,sg} functions family to force buffer to stay in | |
75 | device domain after releasing a mapping for it. Use this attribute with | |
76 | care! | |
4b9347dc MS |
77 | |
78 | DMA_ATTR_FORCE_CONTIGUOUS | |
79 | ------------------------- | |
80 | ||
81 | By default DMA-mapping subsystem is allowed to assemble the buffer | |
82 | allocated by dma_alloc_attrs() function from individual pages if it can | |
83 | be mapped as contiguous chunk into device dma address space. By | |
c98be0c9 | 84 | specifying this attribute the allocated buffer is forced to be contiguous |
4b9347dc | 85 | also in physical memory. |
df05c6f6 DA |
86 | |
87 | DMA_ATTR_ALLOC_SINGLE_PAGES | |
88 | --------------------------- | |
89 | ||
90 | This is a hint to the DMA-mapping subsystem that it's probably not worth | |
91 | the time to try to allocate memory to in a way that gives better TLB | |
92 | efficiency (AKA it's not worth trying to build the mapping out of larger | |
93 | pages). You might want to specify this if: | |
36c682f6 | 94 | |
df05c6f6 DA |
95 | - You know that the accesses to this memory won't thrash the TLB. |
96 | You might know that the accesses are likely to be sequential or | |
97 | that they aren't sequential but it's unlikely you'll ping-pong | |
98 | between many addresses that are likely to be in different physical | |
99 | pages. | |
100 | - You know that the penalty of TLB misses while accessing the | |
101 | memory will be small enough to be inconsequential. If you are | |
102 | doing a heavy operation like decryption or decompression this | |
103 | might be the case. | |
104 | - You know that the DMA mapping is fairly transitory. If you expect | |
105 | the mapping to have a short lifetime then it may be worth it to | |
106 | optimize allocation (avoid coming up with large pages) instead of | |
107 | getting the slight performance win of larger pages. | |
36c682f6 | 108 | |
df05c6f6 DA |
109 | Setting this hint doesn't guarantee that you won't get huge pages, but it |
110 | means that we won't try quite as hard to get them. | |
111 | ||
36c682f6 MCC |
112 | .. note:: At the moment DMA_ATTR_ALLOC_SINGLE_PAGES is only implemented on ARM, |
113 | though ARM64 patches will likely be posted soon. | |
a9a62c93 MFO |
114 | |
115 | DMA_ATTR_NO_WARN | |
116 | ---------------- | |
117 | ||
118 | This tells the DMA-mapping subsystem to suppress allocation failure reports | |
119 | (similarly to __GFP_NOWARN). | |
120 | ||
121 | On some architectures allocation failures are reported with error messages | |
122 | to the system logs. Although this can help to identify and debug problems, | |
123 | drivers which handle failures (eg, retry later) have no problems with them, | |
124 | and can actually flood the system logs with error messages that aren't any | |
125 | problem at all, depending on the implementation of the retry mechanism. | |
126 | ||
127 | So, this provides a way for drivers to avoid those error messages on calls | |
128 | where allocation failures are not a problem, and shouldn't bother the logs. | |
129 | ||
36c682f6 | 130 | .. note:: At the moment DMA_ATTR_NO_WARN is only implemented on PowerPC. |
b2fb3664 MH |
131 | |
132 | DMA_ATTR_PRIVILEGED | |
36c682f6 | 133 | ------------------- |
b2fb3664 MH |
134 | |
135 | Some advanced peripherals such as remote processors and GPUs perform | |
136 | accesses to DMA buffers in both privileged "supervisor" and unprivileged | |
137 | "user" modes. This attribute is used to indicate to the DMA-mapping | |
138 | subsystem that the buffer is fully accessible at the elevated privilege | |
139 | level (and ideally inaccessible or at least read-only at the | |
140 | lesser-privileged levels). | |
487570d3 HP |
141 | |
142 | DMA_ATTR_PRIVILEGED | |
143 | ------------------- | |
144 | ||
145 | Some advanced peripherals such as remote processors and GPUs perform | |
146 | accesses to DMA buffers in both privileged "supervisor" and unprivileged | |
147 | "user" modes. This attribute is used to indicate to the DMA-mapping | |
148 | subsystem that the buffer is fully accessible at the elevated privilege | |
149 | level (and ideally inaccessible or at least read-only at the | |
150 | lesser-privileged levels). |