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 22 #include "../uapi/ion.h" 23 24 struct ion_handle; 25 struct ion_device; 26 struct ion_heap; 27 struct ion_mapper; 28 struct ion_client; 29 struct ion_buffer; 30 31 /* 32 * This should be removed some day when phys_addr_t's are fully 33 * plumbed in the kernel, and all instances of ion_phys_addr_t should 34 * be converted to phys_addr_t. For the time being many kernel interfaces 35 * do not accept phys_addr_t's that would have to 36 */ 37 #define ion_phys_addr_t unsigned long 38 39 /** 40 * struct ion_platform_heap - defines a heap in the given platform 41 * @type: type of the heap from ion_heap_type enum 42 * @id: unique identifier for heap. When allocating higher numbers 43 * will be allocated from first. At allocation these are passed 44 * as a bit mask and therefore can not exceed ION_NUM_HEAP_IDS. 45 * @name: used for debug purposes 46 * @base: base address of heap in physical memory if applicable 47 * @size: size of the heap in bytes if applicable 48 * @align: required alignment in physical memory if applicable 49 * @priv: private info passed from the board file 50 * 51 * Provided by the board file. 52 */ 53 struct ion_platform_heap { 54 enum ion_heap_type type; 55 unsigned int id; 56 const char *name; 57 ion_phys_addr_t base; 58 size_t size; 59 ion_phys_addr_t align; 60 void *priv; 61 }; 62 63 /** 64 * struct ion_platform_data - array of platform heaps passed from board file 65 * @nr: number of structures in the array 66 * @heaps: array of platform_heap structions 67 * 68 * Provided by the board file in the form of platform data to a platform device. 69 */ 70 struct ion_platform_data { 71 int nr; 72 struct ion_platform_heap *heaps; 73 }; 74 75 /** 76 * ion_reserve() - reserve memory for ion heaps if applicable 77 * @data: platform data specifying starting physical address and 78 * size 79 * 80 * Calls memblock reserve to set aside memory for heaps that are 81 * located at specific memory addresses or of specific sizes not 82 * managed by the kernel 83 */ 84 void ion_reserve(struct ion_platform_data *data); 85 86 /** 87 * ion_client_create() - allocate a client and returns it 88 * @dev: the global ion device 89 * @name: used for debugging 90 */ 91 struct ion_client *ion_client_create(struct ion_device *dev, 92 const char *name); 93 94 /** 95 * ion_client_destroy() - free's a client and all it's handles 96 * @client: the client 97 * 98 * Free the provided client and all it's resources including 99 * any handles it is holding. 100 */ 101 void ion_client_destroy(struct ion_client *client); 102 103 /** 104 * ion_alloc - allocate ion memory 105 * @client: the client 106 * @len: size of the allocation 107 * @align: requested allocation alignment, lots of hardware blocks 108 * have alignment requirements of some kind 109 * @heap_id_mask: mask of heaps to allocate from, if multiple bits are set 110 * heaps will be tried in order from highest to lowest 111 * id 112 * @flags: heap flags, the low 16 bits are consumed by ion, the 113 * high 16 bits are passed on to the respective heap and 114 * can be heap custom 115 * 116 * Allocate memory in one of the heaps provided in heap mask and return 117 * an opaque handle to it. 118 */ 119 struct ion_handle *ion_alloc(struct ion_client *client, size_t len, 120 size_t align, unsigned int heap_id_mask, 121 unsigned int flags); 122 123 /** 124 * ion_free - free a handle 125 * @client: the client 126 * @handle: the handle to free 127 * 128 * Free the provided handle. 129 */ 130 void ion_free(struct ion_client *client, struct ion_handle *handle); 131 132 /** 133 * ion_phys - returns the physical address and len of a handle 134 * @client: the client 135 * @handle: the handle 136 * @addr: a pointer to put the address in 137 * @len: a pointer to put the length in 138 * 139 * This function queries the heap for a particular handle to get the 140 * handle's physical address. It't output is only correct if 141 * a heap returns physically contiguous memory -- in other cases 142 * this api should not be implemented -- ion_sg_table should be used 143 * instead. Returns -EINVAL if the handle is invalid. This has 144 * no implications on the reference counting of the handle -- 145 * the returned value may not be valid if the caller is not 146 * holding a reference. 147 */ 148 int ion_phys(struct ion_client *client, struct ion_handle *handle, 149 ion_phys_addr_t *addr, size_t *len); 150 151 /** 152 * ion_map_dma - return an sg_table describing a handle 153 * @client: the client 154 * @handle: the handle 155 * 156 * This function returns the sg_table describing 157 * a particular ion handle. 158 */ 159 struct sg_table *ion_sg_table(struct ion_client *client, 160 struct ion_handle *handle); 161 162 /** 163 * ion_map_kernel - create mapping for the given handle 164 * @client: the client 165 * @handle: handle to map 166 * 167 * Map the given handle into the kernel and return a kernel address that 168 * can be used to access this address. 169 */ 170 void *ion_map_kernel(struct ion_client *client, struct ion_handle *handle); 171 172 /** 173 * ion_unmap_kernel() - destroy a kernel mapping for a handle 174 * @client: the client 175 * @handle: handle to unmap 176 */ 177 void ion_unmap_kernel(struct ion_client *client, struct ion_handle *handle); 178 179 /** 180 * ion_share_dma_buf() - share buffer as dma-buf 181 * @client: the client 182 * @handle: the handle 183 */ 184 struct dma_buf *ion_share_dma_buf(struct ion_client *client, 185 struct ion_handle *handle); 186 187 /** 188 * ion_share_dma_buf_fd() - given an ion client, create a dma-buf fd 189 * @client: the client 190 * @handle: the handle 191 */ 192 int ion_share_dma_buf_fd(struct ion_client *client, struct ion_handle *handle); 193 194 /** 195 * ion_import_dma_buf() - given an dma-buf fd from the ion exporter get handle 196 * @client: the client 197 * @fd: the dma-buf fd 198 * 199 * Given an dma-buf fd that was allocated through ion via ion_share_dma_buf, 200 * import that fd and return a handle representing it. If a dma-buf from 201 * another exporter is passed in this function will return ERR_PTR(-EINVAL) 202 */ 203 struct ion_handle *ion_import_dma_buf(struct ion_client *client, int fd); 204 205 #endif /* _LINUX_ION_H */ 206