src/tbm_bufmgr.h

   1 /**************************************************************************
   2
   3 libtbm
   4
   5 Copyright 2012 Samsung Electronics co., Ltd. All Rights Reserved.
   6
   7 Contact: SooChan Lim <sc1.lim@samsung.com>, Sangjin Lee <lsj119@samsung.com>
   8
   9 Permission is hereby granted, free of charge, to any person obtaining a
  10 copy of this software and associated documentation files (the
  11 "Software"), to deal in the Software without restriction, including
  12 without limitation the rights to use, copy, modify, merge, publish,
  13 distribute, sub license, and/or sell copies of the Software, and to
  14 permit persons to whom the Software is furnished to do so, subject to
  15 the following conditions:
  16
  17 The above copyright notice and this permission notice (including the
  18 next paragraph) shall be included in all copies or substantial portions
  19 of the Software.
  20
  21 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  22 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  23 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
  24 IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR
  25 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  26 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  27 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  28
  29 **************************************************************************/
  30
  31 #ifndef _TBM_BUFMGR_H_
  32 #define _TBM_BUFMGR_H_
  33
  34 #include <stdint.h>
  35
  36 /**
  37  * \file tbm_bufmgr.h
  38  * \brief Tizen Buffer Manager
  39  */
  40
  41 typedef struct _tbm_bufmgr *tbm_bufmgr;
  42 typedef struct _tbm_bo *tbm_bo;
  43
  44 /* TBM_DEVICE_TYPE */
  45 #define TBM_DEVICE_DEFAULT   0  /**< device type to get the default handle    */
  46 #define TBM_DEVICE_CPU       1  /**< device type to get the virtual pointer   */
  47 #define TBM_DEVICE_2D        2  /**< device type to get the 2D memory handle  */
  48 #define TBM_DEVICE_3D        3  /**< device type to get the 3D memory handle  */
  49 #define TBM_DEVICE_MM        4  /**< device type to get the multimedia handle */
  50
  51 /* TBM_OPTION */
  52 #define TBM_OPTION_READ      (1 << 0) /**< access option to read  */
  53 #define TBM_OPTION_WRITE     (1 << 1) /**< access option to write */
  54
  55 /**
  56  * @brief tbm_bo_handle
  57  *  abstraction of the memory handle by TBM_DEVICE_TYPE
  58  */
  59 typedef union _tbm_bo_handle
  60 {
  61    void     *ptr;
  62    int32_t  s32;
  63    uint32_t u32;
  64    int64_t  s64;
  65    uint64_t u64;
  66 } tbm_bo_handle;
  67
  68 /**
  69  * @brief Enumeration of bo memory type
  70  */
  71 enum TBM_BO_FLAGS
  72 {
  73     TBM_BO_DEFAULT = 0,          /**< physically non-contiguous memory */
  74     TBM_BO_SCANOUT = (1<<0),     /**< physically contiguous memory     */
  75     TBM_BO_NONCACHABLE = (1<<1), /**< non-cachable memory              */
  76     TBM_BO_WC = (1<<2),          /**< write-combine memory             */
  77 };
  78
  79 /* Functions for buffer manager */
  80
  81 /**
  82  * @brief initialize the buffer manager.
  83  * @param[in] fd : file descripter of the system buffer manager
  84  * @return a buffer manager
  85  */
  86 tbm_bufmgr tbm_bufmgr_init   (int fd);
  87
  88 /**
  89  * @brief deinitialize the buffer manager.
  90  * @param[in] bufmgr : the buffer manager
  91  */
  92 void       tbm_bufmgr_deinit (tbm_bufmgr bufmgr);
  93
  94 /* Functions for bo */
  95
  96 /**
  97  * @brief allocate the buffer object
  98  * @param[in] bufmgr : the buffer manager
  99  * @param[in] size : the size of buffer object
 100  * @param[in] flags : the flags of memory type
 101  * @return a buffer object
 102  */
 103 tbm_bo        tbm_bo_alloc      (tbm_bufmgr bufmgr, int size, int flags);
 104
 105 /**
 106  * @brief increase the reference count of bo.
 107  * @param[in] bo : the buffer object
 108  * @return a buffer object
 109  */
 110 tbm_bo        tbm_bo_ref        (tbm_bo bo);
 111
 112 /**
 113  * @brief increase the reference count of bo.
 114  * @param[in] bo : the buffer object
 115  */
 116 void          tbm_bo_unref      (tbm_bo bo);
 117
 118 /**
 119  * @brief map the buffer object according to the device type and the option.
 120  * @param[in] bo : the buffer object
 121  * @param[in] device : the device type to get a handle
 122  * @param[in] option : the option to access the buffer object
 123  * @return the handle of the buffer object
 124  */
 125 tbm_bo_handle tbm_bo_map        (tbm_bo bo, int device, int opt);
 126
 127 /**
 128  * @brief unmap the buffer object.
 129  * @param[in] bo : the buffer object
 130  * @return 1 if this function succeeds, otherwise 0.
 131  */
 132 int           tbm_bo_unmap      (tbm_bo bo);
 133
 134 /**
 135  * @brief get the tbm_bo_handle according to the device type.
 136  * @param[in] bo : the buffer object
 137  * @param[in] device : the device type to get a handle
 138  * @return the handle of the buffer object
 139  */
 140 tbm_bo_handle tbm_bo_get_handle (tbm_bo bo, int device);
 141
 142 /**
 143  * @brief export the buffer object
 144  * @param[in] bo : the buffer object
 145  * @return key associated with the buffer object
 146  */
 147 unsigned int  tbm_bo_export     (tbm_bo bo);
 148
 149 /**
 150  * @brief import the buffer object associated with the key.
 151  * @param[in] bufmgr : the buffer manager
 152  * @param[in] key : the key associated with the buffer object
 153  * @return a buffer object
 154  */
 155 tbm_bo        tbm_bo_import     (tbm_bufmgr bufmgr, unsigned int key);
 156
 157 /**
 158  * @brief get the size of a bo.
 159  * @param[in] bo : the buffer object
 160  * @return 1 if this function succeeds, otherwise 0.
 161  */
 162 int           tbm_bo_size       (tbm_bo bo);
 163
 164 /**
 165  * @brief get the state where the buffer object is locked.
 166  * @param[in] bo : the buffer object
 167  * @return 1 if this function succeeds, otherwise 0.
 168  */
 169 int           tbm_bo_locked     (tbm_bo bo);
 170
 171 /**
 172  * @brief swap the buffer object.
 173  * @param[in] bo1 : the buffer object
 174  * @param[in] bo2 : the buffer object
 175  * @return 1 if this function succeeds, otherwise 0.
 176  */
 177 int           tbm_bo_swap       (tbm_bo bo1, tbm_bo bo2);
 178
 179
 180 /* Functions for userdata of bo */
 181 typedef void (*tbm_data_free)(void *);
 182
 183 /**
 184  * @brief add a user_data to the buffer object
 185  * @param[in] bo : the buffer object
 186  * @param[in] key : the key associated with the user_date
 187  * @param[in] data_free_func : the function pointer to free the user_data
 188  * @return 1 if this function succeeds, otherwise 0.
 189  */
 190 int tbm_bo_add_user_data    (tbm_bo bo, unsigned long key, tbm_data_free data_free_func);
 191
 192 /**
 193  * @brief delete the user_data in the buffer object.
 194  * @param[in] bo : the buffer object
 195  * @param[in] key : the key associated with the user_date
 196  * @return 1 if this function succeeds, otherwise 0.
 197  */
 198 int tbm_bo_delete_user_data (tbm_bo bo, unsigned long key);
 199
 200 /**
 201  * @brief set a user_date to the buffer object.
 202  * @param[in] bo : the buffer object
 203  * @param[in] key : the key associated with the user_date
 204  * @param[in] data : a pointer of the user_data
 205  * @return 1 if this function succeeds, otherwise 0.
 206  */
 207 int tbm_bo_set_user_data    (tbm_bo bo, unsigned long key, void* data);
 208
 209 /**
 210  * @brief get a user_date from the buffer object with the key.
 211  * @param[in] bo : the buffer object
 212  * @param[in] key : the key associated with the user_date
 213  * @param[out] data : to get the user data
 214  * @return 1 if this function succeeds, otherwise 0.
 215  */
 216 int tbm_bo_get_user_data    (tbm_bo bo, unsigned long key, void** data);
 217
 218 #endif /* _TBM_BUFMGR_H_ */
 219