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 memory    */
  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 #define TBM_OPTION_VENDOR    (0xffff0000) /**< vendor specific option: it depends on the backend */
  55
  56 /**
  57  * @brief tbm_bo_handle
  58  *  abstraction of the memory handle by TBM_DEVICE_TYPE
  59  */
  60 typedef union _tbm_bo_handle
  61 {
  62    void     *ptr;
  63    int32_t  s32;
  64    uint32_t u32;
  65    int64_t  s64;
  66    uint64_t u64;
  67 } tbm_bo_handle;
  68
  69 /**
  70  * @brief Enumeration of bo memory type
  71  */
  72 enum TBM_BO_FLAGS
  73 {
  74     TBM_BO_DEFAULT = 0,            /**< default memory: it depends on the backend         */
  75     TBM_BO_SCANOUT = (1<<0),       /**< scanout memory                                    */
  76     TBM_BO_NONCACHABLE = (1<<1),   /**< non-cachable memory                               */
  77     TBM_BO_WC = (1<<2),            /**< write-combine memory                              */
  78     TBM_BO_VENDOR = (0xffff0000), /**< vendor specific memory: it depends on the backend */
  79 };
  80
  81 #ifdef __cplusplus
  82 extern "C" {
  83 #endif
  84
  85 /* Functions for buffer manager */
  86
  87 /**
  88  * @brief initialize the buffer manager.
  89  * @param[in] fd : file descripter of the system buffer manager
  90  * @return a buffer manager
  91  */
  92 tbm_bufmgr tbm_bufmgr_init   (int fd);
  93
  94 /**
  95  * @brief deinitialize the buffer manager.
  96  * @param[in] bufmgr : the buffer manager
  97  */
  98 void       tbm_bufmgr_deinit (tbm_bufmgr bufmgr);
  99
 100 /* Functions for bo */
 101
 102 /**
 103  * @brief allocate the buffer object
 104  * @param[in] bufmgr : the buffer manager
 105  * @param[in] size : the size of buffer object
 106  * @param[in] flags : the flags of memory type
 107  * @return a buffer object
 108  */
 109 tbm_bo        tbm_bo_alloc      (tbm_bufmgr bufmgr, int size, int flags);
 110
 111 /**
 112  * @brief increase the reference count of bo.
 113  * @param[in] bo : the buffer object
 114  * @return a buffer object
 115  */
 116 tbm_bo        tbm_bo_ref        (tbm_bo bo);
 117
 118 /**
 119  * @brief increase the reference count of bo.
 120  * @param[in] bo : the buffer object
 121  */
 122 void          tbm_bo_unref      (tbm_bo bo);
 123
 124 /**
 125  * @brief map the buffer object according to the device type and the option.
 126  * @param[in] bo : the buffer object
 127  * @param[in] device : the device type to get a handle
 128  * @param[in] option : the option to access the buffer object
 129  * @return the handle of the buffer object
 130  */
 131 tbm_bo_handle tbm_bo_map        (tbm_bo bo, int device, int opt);
 132
 133 /**
 134  * @brief unmap the buffer object.
 135  * @param[in] bo : the buffer object
 136  * @return 1 if this function succeeds, otherwise 0.
 137  */
 138 int           tbm_bo_unmap      (tbm_bo bo);
 139
 140 /**
 141  * @brief get the tbm_bo_handle according to the device type.
 142  * @param[in] bo : the buffer object
 143  * @param[in] device : the device type to get a handle
 144  * @return the handle of the buffer object
 145  */
 146 tbm_bo_handle tbm_bo_get_handle (tbm_bo bo, int device);
 147
 148 /**
 149  * @brief export the buffer object
 150  * @param[in] bo : the buffer object
 151  * @return key associated with the buffer object
 152  */
 153 unsigned int  tbm_bo_export     (tbm_bo bo);
 154
 155 /**
 156  * @brief import the buffer object associated with the key.
 157  * @param[in] bufmgr : the buffer manager
 158  * @param[in] key : the key associated with the buffer object
 159  * @return a buffer object
 160  */
 161 tbm_bo        tbm_bo_import     (tbm_bufmgr bufmgr, unsigned int key);
 162
 163 /**
 164  * @brief get the size of a bo.
 165  * @param[in] bo : the buffer object
 166  * @return 1 if this function succeeds, otherwise 0.
 167  */
 168 int           tbm_bo_size       (tbm_bo bo);
 169
 170 /**
 171  * @brief get the state where the buffer object is locked.
 172  * @param[in] bo : the buffer object
 173  * @return 1 if this function succeeds, otherwise 0.
 174  */
 175 int           tbm_bo_locked     (tbm_bo bo);
 176
 177 /**
 178  * @brief swap the buffer object.
 179  * @param[in] bo1 : the buffer object
 180  * @param[in] bo2 : the buffer object
 181  * @return 1 if this function succeeds, otherwise 0.
 182  */
 183 int           tbm_bo_swap       (tbm_bo bo1, tbm_bo bo2);
 184
 185
 186 /* Functions for userdata of bo */
 187 typedef void (*tbm_data_free)(void *);
 188
 189 /**
 190  * @brief add a user_data to the buffer object
 191  * @param[in] bo : the buffer object
 192  * @param[in] key : the key associated with the user_date
 193  * @param[in] data_free_func : the function pointer to free the user_data
 194  * @return 1 if this function succeeds, otherwise 0.
 195  */
 196 int tbm_bo_add_user_data    (tbm_bo bo, unsigned long key, tbm_data_free data_free_func);
 197
 198 /**
 199  * @brief delete the user_data in the buffer object.
 200  * @param[in] bo : the buffer object
 201  * @param[in] key : the key associated with the user_date
 202  * @return 1 if this function succeeds, otherwise 0.
 203  */
 204 int tbm_bo_delete_user_data (tbm_bo bo, unsigned long key);
 205
 206 /**
 207  * @brief set a user_date to the buffer object.
 208  * @param[in] bo : the buffer object
 209  * @param[in] key : the key associated with the user_date
 210  * @param[in] data : a pointer of the user_data
 211  * @return 1 if this function succeeds, otherwise 0.
 212  */
 213 int tbm_bo_set_user_data    (tbm_bo bo, unsigned long key, void* data);
 214
 215 /**
 216  * @brief get a user_date from the buffer object with the key.
 217  * @param[in] bo : the buffer object
 218  * @param[in] key : the key associated with the user_date
 219  * @param[out] data : to get the user data
 220  * @return 1 if this function succeeds, otherwise 0.
 221  */
 222 int tbm_bo_get_user_data    (tbm_bo bo, unsigned long key, void** data);
 223
 224 #ifdef __cplusplus
 225 }
 226 #endif
 227
 228 #endif /* _TBM_BUFMGR_H_ */
 229