drivers/staging/android/ion/ion.h

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