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 36struct device; 37struct dma_buf; 38struct 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 object 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 */ 74struct 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 *, enum dma_data_direction); 97 int (*end_cpu_access)(struct dma_buf *, enum dma_data_direction); 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 *); 102 103 int (*mmap)(struct dma_buf *, struct vm_area_struct *vma); 104 105 void *(*vmap)(struct dma_buf *); 106 void (*vunmap)(struct dma_buf *, void *vaddr); 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. 115 * @exp_name: name of the exporter; useful for debugging. 116 * @owner: pointer to exporter module; used for refcounting when exporter is a 117 * kernel module. 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 */ 122struct 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 module *owner; 133 struct list_head list_node; 134 void *priv; 135 struct reservation_object *resv; 136 137 /* poll support */ 138 wait_queue_head_t poll; 139 140 struct dma_buf_poll_cb_t { 141 struct fence_cb cb; 142 wait_queue_head_t *poll; 143 144 unsigned long active; 145 } cb_excl, cb_shared; 146}; 147 148/** 149 * struct dma_buf_attachment - holds device-buffer attachment data 150 * @dmabuf: buffer for this attachment. 151 * @dev: device attached to the buffer. 152 * @node: list of dma_buf_attachment. 153 * @priv: exporter specific attachment data. 154 * 155 * This structure holds the attachment information between the dma_buf buffer 156 * and its user device(s). The list contains one attachment struct per device 157 * attached to the buffer. 158 */ 159struct dma_buf_attachment { 160 struct dma_buf *dmabuf; 161 struct device *dev; 162 struct list_head node; 163 void *priv; 164}; 165 166/** 167 * struct dma_buf_export_info - holds information needed to export a dma_buf 168 * @exp_name: name of the exporter - useful for debugging. 169 * @owner: pointer to exporter module - used for refcounting kernel module 170 * @ops: Attach allocator-defined dma buf ops to the new buffer 171 * @size: Size of the buffer 172 * @flags: mode flags for the file 173 * @resv: reservation-object, NULL to allocate default one 174 * @priv: Attach private data of allocator to this buffer 175 * 176 * This structure holds the information required to export the buffer. Used 177 * with dma_buf_export() only. 178 */ 179struct dma_buf_export_info { 180 const char *exp_name; 181 struct module *owner; 182 const struct dma_buf_ops *ops; 183 size_t size; 184 int flags; 185 struct reservation_object *resv; 186 void *priv; 187}; 188 189/** 190 * helper macro for exporters; zeros and fills in most common values 191 */ 192#define DEFINE_DMA_BUF_EXPORT_INFO(a) \ 193 struct dma_buf_export_info a = { .exp_name = KBUILD_MODNAME, \ 194 .owner = THIS_MODULE } 195 196/** 197 * get_dma_buf - convenience wrapper for get_file. 198 * @dmabuf: [in] pointer to dma_buf 199 * 200 * Increments the reference count on the dma-buf, needed in case of drivers 201 * that either need to create additional references to the dmabuf on the 202 * kernel side. For example, an exporter that needs to keep a dmabuf ptr 203 * so that subsequent exports don't create a new dmabuf. 204 */ 205static inline void get_dma_buf(struct dma_buf *dmabuf) 206{ 207 get_file(dmabuf->file); 208} 209 210struct dma_buf_attachment *dma_buf_attach(struct dma_buf *dmabuf, 211 struct device *dev); 212void dma_buf_detach(struct dma_buf *dmabuf, 213 struct dma_buf_attachment *dmabuf_attach); 214 215struct dma_buf *dma_buf_export(const struct dma_buf_export_info *exp_info); 216 217int dma_buf_fd(struct dma_buf *dmabuf, int flags); 218struct dma_buf *dma_buf_get(int fd); 219void dma_buf_put(struct dma_buf *dmabuf); 220 221struct sg_table *dma_buf_map_attachment(struct dma_buf_attachment *, 222 enum dma_data_direction); 223void dma_buf_unmap_attachment(struct dma_buf_attachment *, struct sg_table *, 224 enum dma_data_direction); 225int dma_buf_begin_cpu_access(struct dma_buf *dma_buf, 226 enum dma_data_direction dir); 227int dma_buf_end_cpu_access(struct dma_buf *dma_buf, 228 enum dma_data_direction dir); 229void *dma_buf_kmap_atomic(struct dma_buf *, unsigned long); 230void dma_buf_kunmap_atomic(struct dma_buf *, unsigned long, void *); 231void *dma_buf_kmap(struct dma_buf *, unsigned long); 232void dma_buf_kunmap(struct dma_buf *, unsigned long, void *); 233 234int dma_buf_mmap(struct dma_buf *, struct vm_area_struct *, 235 unsigned long); 236void *dma_buf_vmap(struct dma_buf *); 237void dma_buf_vunmap(struct dma_buf *, void *vaddr); 238int dma_buf_debugfs_create_file(const char *name, 239 int (*write)(struct seq_file *)); 240#endif /* __DMA_BUF_H__ */ 241