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 * @list_node: node for dma_buf accounting and debugging. 119 * @priv: exporter specific private data for this buffer object. 120 * @resv: reservation object linked to this dma-buf 121 */ 122 struct dma_buf { 123 size_t size; 124 struct file *file; 125 struct list_head attachments; 126 const struct dma_buf_ops *ops; 127 /* mutex to serialize list manipulation, attach/detach and vmap/unmap */ 128 struct mutex lock; 129 unsigned vmapping_counter; 130 void *vmap_ptr; 131 const char *exp_name; 132 struct list_head list_node; 133 void *priv; 134 struct reservation_object *resv; 135 136 /* poll support */ 137 wait_queue_head_t poll; 138 139 struct dma_buf_poll_cb_t { 140 struct fence_cb cb; 141 wait_queue_head_t *poll; 142 143 unsigned long active; 144 } cb_excl, cb_shared; 145 }; 146 147 /** 148 * struct dma_buf_attachment - holds device-buffer attachment data 149 * @dmabuf: buffer for this attachment. 150 * @dev: device attached to the buffer. 151 * @node: list of dma_buf_attachment. 152 * @priv: exporter specific attachment data. 153 * 154 * This structure holds the attachment information between the dma_buf buffer 155 * and its user device(s). The list contains one attachment struct per device 156 * attached to the buffer. 157 */ 158 struct dma_buf_attachment { 159 struct dma_buf *dmabuf; 160 struct device *dev; 161 struct list_head node; 162 void *priv; 163 }; 164 165 /** 166 * get_dma_buf - convenience wrapper for get_file. 167 * @dmabuf: [in] pointer to dma_buf 168 * 169 * Increments the reference count on the dma-buf, needed in case of drivers 170 * that either need to create additional references to the dmabuf on the 171 * kernel side. For example, an exporter that needs to keep a dmabuf ptr 172 * so that subsequent exports don't create a new dmabuf. 173 */ 174 static inline void get_dma_buf(struct dma_buf *dmabuf) 175 { 176 get_file(dmabuf->file); 177 } 178 179 struct dma_buf_attachment *dma_buf_attach(struct dma_buf *dmabuf, 180 struct device *dev); 181 void dma_buf_detach(struct dma_buf *dmabuf, 182 struct dma_buf_attachment *dmabuf_attach); 183 184 struct dma_buf *dma_buf_export_named(void *priv, const struct dma_buf_ops *ops, 185 size_t size, int flags, const char *, 186 struct reservation_object *); 187 188 #define dma_buf_export(priv, ops, size, flags, resv) \ 189 dma_buf_export_named(priv, ops, size, flags, KBUILD_MODNAME, resv) 190 191 int dma_buf_fd(struct dma_buf *dmabuf, int flags); 192 struct dma_buf *dma_buf_get(int fd); 193 void dma_buf_put(struct dma_buf *dmabuf); 194 195 struct sg_table *dma_buf_map_attachment(struct dma_buf_attachment *, 196 enum dma_data_direction); 197 void dma_buf_unmap_attachment(struct dma_buf_attachment *, struct sg_table *, 198 enum dma_data_direction); 199 int dma_buf_begin_cpu_access(struct dma_buf *dma_buf, size_t start, size_t len, 200 enum dma_data_direction dir); 201 void dma_buf_end_cpu_access(struct dma_buf *dma_buf, size_t start, size_t len, 202 enum dma_data_direction dir); 203 void *dma_buf_kmap_atomic(struct dma_buf *, unsigned long); 204 void dma_buf_kunmap_atomic(struct dma_buf *, unsigned long, void *); 205 void *dma_buf_kmap(struct dma_buf *, unsigned long); 206 void dma_buf_kunmap(struct dma_buf *, unsigned long, void *); 207 208 int dma_buf_mmap(struct dma_buf *, struct vm_area_struct *, 209 unsigned long); 210 void *dma_buf_vmap(struct dma_buf *); 211 void dma_buf_vunmap(struct dma_buf *, void *vaddr); 212 int dma_buf_debugfs_create_file(const char *name, 213 int (*write)(struct seq_file *)); 214 #endif /* __DMA_BUF_H__ */ 215