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> 29 #include <linux/scatterlist.h> 30 #include <linux/list.h> 31 #include <linux/dma-mapping.h> 32 #include <linux/fs.h> 33 #include <linux/fence.h> 34 #include <linux/wait.h> 35 36 struct device; 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. 55 * @begin_cpu_access: [optional] called before cpu access to invalidate cpu 56 * caches and allocate backing storage (if not yet done) 57 * respectively pin the objet into memory. 58 * @end_cpu_access: [optional] called after cpu access to flush caches. 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. 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. 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 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 *, 87 struct sg_table *, 88 enum dma_data_direction); 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 96 int (*begin_cpu_access)(struct dma_buf *, size_t, size_t, 97 enum dma_data_direction); 98 void (*end_cpu_access)(struct dma_buf *, size_t, size_t, 99 enum dma_data_direction); 100 void *(*kmap_atomic)(struct dma_buf *, unsigned long); 101 void (*kunmap_atomic)(struct dma_buf *, unsigned long, void *); 102 void *(*kmap)(struct dma_buf *, unsigned long); 103 void (*kunmap)(struct dma_buf *, unsigned long, void *); 104 105 int (*mmap)(struct dma_buf *, struct vm_area_struct *vma); 106 107 void *(*vmap)(struct dma_buf *); 108 void (*vunmap)(struct dma_buf *, void *vaddr); 109 }; 110 111 /** 112 * struct dma_buf - shared buffer object 113 * @size: size of the buffer 114 * @file: file pointer used for sharing buffers across, and for refcounting. 115 * @attachments: list of dma_buf_attachment that denotes all devices attached. 116 * @ops: dma_buf_ops associated with this buffer object. 117 * @exp_name: name of the exporter; useful for debugging. 118 * @owner: pointer to exporter module; used for refcounting when exporter is a 119 * kernel module. 120 * @list_node: node for dma_buf accounting and debugging. 121 * @priv: exporter specific private data for this buffer object. 122 * @resv: reservation object linked to this dma-buf 123 */ 124 struct dma_buf { 125 size_t size; 126 struct file *file; 127 struct list_head attachments; 128 const struct dma_buf_ops *ops; 129 /* mutex to serialize list manipulation, attach/detach and vmap/unmap */ 130 struct mutex lock; 131 unsigned vmapping_counter; 132 void *vmap_ptr; 133 const char *exp_name; 134 struct module *owner; 135 struct list_head list_node; 136 void *priv; 137 struct reservation_object *resv; 138 139 /* poll support */ 140 wait_queue_head_t poll; 141 142 struct dma_buf_poll_cb_t { 143 struct fence_cb cb; 144 wait_queue_head_t *poll; 145 146 unsigned long active; 147 } cb_excl, cb_shared; 148 }; 149 150 /** 151 * struct dma_buf_attachment - holds device-buffer attachment data 152 * @dmabuf: buffer for this attachment. 153 * @dev: device attached to the buffer. 154 * @node: list of dma_buf_attachment. 155 * @priv: exporter specific attachment data. 156 * 157 * This structure holds the attachment information between the dma_buf buffer 158 * and its user device(s). The list contains one attachment struct per device 159 * attached to the buffer. 160 */ 161 struct dma_buf_attachment { 162 struct dma_buf *dmabuf; 163 struct device *dev; 164 struct list_head node; 165 void *priv; 166 }; 167 168 /** 169 * struct dma_buf_export_info - holds information needed to export a dma_buf 170 * @exp_name: name of the exporter - useful for debugging. 171 * @owner: pointer to exporter module - used for refcounting kernel module 172 * @ops: Attach allocator-defined dma buf ops to the new buffer 173 * @size: Size of the buffer 174 * @flags: mode flags for the file 175 * @resv: reservation-object, NULL to allocate default one 176 * @priv: Attach private data of allocator to this buffer 177 * 178 * This structure holds the information required to export the buffer. Used 179 * with dma_buf_export() only. 180 */ 181 struct dma_buf_export_info { 182 const char *exp_name; 183 struct module *owner; 184 const struct dma_buf_ops *ops; 185 size_t size; 186 int flags; 187 struct reservation_object *resv; 188 void *priv; 189 }; 190 191 /** 192 * helper macro for exporters; zeros and fills in most common values 193 */ 194 #define DEFINE_DMA_BUF_EXPORT_INFO(a) \ 195 struct dma_buf_export_info a = { .exp_name = KBUILD_MODNAME, \ 196 .owner = THIS_MODULE } 197 198 /** 199 * get_dma_buf - convenience wrapper for get_file. 200 * @dmabuf: [in] pointer to dma_buf 201 * 202 * Increments the reference count on the dma-buf, needed in case of drivers 203 * that either need to create additional references to the dmabuf on the 204 * kernel side. For example, an exporter that needs to keep a dmabuf ptr 205 * so that subsequent exports don't create a new dmabuf. 206 */ 207 static inline void get_dma_buf(struct dma_buf *dmabuf) 208 { 209 get_file(dmabuf->file); 210 } 211 212 struct dma_buf_attachment *dma_buf_attach(struct dma_buf *dmabuf, 213 struct device *dev); 214 void dma_buf_detach(struct dma_buf *dmabuf, 215 struct dma_buf_attachment *dmabuf_attach); 216 217 struct dma_buf *dma_buf_export(const struct dma_buf_export_info *exp_info); 218 219 int dma_buf_fd(struct dma_buf *dmabuf, int flags); 220 struct dma_buf *dma_buf_get(int fd); 221 void dma_buf_put(struct dma_buf *dmabuf); 222 223 struct sg_table *dma_buf_map_attachment(struct dma_buf_attachment *, 224 enum dma_data_direction); 225 void dma_buf_unmap_attachment(struct dma_buf_attachment *, struct sg_table *, 226 enum dma_data_direction); 227 int dma_buf_begin_cpu_access(struct dma_buf *dma_buf, size_t start, size_t len, 228 enum dma_data_direction dir); 229 void dma_buf_end_cpu_access(struct dma_buf *dma_buf, size_t start, size_t len, 230 enum dma_data_direction dir); 231 void *dma_buf_kmap_atomic(struct dma_buf *, unsigned long); 232 void dma_buf_kunmap_atomic(struct dma_buf *, unsigned long, void *); 233 void *dma_buf_kmap(struct dma_buf *, unsigned long); 234 void dma_buf_kunmap(struct dma_buf *, unsigned long, void *); 235 236 int dma_buf_mmap(struct dma_buf *, struct vm_area_struct *, 237 unsigned long); 238 void *dma_buf_vmap(struct dma_buf *); 239 void dma_buf_vunmap(struct dma_buf *, void *vaddr); 240 int dma_buf_debugfs_create_file(const char *name, 241 int (*write)(struct seq_file *)); 242 #endif /* __DMA_BUF_H__ */ 243