Home | History | Annotate | Download | only in linux
      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 _UAPI_ION_H
     18 #define _UAPI_ION_H
     19 
     20 #include <linux/ioctl.h>
     21 #include <linux/types.h>
     22 
     23 typedef int ion_user_handle_t;
     24 
     25 /**
     26  * enum ion_heap_types - list of all possible types of heaps
     27  * @ION_HEAP_TYPE_SYSTEM:	 memory allocated via vmalloc
     28  * @ION_HEAP_TYPE_SYSTEM_CONTIG: memory allocated via kmalloc
     29  * @ION_HEAP_TYPE_CARVEOUT:	 memory allocated from a prereserved
     30  * 				 carveout heap, allocations are physically
     31  * 				 contiguous
     32  * @ION_HEAP_TYPE_DMA:		 memory allocated via DMA API
     33  * @ION_NUM_HEAPS:		 helper for iterating over heaps, a bit mask
     34  * 				 is used to identify the heaps, so only 32
     35  * 				 total heap types are supported
     36  */
     37 enum ion_heap_type {
     38 	ION_HEAP_TYPE_SYSTEM,
     39 	ION_HEAP_TYPE_SYSTEM_CONTIG,
     40 	ION_HEAP_TYPE_CARVEOUT,
     41 	ION_HEAP_TYPE_CHUNK,
     42 	ION_HEAP_TYPE_DMA,
     43 	ION_HEAP_TYPE_CUSTOM, /* must be last so device specific heaps always
     44 				 are at the end of this enum */
     45 	ION_NUM_HEAPS = 16,
     46 };
     47 
     48 #define ION_HEAP_SYSTEM_MASK		(1 << ION_HEAP_TYPE_SYSTEM)
     49 #define ION_HEAP_SYSTEM_CONTIG_MASK	(1 << ION_HEAP_TYPE_SYSTEM_CONTIG)
     50 #define ION_HEAP_CARVEOUT_MASK		(1 << ION_HEAP_TYPE_CARVEOUT)
     51 #define ION_HEAP_TYPE_DMA_MASK		(1 << ION_HEAP_TYPE_DMA)
     52 
     53 #define ION_NUM_HEAP_IDS		sizeof(unsigned int) * 8
     54 
     55 /**
     56  * allocation flags - the lower 16 bits are used by core ion, the upper 16
     57  * bits are reserved for use by the heaps themselves.
     58  */
     59 #define ION_FLAG_CACHED 1		/* mappings of this buffer should be
     60 					   cached, ion will do cache
     61 					   maintenance when the buffer is
     62 					   mapped for dma */
     63 #define ION_FLAG_CACHED_NEEDS_SYNC 2	/* mappings of this buffer will created
     64 					   at mmap time, if this is set
     65 					   caches must be managed manually */
     66 
     67 /**
     68  * DOC: Ion Userspace API
     69  *
     70  * create a client by opening /dev/ion
     71  * most operations handled via following ioctls
     72  *
     73  */
     74 
     75 /**
     76  * struct ion_allocation_data - metadata passed from userspace for allocations
     77  * @len:		size of the allocation
     78  * @align:		required alignment of the allocation
     79  * @heap_id_mask:	mask of heap ids to allocate from
     80  * @flags:		flags passed to heap
     81  * @handle:		pointer that will be populated with a cookie to use to
     82  *			refer to this allocation
     83  *
     84  * Provided by userspace as an argument to the ioctl
     85  */
     86 struct ion_allocation_data {
     87 	size_t len;
     88 	size_t align;
     89 	unsigned int heap_id_mask;
     90 	unsigned int flags;
     91 	ion_user_handle_t handle;
     92 };
     93 
     94 /**
     95  * struct ion_fd_data - metadata passed to/from userspace for a handle/fd pair
     96  * @handle:	a handle
     97  * @fd:		a file descriptor representing that handle
     98  *
     99  * For ION_IOC_SHARE or ION_IOC_MAP userspace populates the handle field with
    100  * the handle returned from ion alloc, and the kernel returns the file
    101  * descriptor to share or map in the fd field.  For ION_IOC_IMPORT, userspace
    102  * provides the file descriptor and the kernel returns the handle.
    103  */
    104 struct ion_fd_data {
    105 	ion_user_handle_t handle;
    106 	int fd;
    107 };
    108 
    109 /**
    110  * struct ion_handle_data - a handle passed to/from the kernel
    111  * @handle:	a handle
    112  */
    113 struct ion_handle_data {
    114 	ion_user_handle_t handle;
    115 };
    116 
    117 /**
    118  * struct ion_custom_data - metadata passed to/from userspace for a custom ioctl
    119  * @cmd:	the custom ioctl function to call
    120  * @arg:	additional data to pass to the custom ioctl, typically a user
    121  *		pointer to a predefined structure
    122  *
    123  * This works just like the regular cmd and arg fields of an ioctl.
    124  */
    125 struct ion_custom_data {
    126 	unsigned int cmd;
    127 	unsigned long arg;
    128 };
    129 #define ION_IOC_MAGIC		'I'
    130 
    131 /**
    132  * DOC: ION_IOC_ALLOC - allocate memory
    133  *
    134  * Takes an ion_allocation_data struct and returns it with the handle field
    135  * populated with the opaque handle for the allocation.
    136  */
    137 #define ION_IOC_ALLOC		_IOWR(ION_IOC_MAGIC, 0, \
    138 				      struct ion_allocation_data)
    139 
    140 /**
    141  * DOC: ION_IOC_FREE - free memory
    142  *
    143  * Takes an ion_handle_data struct and frees the handle.
    144  */
    145 #define ION_IOC_FREE		_IOWR(ION_IOC_MAGIC, 1, struct ion_handle_data)
    146 
    147 /**
    148  * DOC: ION_IOC_MAP - get a file descriptor to mmap
    149  *
    150  * Takes an ion_fd_data struct with the handle field populated with a valid
    151  * opaque handle.  Returns the struct with the fd field set to a file
    152  * descriptor open in the current address space.  This file descriptor
    153  * can then be used as an argument to mmap.
    154  */
    155 #define ION_IOC_MAP		_IOWR(ION_IOC_MAGIC, 2, struct ion_fd_data)
    156 
    157 /**
    158  * DOC: ION_IOC_SHARE - creates a file descriptor to use to share an allocation
    159  *
    160  * Takes an ion_fd_data struct with the handle field populated with a valid
    161  * opaque handle.  Returns the struct with the fd field set to a file
    162  * descriptor open in the current address space.  This file descriptor
    163  * can then be passed to another process.  The corresponding opaque handle can
    164  * be retrieved via ION_IOC_IMPORT.
    165  */
    166 #define ION_IOC_SHARE		_IOWR(ION_IOC_MAGIC, 4, struct ion_fd_data)
    167 
    168 /**
    169  * DOC: ION_IOC_IMPORT - imports a shared file descriptor
    170  *
    171  * Takes an ion_fd_data struct with the fd field populated with a valid file
    172  * descriptor obtained from ION_IOC_SHARE and returns the struct with the handle
    173  * filed set to the corresponding opaque handle.
    174  */
    175 #define ION_IOC_IMPORT		_IOWR(ION_IOC_MAGIC, 5, struct ion_fd_data)
    176 
    177 /**
    178  * DOC: ION_IOC_SYNC - syncs a shared file descriptors to memory
    179  *
    180  * Deprecated in favor of using the dma_buf api's correctly (syncing
    181  * will happend automatically when the buffer is mapped to a device).
    182  * If necessary should be used after touching a cached buffer from the cpu,
    183  * this will make the buffer in memory coherent.
    184  */
    185 #define ION_IOC_SYNC		_IOWR(ION_IOC_MAGIC, 7, struct ion_fd_data)
    186 
    187 /**
    188  * DOC: ION_IOC_CUSTOM - call architecture specific ion ioctl
    189  *
    190  * Takes the argument of the architecture specific ioctl to call and
    191  * passes appropriate userdata for that ioctl
    192  */
    193 #define ION_IOC_CUSTOM		_IOWR(ION_IOC_MAGIC, 6, struct ion_custom_data)
    194 
    195 #endif /* _UAPI_ION_H */
    196