1/* 2 * include/linux/ion.h 3 * 4 * Copyright (C) 2011 Google, Inc. 5 * Copyright (c) 2011-2012, The Linux Foundation. All rights reserved. 6 * 7 * This software is licensed under the terms of the GNU General Public 8 * License version 2, as published by the Free Software Foundation, and 9 * may be copied, distributed, and modified under those terms. 10 * 11 * This program is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 */ 17 18#ifndef _LINUX_ION_H 19#define _LINUX_ION_H 20 21#include <linux/ioctl.h> 22#include <linux/types.h> 23 24struct ion_handle; 25typedef struct ion_handle *ion_user_handle_t; 26/** 27 * enum ion_heap_types - list of all possible types of heaps 28 * @ION_HEAP_TYPE_SYSTEM: memory allocated via vmalloc 29 * @ION_HEAP_TYPE_SYSTEM_CONTIG: memory allocated via kmalloc 30 * @ION_HEAP_TYPE_CARVEOUT: memory allocated from a prereserved 31 * carveout heap, allocations are physically 32 * contiguous 33 * @ION_HEAP_TYPE_IOMMU: IOMMU memory 34 * @ION_HEAP_TYPE_CP: memory allocated from a prereserved 35 * carveout heap, allocations are physically 36 * contiguous. Used for content protection. 37 * @ION_HEAP_TYPE_DMA: memory allocated via DMA API 38 * @ION_NUM_HEAPS: helper for iterating over heaps, a bit mask 39 * is used to identify the heaps, so only 32 40 * total heap types are supported 41 */ 42enum ion_heap_type { 43 ION_HEAP_TYPE_SYSTEM, 44 ION_HEAP_TYPE_SYSTEM_CONTIG, 45 ION_HEAP_TYPE_CARVEOUT, 46 ION_HEAP_TYPE_DMA, 47 ION_HEAP_TYPE_CUSTOM, /* must be last so device specific heaps always 48 are at the end of this enum */ 49 ION_NUM_HEAPS = 16, 50}; 51 52#define ION_HEAP_SYSTEM_MASK (1 << ION_HEAP_TYPE_SYSTEM) 53#define ION_HEAP_SYSTEM_CONTIG_MASK (1 << ION_HEAP_TYPE_SYSTEM_CONTIG) 54#define ION_HEAP_CARVEOUT_MASK (1 << ION_HEAP_TYPE_CARVEOUT) 55#define ION_HEAP_TYPE_DMA_MASK (1 << ION_HEAP_TYPE_DMA) 56 57/** 58 * heap flags - the lower 16 bits are used by core ion, the upper 16 59 * bits are reserved for use by the heaps themselves. 60 */ 61#define ION_FLAG_CACHED 1 /* mappings of this buffer should be 62 cached, ion will do cache 63 maintenance when the buffer is 64 mapped for dma */ 65 66#ifdef __KERNEL__ 67#include <linux/err.h> 68#include <mach/ion.h> 69struct ion_device; 70struct ion_heap; 71struct ion_mapper; 72struct ion_client; 73struct ion_buffer; 74 75/* This should be removed some day when phys_addr_t's are fully 76 plumbed in the kernel, and all instances of ion_phys_addr_t should 77 be converted to phys_addr_t. For the time being many kernel interfaces 78 do not accept phys_addr_t's that would have to */ 79#define ion_phys_addr_t unsigned long 80#define ion_virt_addr_t unsigned long 81 82/** 83 * struct ion_platform_heap - defines a heap in the given platform 84 * @type: type of the heap from ion_heap_type enum 85 * @id: unique identifier for heap. When allocating (lower numbers 86 * will be allocated from first) 87 * @name: used for debug purposes 88 * @base: base address of heap in physical memory if applicable 89 * @size: size of the heap in bytes if applicable 90 * @memory_type:Memory type used for the heap 91 * @has_outer_cache: set to 1 if outer cache is used, 0 otherwise. 92 * @extra_data: Extra data specific to each heap type 93 * @priv: heap private data 94 */ 95struct ion_platform_heap { 96 enum ion_heap_type type; 97 unsigned int id; 98 const char *name; 99 ion_phys_addr_t base; 100 size_t size; 101 enum ion_memory_types memory_type; 102 unsigned int has_outer_cache; 103 void *extra_data; 104 void *priv; 105}; 106 107/** 108 * struct ion_platform_data - array of platform heaps passed from board file 109 * @has_outer_cache: set to 1 if outer cache is used, 0 otherwise. 110 * @nr: number of structures in the array 111 * @request_region: function to be called when the number of allocations goes 112 * from 0 -> 1 113 * @release_region: function to be called when the number of allocations goes 114 * from 1 -> 0 115 * @setup_region: function to be called upon ion registration 116 * @heaps: array of platform_heap structions 117 * 118 * Provided by the board file in the form of platform data to a platform device. 119 */ 120struct ion_platform_data { 121 unsigned int has_outer_cache; 122 int nr; 123 int (*request_region)(void *); 124 int (*release_region)(void *); 125 void *(*setup_region)(void); 126 struct ion_platform_heap *heaps; 127}; 128 129#ifdef CONFIG_ION 130 131/** 132 * ion_reserve() - reserve memory for ion heaps if applicable 133 * @data: platform data specifying starting physical address and 134 * size 135 * 136 * Calls memblock reserve to set aside memory for heaps that are 137 * located at specific memory addresses or of specfic sizes not 138 * managed by the kernel 139 */ 140void ion_reserve(struct ion_platform_data *data); 141 142/** 143 * ion_client_create() - allocate a client and returns it 144 * @dev: the global ion device 145 * @heap_mask: mask of heaps this client can allocate from 146 * @name: used for debugging 147 */ 148struct ion_client *ion_client_create(struct ion_device *dev, 149 unsigned int heap_mask, const char *name); 150 151/** 152 * msm_ion_client_create - allocate a client using the ion_device specified in 153 * drivers/gpu/ion/msm/msm_ion.c 154 * 155 * heap_mask and name are the same as ion_client_create, return values 156 * are the same as ion_client_create. 157 */ 158 159struct ion_client *msm_ion_client_create(unsigned int heap_mask, 160 const char *name); 161 162/** 163 * ion_client_destroy() - free's a client and all it's handles 164 * @client: the client 165 * 166 * Free the provided client and all it's resources including 167 * any handles it is holding. 168 */ 169void ion_client_destroy(struct ion_client *client); 170 171/** 172 * ion_alloc - allocate ion memory 173 * @client: the client 174 * @len: size of the allocation 175 * @align: requested allocation alignment, lots of hardware blocks have 176 * alignment requirements of some kind 177 * @heap_mask: mask of heaps to allocate from, if multiple bits are set 178 * heaps will be tried in order from lowest to highest order bit 179 * @flags: heap flags, the low 16 bits are consumed by ion, the high 16 180 * bits are passed on to the respective heap and can be heap 181 * custom 182 * 183 * Allocate memory in one of the heaps provided in heap mask and return 184 * an opaque handle to it. 185 */ 186struct ion_handle *ion_alloc(struct ion_client *client, size_t len, 187 size_t align, unsigned int heap_mask, 188 unsigned int flags); 189 190/** 191 * ion_free - free a handle 192 * @client: the client 193 * @handle: the handle to free 194 * 195 * Free the provided handle. 196 */ 197void ion_free(struct ion_client *client, struct ion_handle *handle); 198 199/** 200 * ion_phys - returns the physical address and len of a handle 201 * @client: the client 202 * @handle: the handle 203 * @addr: a pointer to put the address in 204 * @len: a pointer to put the length in 205 * 206 * This function queries the heap for a particular handle to get the 207 * handle's physical address. It't output is only correct if 208 * a heap returns physically contiguous memory -- in other cases 209 * this api should not be implemented -- ion_sg_table should be used 210 * instead. Returns -EINVAL if the handle is invalid. This has 211 * no implications on the reference counting of the handle -- 212 * the returned value may not be valid if the caller is not 213 * holding a reference. 214 */ 215int ion_phys(struct ion_client *client, struct ion_handle *handle, 216 ion_phys_addr_t *addr, size_t *len); 217 218/** 219 * ion_map_dma - return an sg_table describing a handle 220 * @client: the client 221 * @handle: the handle 222 * 223 * This function returns the sg_table describing 224 * a particular ion handle. 225 */ 226struct sg_table *ion_sg_table(struct ion_client *client, 227 struct ion_handle *handle); 228 229/** 230 * ion_map_kernel - create mapping for the given handle 231 * @client: the client 232 * @handle: handle to map 233 * @flags: flags for this mapping 234 * 235 * Map the given handle into the kernel and return a kernel address that 236 * can be used to access this address. If no flags are specified, this 237 * will return a non-secure uncached mapping. 238 */ 239void *ion_map_kernel(struct ion_client *client, struct ion_handle *handle); 240 241/** 242 * ion_unmap_kernel() - destroy a kernel mapping for a handle 243 * @client: the client 244 * @handle: handle to unmap 245 */ 246void ion_unmap_kernel(struct ion_client *client, struct ion_handle *handle); 247 248/** 249 * ion_share_dma_buf() - given an ion client, create a dma-buf fd 250 * @client: the client 251 * @handle: the handle 252 */ 253int ion_share_dma_buf(struct ion_client *client, struct ion_handle *handle); 254 255/** 256 * ion_import_dma_buf() - given an dma-buf fd from the ion exporter get handle 257 * @client: the client 258 * @fd: the dma-buf fd 259 * 260 * Given an dma-buf fd that was allocated through ion via ion_share_dma_buf, 261 * import that fd and return a handle representing it. If a dma-buf from 262 * another exporter is passed in this function will return ERR_PTR(-EINVAL) 263 */ 264struct ion_handle *ion_import_dma_buf(struct ion_client *client, int fd); 265 266/** 267 * ion_handle_get_flags - get the flags for a given handle 268 * 269 * @client - client who allocated the handle 270 * @handle - handle to get the flags 271 * @flags - pointer to store the flags 272 * 273 * Gets the current flags for a handle. These flags indicate various options 274 * of the buffer (caching, security, etc.) 275 */ 276int ion_handle_get_flags(struct ion_client *client, struct ion_handle *handle, 277 unsigned long *flags); 278 279 280/** 281 * ion_map_iommu - map the given handle into an iommu 282 * 283 * @client - client who allocated the handle 284 * @handle - handle to map 285 * @domain_num - domain number to map to 286 * @partition_num - partition number to allocate iova from 287 * @align - alignment for the iova 288 * @iova_length - length of iova to map. If the iova length is 289 * greater than the handle length, the remaining 290 * address space will be mapped to a dummy buffer. 291 * @iova - pointer to store the iova address 292 * @buffer_size - pointer to store the size of the buffer 293 * @flags - flags for options to map 294 * @iommu_flags - flags specific to the iommu. 295 * 296 * Maps the handle into the iova space specified via domain number. Iova 297 * will be allocated from the partition specified via partition_num. 298 * Returns 0 on success, negative value on error. 299 */ 300int ion_map_iommu(struct ion_client *client, struct ion_handle *handle, 301 int domain_num, int partition_num, unsigned long align, 302 unsigned long iova_length, unsigned long *iova, 303 unsigned long *buffer_size, 304 unsigned long flags, unsigned long iommu_flags); 305 306 307/** 308 * ion_handle_get_size - get the allocated size of a given handle 309 * 310 * @client - client who allocated the handle 311 * @handle - handle to get the size 312 * @size - pointer to store the size 313 * 314 * gives the allocated size of a handle. returns 0 on success, negative 315 * value on error 316 * 317 * NOTE: This is intended to be used only to get a size to pass to map_iommu. 318 * You should *NOT* rely on this for any other usage. 319 */ 320 321int ion_handle_get_size(struct ion_client *client, struct ion_handle *handle, 322 unsigned long *size); 323 324/** 325 * ion_unmap_iommu - unmap the handle from an iommu 326 * 327 * @client - client who allocated the handle 328 * @handle - handle to unmap 329 * @domain_num - domain to unmap from 330 * @partition_num - partition to unmap from 331 * 332 * Decrement the reference count on the iommu mapping. If the count is 333 * 0, the mapping will be removed from the iommu. 334 */ 335void ion_unmap_iommu(struct ion_client *client, struct ion_handle *handle, 336 int domain_num, int partition_num); 337 338 339/** 340 * ion_secure_heap - secure a heap 341 * 342 * @client - a client that has allocated from the heap heap_id 343 * @heap_id - heap id to secure. 344 * @version - version of content protection 345 * @data - extra data needed for protection 346 * 347 * Secure a heap 348 * Returns 0 on success 349 */ 350int ion_secure_heap(struct ion_device *dev, int heap_id, int version, 351 void *data); 352 353/** 354 * ion_unsecure_heap - un-secure a heap 355 * 356 * @client - a client that has allocated from the heap heap_id 357 * @heap_id - heap id to un-secure. 358 * @version - version of content protection 359 * @data - extra data needed for protection 360 * 361 * Un-secure a heap 362 * Returns 0 on success 363 */ 364int ion_unsecure_heap(struct ion_device *dev, int heap_id, int version, 365 void *data); 366 367/** 368 * msm_ion_do_cache_op - do cache operations. 369 * 370 * @client - pointer to ION client. 371 * @handle - pointer to buffer handle. 372 * @vaddr - virtual address to operate on. 373 * @len - Length of data to do cache operation on. 374 * @cmd - Cache operation to perform: 375 * ION_IOC_CLEAN_CACHES 376 * ION_IOC_INV_CACHES 377 * ION_IOC_CLEAN_INV_CACHES 378 * 379 * Returns 0 on success 380 */ 381int msm_ion_do_cache_op(struct ion_client *client, struct ion_handle *handle, 382 void *vaddr, unsigned long len, unsigned int cmd); 383 384#else 385static inline void ion_reserve(struct ion_platform_data *data) 386{ 387 388} 389 390static inline struct ion_client *ion_client_create(struct ion_device *dev, 391 unsigned int heap_mask, const char *name) 392{ 393 return ERR_PTR(-ENODEV); 394} 395 396static inline struct ion_client *msm_ion_client_create(unsigned int heap_mask, 397 const char *name) 398{ 399 return ERR_PTR(-ENODEV); 400} 401 402static inline void ion_client_destroy(struct ion_client *client) { } 403 404static inline struct ion_handle *ion_alloc(struct ion_client *client, 405 size_t len, size_t align, 406 unsigned int heap_mask, 407 unsigned int flags) 408{ 409 return ERR_PTR(-ENODEV); 410} 411 412static inline void ion_free(struct ion_client *client, 413 struct ion_handle *handle) { } 414 415 416static inline int ion_phys(struct ion_client *client, 417 struct ion_handle *handle, ion_phys_addr_t *addr, size_t *len) 418{ 419 return -ENODEV; 420} 421 422static inline struct sg_table *ion_sg_table(struct ion_client *client, 423 struct ion_handle *handle) 424{ 425 return ERR_PTR(-ENODEV); 426} 427 428static inline void *ion_map_kernel(struct ion_client *client, 429 struct ion_handle *handle, unsigned long flags) 430{ 431 return ERR_PTR(-ENODEV); 432} 433 434static inline void ion_unmap_kernel(struct ion_client *client, 435 struct ion_handle *handle) { } 436 437static inline int ion_share_dma_buf(struct ion_client *client, struct ion_handle *handle) 438{ 439 return -ENODEV; 440} 441 442static inline struct ion_handle *ion_import_dma_buf(struct ion_client *client, int fd) 443{ 444 return ERR_PTR(-ENODEV); 445} 446 447static inline int ion_handle_get_flags(struct ion_client *client, 448 struct ion_handle *handle, unsigned long *flags) 449{ 450 return -ENODEV; 451} 452 453static inline int ion_map_iommu(struct ion_client *client, 454 struct ion_handle *handle, int domain_num, 455 int partition_num, unsigned long align, 456 unsigned long iova_length, unsigned long *iova, 457 unsigned long *buffer_size, 458 unsigned long flags, 459 unsigned long iommu_flags) 460{ 461 return -ENODEV; 462} 463 464static inline void ion_unmap_iommu(struct ion_client *client, 465 struct ion_handle *handle, int domain_num, 466 int partition_num) 467{ 468 return; 469} 470 471static inline int ion_secure_heap(struct ion_device *dev, int heap_id, 472 int version, void *data) 473{ 474 return -ENODEV; 475 476} 477 478static inline int ion_unsecure_heap(struct ion_device *dev, int heap_id, 479 int version, void *data) 480{ 481 return -ENODEV; 482} 483 484static inline int msm_ion_do_cache_op(struct ion_client *client, 485 struct ion_handle *handle, void *vaddr, 486 unsigned long len, unsigned int cmd) 487{ 488 return -ENODEV; 489} 490 491#endif /* CONFIG_ION */ 492#endif /* __KERNEL__ */ 493 494/** 495 * DOC: Ion Userspace API 496 * 497 * create a client by opening /dev/ion 498 * most operations handled via following ioctls 499 * 500 */ 501 502/** 503 * struct ion_allocation_data - metadata passed from userspace for allocations 504 * @len: size of the allocation 505 * @align: required alignment of the allocation 506 * @heap_mask: mask of heaps to allocate from 507 * @flags: flags passed to heap 508 * @handle: pointer that will be populated with a cookie to use to refer 509 * to this allocation 510 * 511 * Provided by userspace as an argument to the ioctl 512 */ 513struct ion_allocation_data { 514 size_t len; 515 size_t align; 516 unsigned int heap_id_mask; 517 unsigned int flags; 518 ion_user_handle_t handle; 519}; 520 521/** 522 * struct ion_fd_data - metadata passed to/from userspace for a handle/fd pair 523 * @handle: a handle 524 * @fd: a file descriptor representing that handle 525 * 526 * For ION_IOC_SHARE or ION_IOC_MAP userspace populates the handle field with 527 * the handle returned from ion alloc, and the kernel returns the file 528 * descriptor to share or map in the fd field. For ION_IOC_IMPORT, userspace 529 * provides the file descriptor and the kernel returns the handle. 530 */ 531struct ion_fd_data { 532 ion_user_handle_t handle; 533 int fd; 534}; 535 536/** 537 * struct ion_handle_data - a handle passed to/from the kernel 538 * @handle: a handle 539 */ 540struct ion_handle_data { 541 ion_user_handle_t handle; 542}; 543 544/** 545 * struct ion_custom_data - metadata passed to/from userspace for a custom ioctl 546 * @cmd: the custom ioctl function to call 547 * @arg: additional data to pass to the custom ioctl, typically a user 548 * pointer to a predefined structure 549 * 550 * This works just like the regular cmd and arg fields of an ioctl. 551 */ 552struct ion_custom_data { 553 unsigned int cmd; 554 unsigned long arg; 555}; 556#define ION_IOC_MAGIC 'I' 557 558/** 559 * DOC: ION_IOC_ALLOC - allocate memory 560 * 561 * Takes an ion_allocation_data struct and returns it with the handle field 562 * populated with the opaque handle for the allocation. 563 */ 564#define ION_IOC_ALLOC _IOWR(ION_IOC_MAGIC, 0, \ 565 struct ion_allocation_data) 566 567/** 568 * DOC: ION_IOC_FREE - free memory 569 * 570 * Takes an ion_handle_data struct and frees the handle. 571 */ 572#define ION_IOC_FREE _IOWR(ION_IOC_MAGIC, 1, struct ion_handle_data) 573 574/** 575 * DOC: ION_IOC_MAP - get a file descriptor to mmap 576 * 577 * Takes an ion_fd_data struct with the handle field populated with a valid 578 * opaque handle. Returns the struct with the fd field set to a file 579 * descriptor open in the current address space. This file descriptor 580 * can then be used as an argument to mmap. 581 */ 582#define ION_IOC_MAP _IOWR(ION_IOC_MAGIC, 2, struct ion_fd_data) 583 584/** 585 * DOC: ION_IOC_SHARE - creates a file descriptor to use to share an allocation 586 * 587 * Takes an ion_fd_data struct with the handle field populated with a valid 588 * opaque handle. Returns the struct with the fd field set to a file 589 * descriptor open in the current address space. This file descriptor 590 * can then be passed to another process. The corresponding opaque handle can 591 * be retrieved via ION_IOC_IMPORT. 592 */ 593#define ION_IOC_SHARE _IOWR(ION_IOC_MAGIC, 4, struct ion_fd_data) 594 595/** 596 * DOC: ION_IOC_IMPORT - imports a shared file descriptor 597 * 598 * Takes an ion_fd_data struct with the fd field populated with a valid file 599 * descriptor obtained from ION_IOC_SHARE and returns the struct with the handle 600 * filed set to the corresponding opaque handle. 601 */ 602#define ION_IOC_IMPORT _IOWR(ION_IOC_MAGIC, 5, struct ion_fd_data) 603 604/** 605 * DOC: ION_IOC_CUSTOM - call architecture specific ion ioctl 606 * 607 * Takes the argument of the architecture specific ioctl to call and 608 * passes appropriate userdata for that ioctl 609 */ 610#define ION_IOC_CUSTOM _IOWR(ION_IOC_MAGIC, 6, struct ion_custom_data) 611 612/** 613 * DOC: ION_IOC_SYNC - syncs a shared file descriptors to memory 614 * 615 * Deprecated in favor of using the dma_buf api's correctly (syncing 616 * will happend automatically when the buffer is mapped to a device). 617 * If necessary should be used after touching a cached buffer from the cpu, 618 * this will make the buffer in memory coherent. 619 */ 620#define ION_IOC_SYNC _IOWR(ION_IOC_MAGIC, 7, struct ion_fd_data) 621#endif /* _LINUX_ION_H */ 622