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