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