]>
Commit | Line | Data |
---|---|---|
d15bd7ee SS |
1 | /* |
2 | * Header file for dma buffer sharing framework. | |
3 | * | |
4 | * Copyright(C) 2011 Linaro Limited. All rights reserved. | |
5 | * Author: Sumit Semwal <sumit.semwal@ti.com> | |
6 | * | |
7 | * Many thanks to linaro-mm-sig list, and specially | |
8 | * Arnd Bergmann <arnd@arndb.de>, Rob Clark <rob@ti.com> and | |
9 | * Daniel Vetter <daniel@ffwll.ch> for their support in creation and | |
10 | * refining of this idea. | |
11 | * | |
12 | * This program is free software; you can redistribute it and/or modify it | |
13 | * under the terms of the GNU General Public License version 2 as published by | |
14 | * the Free Software Foundation. | |
15 | * | |
16 | * This program is distributed in the hope that it will be useful, but WITHOUT | |
17 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
18 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for | |
19 | * more details. | |
20 | * | |
21 | * You should have received a copy of the GNU General Public License along with | |
22 | * this program. If not, see <http://www.gnu.org/licenses/>. | |
23 | */ | |
24 | #ifndef __DMA_BUF_H__ | |
25 | #define __DMA_BUF_H__ | |
26 | ||
27 | #include <linux/file.h> | |
28 | #include <linux/err.h> | |
d15bd7ee SS |
29 | #include <linux/scatterlist.h> |
30 | #include <linux/list.h> | |
31 | #include <linux/dma-mapping.h> | |
f9a24d1a | 32 | #include <linux/fs.h> |
f54d1867 | 33 | #include <linux/dma-fence.h> |
9b495a58 | 34 | #include <linux/wait.h> |
d15bd7ee | 35 | |
313162d0 | 36 | struct device; |
d15bd7ee SS |
37 | struct dma_buf; |
38 | struct dma_buf_attachment; | |
39 | ||
40 | /** | |
41 | * struct dma_buf_ops - operations possible on struct dma_buf | |
42 | * @attach: [optional] allows different devices to 'attach' themselves to the | |
43 | * given buffer. It might return -EBUSY to signal that backing storage | |
44 | * is already allocated and incompatible with the requirements | |
45 | * of requesting device. | |
46 | * @detach: [optional] detach a given device from this buffer. | |
47 | * @map_dma_buf: returns list of scatter pages allocated, increases usecount | |
48 | * of the buffer. Requires atleast one attach to be called | |
49 | * before. Returned sg list should already be mapped into | |
50 | * _device_ address space. This call may sleep. May also return | |
51 | * -EINTR. Should return -EINVAL if attach hasn't been called yet. | |
52 | * @unmap_dma_buf: decreases usecount of buffer, might deallocate scatter | |
53 | * pages. | |
54 | * @release: release this buffer; to be called after the last dma_buf_put. | |
fc13020e DV |
55 | * @begin_cpu_access: [optional] called before cpu access to invalidate cpu |
56 | * caches and allocate backing storage (if not yet done) | |
831e9da7 | 57 | * respectively pin the object into memory. |
8a168ca7 | 58 | * @end_cpu_access: [optional] called after cpu access to flush caches. |
fc13020e DV |
59 | * @kmap_atomic: maps a page from the buffer into kernel address |
60 | * space, users may not block until the subsequent unmap call. | |
61 | * This callback must not sleep. | |
62 | * @kunmap_atomic: [optional] unmaps a atomically mapped page from the buffer. | |
63 | * This Callback must not sleep. | |
64 | * @kmap: maps a page from the buffer into kernel address space. | |
65 | * @kunmap: [optional] unmaps a page from the buffer. | |
4c78513e DV |
66 | * @mmap: used to expose the backing storage to userspace. Note that the |
67 | * mapping needs to be coherent - if the exporter doesn't directly | |
68 | * support this, it needs to fake coherency by shooting down any ptes | |
69 | * when transitioning away from the cpu domain. | |
12c4727e SS |
70 | * @vmap: [optional] creates a virtual mapping for the buffer into kernel |
71 | * address space. Same restrictions as for vmap and friends apply. | |
72 | * @vunmap: [optional] unmaps a vmap from the buffer | |
d15bd7ee SS |
73 | */ |
74 | struct dma_buf_ops { | |
75 | int (*attach)(struct dma_buf *, struct device *, | |
76 | struct dma_buf_attachment *); | |
77 | ||
78 | void (*detach)(struct dma_buf *, struct dma_buf_attachment *); | |
79 | ||
80 | /* For {map,unmap}_dma_buf below, any specific buffer attributes | |
81 | * required should get added to device_dma_parameters accessible | |
82 | * via dev->dma_params. | |
83 | */ | |
84 | struct sg_table * (*map_dma_buf)(struct dma_buf_attachment *, | |
85 | enum dma_data_direction); | |
86 | void (*unmap_dma_buf)(struct dma_buf_attachment *, | |
33ea2dcb SS |
87 | struct sg_table *, |
88 | enum dma_data_direction); | |
d15bd7ee SS |
89 | /* TODO: Add try_map_dma_buf version, to return immed with -EBUSY |
90 | * if the call would block. | |
91 | */ | |
92 | ||
93 | /* after final dma_buf_put() */ | |
94 | void (*release)(struct dma_buf *); | |
95 | ||
831e9da7 | 96 | int (*begin_cpu_access)(struct dma_buf *, enum dma_data_direction); |
18b862dc | 97 | int (*end_cpu_access)(struct dma_buf *, enum dma_data_direction); |
fc13020e DV |
98 | void *(*kmap_atomic)(struct dma_buf *, unsigned long); |
99 | void (*kunmap_atomic)(struct dma_buf *, unsigned long, void *); | |
100 | void *(*kmap)(struct dma_buf *, unsigned long); | |
101 | void (*kunmap)(struct dma_buf *, unsigned long, void *); | |
4c78513e DV |
102 | |
103 | int (*mmap)(struct dma_buf *, struct vm_area_struct *vma); | |
98f86c9e DA |
104 | |
105 | void *(*vmap)(struct dma_buf *); | |
106 | void (*vunmap)(struct dma_buf *, void *vaddr); | |
d15bd7ee SS |
107 | }; |
108 | ||
109 | /** | |
110 | * struct dma_buf - shared buffer object | |
111 | * @size: size of the buffer | |
112 | * @file: file pointer used for sharing buffers across, and for refcounting. | |
113 | * @attachments: list of dma_buf_attachment that denotes all devices attached. | |
114 | * @ops: dma_buf_ops associated with this buffer object. | |
e2082e3a RC |
115 | * @lock: used internally to serialize list manipulation, attach/detach and vmap/unmap |
116 | * @vmapping_counter: used internally to refcnt the vmaps | |
117 | * @vmap_ptr: the current vmap ptr if vmapping_counter > 0 | |
78df9695 | 118 | * @exp_name: name of the exporter; useful for debugging. |
9abdffe2 SS |
119 | * @owner: pointer to exporter module; used for refcounting when exporter is a |
120 | * kernel module. | |
b89e3563 | 121 | * @list_node: node for dma_buf accounting and debugging. |
d15bd7ee | 122 | * @priv: exporter specific private data for this buffer object. |
3aac4502 | 123 | * @resv: reservation object linked to this dma-buf |
e2082e3a RC |
124 | * @poll: for userspace poll support |
125 | * @cb_excl: for userspace poll support | |
126 | * @cb_shared: for userspace poll support | |
d15bd7ee SS |
127 | */ |
128 | struct dma_buf { | |
129 | size_t size; | |
130 | struct file *file; | |
131 | struct list_head attachments; | |
132 | const struct dma_buf_ops *ops; | |
d15bd7ee | 133 | struct mutex lock; |
f00b4dad DV |
134 | unsigned vmapping_counter; |
135 | void *vmap_ptr; | |
78df9695 | 136 | const char *exp_name; |
9abdffe2 | 137 | struct module *owner; |
b89e3563 | 138 | struct list_head list_node; |
d15bd7ee | 139 | void *priv; |
3aac4502 | 140 | struct reservation_object *resv; |
9b495a58 ML |
141 | |
142 | /* poll support */ | |
143 | wait_queue_head_t poll; | |
144 | ||
145 | struct dma_buf_poll_cb_t { | |
f54d1867 | 146 | struct dma_fence_cb cb; |
9b495a58 ML |
147 | wait_queue_head_t *poll; |
148 | ||
149 | unsigned long active; | |
150 | } cb_excl, cb_shared; | |
d15bd7ee SS |
151 | }; |
152 | ||
153 | /** | |
154 | * struct dma_buf_attachment - holds device-buffer attachment data | |
155 | * @dmabuf: buffer for this attachment. | |
156 | * @dev: device attached to the buffer. | |
157 | * @node: list of dma_buf_attachment. | |
158 | * @priv: exporter specific attachment data. | |
159 | * | |
160 | * This structure holds the attachment information between the dma_buf buffer | |
161 | * and its user device(s). The list contains one attachment struct per device | |
162 | * attached to the buffer. | |
163 | */ | |
164 | struct dma_buf_attachment { | |
165 | struct dma_buf *dmabuf; | |
166 | struct device *dev; | |
167 | struct list_head node; | |
168 | void *priv; | |
169 | }; | |
170 | ||
d8fbe341 SS |
171 | /** |
172 | * struct dma_buf_export_info - holds information needed to export a dma_buf | |
9abdffe2 SS |
173 | * @exp_name: name of the exporter - useful for debugging. |
174 | * @owner: pointer to exporter module - used for refcounting kernel module | |
d8fbe341 SS |
175 | * @ops: Attach allocator-defined dma buf ops to the new buffer |
176 | * @size: Size of the buffer | |
177 | * @flags: mode flags for the file | |
178 | * @resv: reservation-object, NULL to allocate default one | |
179 | * @priv: Attach private data of allocator to this buffer | |
180 | * | |
181 | * This structure holds the information required to export the buffer. Used | |
182 | * with dma_buf_export() only. | |
183 | */ | |
184 | struct dma_buf_export_info { | |
185 | const char *exp_name; | |
9abdffe2 | 186 | struct module *owner; |
d8fbe341 SS |
187 | const struct dma_buf_ops *ops; |
188 | size_t size; | |
189 | int flags; | |
190 | struct reservation_object *resv; | |
191 | void *priv; | |
192 | }; | |
193 | ||
194 | /** | |
195 | * helper macro for exporters; zeros and fills in most common values | |
e2082e3a RC |
196 | * |
197 | * @name: export-info name | |
d8fbe341 | 198 | */ |
e2082e3a RC |
199 | #define DEFINE_DMA_BUF_EXPORT_INFO(name) \ |
200 | struct dma_buf_export_info name = { .exp_name = KBUILD_MODNAME, \ | |
9abdffe2 | 201 | .owner = THIS_MODULE } |
d8fbe341 | 202 | |
f9a24d1a RC |
203 | /** |
204 | * get_dma_buf - convenience wrapper for get_file. | |
205 | * @dmabuf: [in] pointer to dma_buf | |
206 | * | |
207 | * Increments the reference count on the dma-buf, needed in case of drivers | |
208 | * that either need to create additional references to the dmabuf on the | |
209 | * kernel side. For example, an exporter that needs to keep a dmabuf ptr | |
210 | * so that subsequent exports don't create a new dmabuf. | |
211 | */ | |
212 | static inline void get_dma_buf(struct dma_buf *dmabuf) | |
213 | { | |
214 | get_file(dmabuf->file); | |
215 | } | |
216 | ||
d15bd7ee SS |
217 | struct dma_buf_attachment *dma_buf_attach(struct dma_buf *dmabuf, |
218 | struct device *dev); | |
219 | void dma_buf_detach(struct dma_buf *dmabuf, | |
220 | struct dma_buf_attachment *dmabuf_attach); | |
78df9695 | 221 | |
d8fbe341 | 222 | struct dma_buf *dma_buf_export(const struct dma_buf_export_info *exp_info); |
78df9695 | 223 | |
55c1c4ca | 224 | int dma_buf_fd(struct dma_buf *dmabuf, int flags); |
d15bd7ee SS |
225 | struct dma_buf *dma_buf_get(int fd); |
226 | void dma_buf_put(struct dma_buf *dmabuf); | |
227 | ||
228 | struct sg_table *dma_buf_map_attachment(struct dma_buf_attachment *, | |
229 | enum dma_data_direction); | |
33ea2dcb SS |
230 | void dma_buf_unmap_attachment(struct dma_buf_attachment *, struct sg_table *, |
231 | enum dma_data_direction); | |
831e9da7 | 232 | int dma_buf_begin_cpu_access(struct dma_buf *dma_buf, |
fc13020e | 233 | enum dma_data_direction dir); |
18b862dc CW |
234 | int dma_buf_end_cpu_access(struct dma_buf *dma_buf, |
235 | enum dma_data_direction dir); | |
fc13020e DV |
236 | void *dma_buf_kmap_atomic(struct dma_buf *, unsigned long); |
237 | void dma_buf_kunmap_atomic(struct dma_buf *, unsigned long, void *); | |
238 | void *dma_buf_kmap(struct dma_buf *, unsigned long); | |
239 | void dma_buf_kunmap(struct dma_buf *, unsigned long, void *); | |
4c78513e DV |
240 | |
241 | int dma_buf_mmap(struct dma_buf *, struct vm_area_struct *, | |
242 | unsigned long); | |
98f86c9e DA |
243 | void *dma_buf_vmap(struct dma_buf *); |
244 | void dma_buf_vunmap(struct dma_buf *, void *vaddr); | |
d15bd7ee | 245 | #endif /* __DMA_BUF_H__ */ |