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