include/ion.h

   1 /*
   2  * Copyright (C) 2012 Samsung Electronics Co., Ltd.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef _LIB_ION_H_
  18 #define _LIB_ION_H_
  19
  20 #include <unistd.h> /* size_t */
  21
  22 #define ION_FLAG_CACHED 1
  23 #define ION_FLAG_CACHED_NEEDS_SYNC 2
  24 #define ION_FLAG_PRESERVE_KMAP 4
  25 #define ION_FLAG_NOZEROED 8
  26
  27 #define ION_HEAP_SYSTEM_MASK            (1 << 0)
  28 #define ION_HEAP_SYSTEM_CONTIG_MASK     (1 << 1)
  29 #define ION_HEAP_EXYNOS_CONTIG_MASK     (1 << 4)
  30 #define ION_HEAP_EXYNOS_MASK            (1 << 5)
  31 #define ION_EXYNOS_VIDEO_MASK     (1 << 21)
  32 #define ION_EXYNOS_FIMD_VIDEO_MASK    (1 << 28)
  33 #define ION_EXYNOS_GSC_MASK             (1 << 27)
  34 #define ION_EXYNOS_MFC_OUTPUT_MASK    (1 << 26)
  35 #define ION_EXYNOS_MFC_INPUT_MASK    (1 << 25)
  36
  37
  38 /* ION_MSYNC_FLAGS
  39  * values of @flags parameter to ion_msync()
  40  *
  41  * IMSYNC_DEV_TO_READ: Device only reads the buffer
  42  * IMSYNC_DEV_TO_WRITE: Device may writes to the buffer
  43  * IMSYNC_DEV_TO_RW: Device reads and writes to the buffer
  44  *
  45  * IMSYNC_SYNC_FOR_DEV: ion_msync() for device to access the buffer
  46  * IMSYNC_SYNC_FOR_CPU: ion_msync() for CPU to access the buffer after device
  47  *                      has accessed it.
  48  *
  49  * The values must be ORed with one of IMSYNC_DEV_* and one of IMSYNC_SYNC_*.
  50  * Otherwise, ion_msync() will not effect.
  51  */
  52 enum ION_MSYNC_FLAGS {
  53     IMSYNC_DEV_TO_READ = 0,
  54     IMSYNC_DEV_TO_WRITE = 1,
  55     IMSYNC_DEV_TO_RW = 2,
  56     IMSYNC_SYNC_FOR_DEV = 0x10000,
  57     IMSYNC_SYNC_FOR_CPU = 0x20000,
  58 };
  59
  60 struct ion_preload_object {
  61     size_t len;
  62     unsigned int count;
  63 };
  64
  65 #ifdef __cplusplus
  66 extern "C" {
  67 #endif
  68
  69 /* ion_client
  70  * An ION client is an object or an entity that needs to use the service of
  71  * ION and has unique address space. ion_client is an identifier of an ION
  72  * client and it represents the ION client.
  73  * All operations on ION needs a valid ion_client value and it can be obtained
  74  * by ion_client_create().
  75  */
  76 typedef int ion_client;
  77
  78 /* ion_buffer
  79  * An identifier of a buffer allocated from ION. You must obtain to access
  80  * a buffer allocated from ION. If you have an effective ion_buffer, you have
  81  * three options to work with it.
  82  * - To access  the buffer, you can request an address (user virtual address)
  83  *   of the buffer with ion_map().
  84  * - To pass the buffer to the kernel, you can pass the ion_buffer to the
  85  *   kernel driver directly, if the kernel driver can work with ION.
  86  * - To pass the buffer to other processes, you can pass the ion_buffer to
  87  *   other processes through RPC machanism such as socket communication or
  88  *   Android Binder because ion_buffer is actually an open file descripotor
  89  *   of the current process.
  90  */
  91 typedef int ion_buffer;
  92
  93 typedef unsigned int ion_handle;
  94
  95 /* ion_client_create()
  96  * @RETURN: new ion_client.
  97  *          netative value if creating new ion_client is failed.
  98  *
  99  * A call to ion_client_create() must be paired with ion_client_destroy(),
 100  * symmetrically. ion_client_destroy() needs a valid ion_client that
 101  * is returned by ion_client_create().
 102  */
 103 ion_client ion_client_create(void);
 104
 105 /* ion_client_destroy()
 106  * @client: An ion_client value to remove.
 107  */
 108 void ion_client_destroy(ion_client client);
 109
 110 /* ion_alloc() - Allocates new buffer from ION.
 111  * @client: A valid ion_client value returned by ion_client_create().
 112  * @len: Size of a buffer required in bytes.
 113  * @align: Alignment requirements of @len and the start address of the allocated
 114  *         buffer. If the @len is not aligned by @align, ION allocates a buffer
 115  *         that is aligned by @align and the size of the buffer will be larger
 116  *         than @len.
 117  * @heap_mask: Mask of heaps which you want this allocation to be served from.
 118  * @flags: Additional requirements about buffer. ION_FLAG_CACHED for a
 119  *         buffer you want to have a cached mapping of
 120  * @RETURN: An ion_buffer that represents the buffer allocated. It is only
 121  *          unique in the context of the given client, @client.
 122  *          -error if the allocation failed.
 123  *          See the description of ion_buffer above for detailed information.
 124  */
 125 ion_buffer ion_alloc(ion_client client, size_t len, size_t align,
 126                      unsigned int heap_mask, unsigned int flags);
 127
 128 /* ion_free() - Frees an existing buffer that is allocated by ION
 129  * @buffer: An ion_buffer of the buffer to be released.
 130  */
 131 void ion_free(ion_buffer buffer);
 132
 133 /* ion_map() - Obtains a virtual address of the buffer identied by @buffer
 134  * @buffer: The buffer to map. The virtual address returned is allocated by the
 135  *          kernel.
 136  * @len: The size of the buffer to map. This must not exceed the size of the
 137  *       buffer represented by @fd_buf. Thus you need to know the size of it
 138  *       before calling this function. If @len is less than the size of the
 139  *       buffer, this function just map just the size requested (@len) not the
 140  *       entire buffer.
 141  * @offset: How many pages will be ignored while mapping.@offset number of
 142  *       pages from the start of the buffer will not be mapped.
 143  * @RETURN: The start virtual addres mapped.
 144  *          MAP_FAILED if mapping fails.
 145  *
 146  * Note that @len + (@offset * PAGE_SIZE) must not exceed the size of the
 147  * buffer.
 148  */
 149 void *ion_map(ion_buffer buffer, size_t len, off_t offset);
 150
 151 /* ion_unmap() - Frees the buffer mapped by ion_map()
 152  * @addr: The address returned by ion_map().
 153  * @len: The size of the buffer mapped by ion_map().
 154  * @RETURN: 0 on success, and -1 on failure.
 155  *          errno is also set on failure.
 156  */
 157 int ion_unmap(void *addr, size_t len);
 158
 159 /* ion_msync() - Makes sure that data in the buffer are visible to H/W peri.
 160  * @client: A valid ion_client value returned by ion_client_create().
 161  * @buffer: The buffer to perform ion_msync().
 162  * @flags: Direction of access of H/W peri and CPU. See the description of
 163  *         ION_MSYNC_FLAGS.
 164  * @size: Size to ion_msync() in bytes.
 165  * @offset: Where ion_msync() start in @buffer, size in bytes.
 166  * @RETURN: 0 if successful. -error, otherwise.
 167  *
 168  * Note that @offset + @size must not exceed the size of @buffer.
 169  */
 170 int ion_sync(ion_client client, ion_buffer buffer);
 171
 172 /* ion_sync_range() - Make sure the specified range in the buffer are visible to H/W
 173  * @client: A valid ion_client value returned by ion_client_create().
 174  * @sahre_fd: A valid file descriptor for the buffer(mostely returned by ion_alloc())
 175  * @addr: start address of the region to sync.
 176           It must be the mapped address of the buffer specified by @dmabuf_fd.
 177  * @size: size of the region to sync.
 178  */
 179 int ion_sync_range(ion_client client, int dmabuf_fd, void *addr, size_t size);
 180
 181 int ion_incRef(int fd, int share_fd, ion_handle *handle);
 182
 183 int ion_decRef(int fd, ion_handle handle);
 184
 185 #ifdef __cplusplus
 186 }
 187 #endif
 188 #endif /* _LIB_ION_H_ */