ion.h revision 56a7c1851341a2fa9bd115746c1310411a6537a1
1/* 2 * drivers/staging/android/ion/ion.h 3 * 4 * Copyright (C) 2011 Google, Inc. 5 * 6 * This software is licensed under the terms of the GNU General Public 7 * License version 2, as published by the Free Software Foundation, and 8 * may be copied, distributed, and modified under those terms. 9 * 10 * This program is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU General Public License for more details. 14 * 15 */ 16 17#ifndef _LINUX_ION_H 18#define _LINUX_ION_H 19 20#include <linux/types.h> 21 22struct ion_handle; 23/** 24 * enum ion_heap_types - list of all possible types of heaps 25 * @ION_HEAP_TYPE_SYSTEM: memory allocated via vmalloc 26 * @ION_HEAP_TYPE_SYSTEM_CONTIG: memory allocated via kmalloc 27 * @ION_HEAP_TYPE_CARVEOUT: memory allocated from a prereserved 28 * carveout heap, allocations are physically 29 * contiguous 30 * @ION_HEAP_END: helper for iterating over heaps 31 */ 32enum ion_heap_type { 33 ION_HEAP_TYPE_SYSTEM, 34 ION_HEAP_TYPE_SYSTEM_CONTIG, 35 ION_HEAP_TYPE_CARVEOUT, 36 ION_HEAP_TYPE_CUSTOM, /* must be last so device specific heaps always 37 are at the end of this enum */ 38 ION_NUM_HEAPS, 39}; 40 41#define ION_HEAP_SYSTEM_MASK (1 << ION_HEAP_TYPE_SYSTEM) 42#define ION_HEAP_SYSTEM_CONTIG_MASK (1 << ION_HEAP_TYPE_SYSTEM_CONTIG) 43#define ION_HEAP_CARVEOUT_MASK (1 << ION_HEAP_TYPE_CARVEOUT) 44 45/** 46 * heap flags - the lower 16 bits are used by core ion, the upper 16 47 * bits are reserved for use by the heaps themselves. 48 */ 49#define ION_FLAG_CACHED 1 /* mappings of this buffer should be 50 cached, ion will do cache 51 maintenance when the buffer is 52 mapped for dma */ 53 54#ifdef __KERNEL__ 55struct ion_device; 56struct ion_heap; 57struct ion_mapper; 58struct ion_client; 59struct ion_buffer; 60 61/* This should be removed some day when phys_addr_t's are fully 62 plumbed in the kernel, and all instances of ion_phys_addr_t should 63 be converted to phys_addr_t. For the time being many kernel interfaces 64 do not accept phys_addr_t's that would have to */ 65#define ion_phys_addr_t unsigned long 66 67/** 68 * struct ion_platform_heap - defines a heap in the given platform 69 * @type: type of the heap from ion_heap_type enum 70 * @id: unique identifier for heap. When allocating (lower numbers 71 * will be allocated from first) 72 * @name: used for debug purposes 73 * @base: base address of heap in physical memory if applicable 74 * @size: size of the heap in bytes if applicable 75 * 76 * Provided by the board file. 77 */ 78struct ion_platform_heap { 79 enum ion_heap_type type; 80 unsigned int id; 81 const char *name; 82 ion_phys_addr_t base; 83 size_t size; 84}; 85 86/** 87 * struct ion_platform_data - array of platform heaps passed from board file 88 * @nr: number of structures in the array 89 * @heaps: array of platform_heap structions 90 * 91 * Provided by the board file in the form of platform data to a platform device. 92 */ 93struct ion_platform_data { 94 int nr; 95 struct ion_platform_heap heaps[]; 96}; 97 98/** 99 * ion_reserve() - reserve memory for ion heaps if applicable 100 * @data: platform data specifying starting physical address and 101 * size 102 * 103 * Calls memblock reserve to set aside memory for heaps that are 104 * located at specific memory addresses or of specfic sizes not 105 * managed by the kernel 106 */ 107void ion_reserve(struct ion_platform_data *data); 108 109/** 110 * ion_client_create() - allocate a client and returns it 111 * @dev: the global ion device 112 * @heap_mask: mask of heaps this client can allocate from 113 * @name: used for debugging 114 */ 115struct ion_client *ion_client_create(struct ion_device *dev, 116 unsigned int heap_mask, const char *name); 117 118/** 119 * ion_client_destroy() - free's a client and all it's handles 120 * @client: the client 121 * 122 * Free the provided client and all it's resources including 123 * any handles it is holding. 124 */ 125void ion_client_destroy(struct ion_client *client); 126 127/** 128 * ion_alloc - allocate ion memory 129 * @client: the client 130 * @len: size of the allocation 131 * @align: requested allocation alignment, lots of hardware blocks have 132 * alignment requirements of some kind 133 * @heap_mask: mask of heaps to allocate from, if multiple bits are set 134 * heaps will be tried in order from lowest to highest order bit 135 * @flags: heap flags, the low 16 bits are consumed by ion, the high 16 136 * bits are passed on to the respective heap and can be heap 137 * custom 138 * 139 * Allocate memory in one of the heaps provided in heap mask and return 140 * an opaque handle to it. 141 */ 142struct ion_handle *ion_alloc(struct ion_client *client, size_t len, 143 size_t align, unsigned int heap_mask, 144 unsigned int flags); 145 146/** 147 * ion_free - free a handle 148 * @client: the client 149 * @handle: the handle to free 150 * 151 * Free the provided handle. 152 */ 153void ion_free(struct ion_client *client, struct ion_handle *handle); 154 155/** 156 * ion_phys - returns the physical address and len of a handle 157 * @client: the client 158 * @handle: the handle 159 * @addr: a pointer to put the address in 160 * @len: a pointer to put the length in 161 * 162 * This function queries the heap for a particular handle to get the 163 * handle's physical address. It't output is only correct if 164 * a heap returns physically contiguous memory -- in other cases 165 * this api should not be implemented -- ion_sg_table should be used 166 * instead. Returns -EINVAL if the handle is invalid. This has 167 * no implications on the reference counting of the handle -- 168 * the returned value may not be valid if the caller is not 169 * holding a reference. 170 */ 171int ion_phys(struct ion_client *client, struct ion_handle *handle, 172 ion_phys_addr_t *addr, size_t *len); 173 174/** 175 * ion_map_dma - return an sg_table describing a handle 176 * @client: the client 177 * @handle: the handle 178 * 179 * This function returns the sg_table describing 180 * a particular ion handle. 181 */ 182struct sg_table *ion_sg_table(struct ion_client *client, 183 struct ion_handle *handle); 184 185/** 186 * ion_map_kernel - create mapping for the given handle 187 * @client: the client 188 * @handle: handle to map 189 * 190 * Map the given handle into the kernel and return a kernel address that 191 * can be used to access this address. 192 */ 193void *ion_map_kernel(struct ion_client *client, struct ion_handle *handle); 194 195/** 196 * ion_unmap_kernel() - destroy a kernel mapping for a handle 197 * @client: the client 198 * @handle: handle to unmap 199 */ 200void ion_unmap_kernel(struct ion_client *client, struct ion_handle *handle); 201 202/** 203 * ion_share_dma_buf() - given an ion client, create a dma-buf fd 204 * @client: the client 205 * @handle: the handle 206 */ 207int ion_share_dma_buf(struct ion_client *client, struct ion_handle *handle); 208 209/** 210 * ion_import_dma_buf() - given an dma-buf fd from the ion exporter get handle 211 * @client: the client 212 * @fd: the dma-buf fd 213 * 214 * Given an dma-buf fd that was allocated through ion via ion_share_dma_buf, 215 * import that fd and return a handle representing it. If a dma-buf from 216 * another exporter is passed in this function will return ERR_PTR(-EINVAL) 217 */ 218struct ion_handle *ion_import_dma_buf(struct ion_client *client, int fd); 219 220#endif /* __KERNEL__ */ 221 222/** 223 * DOC: Ion Userspace API 224 * 225 * create a client by opening /dev/ion 226 * most operations handled via following ioctls 227 * 228 */ 229 230/** 231 * struct ion_allocation_data - metadata passed from userspace for allocations 232 * @len: size of the allocation 233 * @align: required alignment of the allocation 234 * @heap_mask: mask of heaps to allocate from 235 * @flags: flags passed to heap 236 * @handle: pointer that will be populated with a cookie to use to refer 237 * to this allocation 238 * 239 * Provided by userspace as an argument to the ioctl 240 */ 241struct ion_allocation_data { 242 size_t len; 243 size_t align; 244 unsigned int heap_mask; 245 unsigned int flags; 246 struct ion_handle *handle; 247}; 248 249/** 250 * struct ion_fd_data - metadata passed to/from userspace for a handle/fd pair 251 * @handle: a handle 252 * @fd: a file descriptor representing that handle 253 * 254 * For ION_IOC_SHARE or ION_IOC_MAP userspace populates the handle field with 255 * the handle returned from ion alloc, and the kernel returns the file 256 * descriptor to share or map in the fd field. For ION_IOC_IMPORT, userspace 257 * provides the file descriptor and the kernel returns the handle. 258 */ 259struct ion_fd_data { 260 struct ion_handle *handle; 261 int fd; 262}; 263 264/** 265 * struct ion_handle_data - a handle passed to/from the kernel 266 * @handle: a handle 267 */ 268struct ion_handle_data { 269 struct ion_handle *handle; 270}; 271 272/** 273 * struct ion_custom_data - metadata passed to/from userspace for a custom ioctl 274 * @cmd: the custom ioctl function to call 275 * @arg: additional data to pass to the custom ioctl, typically a user 276 * pointer to a predefined structure 277 * 278 * This works just like the regular cmd and arg fields of an ioctl. 279 */ 280struct ion_custom_data { 281 unsigned int cmd; 282 unsigned long arg; 283}; 284 285#define ION_IOC_MAGIC 'I' 286 287/** 288 * DOC: ION_IOC_ALLOC - allocate memory 289 * 290 * Takes an ion_allocation_data struct and returns it with the handle field 291 * populated with the opaque handle for the allocation. 292 */ 293#define ION_IOC_ALLOC _IOWR(ION_IOC_MAGIC, 0, \ 294 struct ion_allocation_data) 295 296/** 297 * DOC: ION_IOC_FREE - free memory 298 * 299 * Takes an ion_handle_data struct and frees the handle. 300 */ 301#define ION_IOC_FREE _IOWR(ION_IOC_MAGIC, 1, struct ion_handle_data) 302 303/** 304 * DOC: ION_IOC_MAP - get a file descriptor to mmap 305 * 306 * Takes an ion_fd_data struct with the handle field populated with a valid 307 * opaque handle. Returns the struct with the fd field set to a file 308 * descriptor open in the current address space. This file descriptor 309 * can then be used as an argument to mmap. 310 */ 311#define ION_IOC_MAP _IOWR(ION_IOC_MAGIC, 2, struct ion_fd_data) 312 313/** 314 * DOC: ION_IOC_SHARE - creates a file descriptor to use to share an allocation 315 * 316 * Takes an ion_fd_data struct with the handle field populated with a valid 317 * opaque handle. Returns the struct with the fd field set to a file 318 * descriptor open in the current address space. This file descriptor 319 * can then be passed to another process. The corresponding opaque handle can 320 * be retrieved via ION_IOC_IMPORT. 321 */ 322#define ION_IOC_SHARE _IOWR(ION_IOC_MAGIC, 4, struct ion_fd_data) 323 324/** 325 * DOC: ION_IOC_IMPORT - imports a shared file descriptor 326 * 327 * Takes an ion_fd_data struct with the fd field populated with a valid file 328 * descriptor obtained from ION_IOC_SHARE and returns the struct with the handle 329 * filed set to the corresponding opaque handle. 330 */ 331#define ION_IOC_IMPORT _IOWR(ION_IOC_MAGIC, 5, int) 332 333/** 334 * DOC: ION_IOC_CUSTOM - call architecture specific ion ioctl 335 * 336 * Takes the argument of the architecture specific ioctl to call and 337 * passes appropriate userdata for that ioctl 338 */ 339#define ION_IOC_CUSTOM _IOWR(ION_IOC_MAGIC, 6, struct ion_custom_data) 340 341#endif /* _LINUX_ION_H */ 342