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