src/tbm_bufmgr_backend.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 Boram Park <boram1288.park@samsung.com>, Changyeon Lee <cyeon.lee@samsung.com>
   9
  10 Permission is hereby granted, free of charge, to any person obtaining a
  11 copy of this software and associated documentation files (the
  12 "Software"), to deal in the Software without restriction, including
  13 without limitation the rights to use, copy, modify, merge, publish,
  14 distribute, sub license, and/or sell copies of the Software, and to
  15 permit persons to whom the Software is furnished to do so, subject to
  16 the following conditions:
  17
  18 The above copyright notice and this permission notice (including the
  19 next paragraph) shall be included in all copies or substantial portions
  20 of the Software.
  21
  22 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  23 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  24 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
  25 IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR
  26 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  27 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  28 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  29
  30 **************************************************************************/
  31
  32 /*
  33  * This file is referenced by the xf86Module.h in xorg server.
  34  */
  35
  36 #ifndef _TBM_BUFMGR_BACKEND_H_
  37 #define _TBM_BUFMGR_BACKEND_H_
  38
  39 #include <tbm_bufmgr.h>
  40 #include <pthread.h>
  41
  42 /**
  43  * \file tbm_bufmgr_backend.h
  44  * \brief backend header for Tizen Buffer Manager
  45  *   This header is for the implementation of the TBM backend module.
  46  */
  47
  48 #define ABI_MINOR_MASK          0x0000FFFF
  49 #define ABI_MAJOR_MASK          0xFFFF0000
  50 #define GET_ABI_MINOR(v)        ((v) & ABI_MINOR_MASK)
  51 #define GET_ABI_MAJOR(v)        (((v) & ABI_MAJOR_MASK) >> 16)
  52
  53 /*
  54  * ABI versions.  Each version has a major and minor revision.  Modules
  55  * using lower minor revisions must work with servers of a higher minor
  56  * revision.  There is no compatibility between different major revisions.
  57  * Whenever the ABI_ANSIC_VERSION is changed, the others must also be
  58  * changed.  The minor revision mask is 0x0000FFFF and the major revision
  59  * mask is 0xFFFF0000.
  60  */
  61 #define SET_ABI_VERSION(maj, min) \
  62                 ((((maj) << 16) & ABI_MAJOR_MASK) | ((min) & ABI_MINOR_MASK))
  63
  64 #define TBM_ABI_VERSION SET_ABI_VERSION(1, 1) /**< current abi vertion  */
  65
  66 /* unneeded version 2.0 */
  67 /* TBM_CACHE */
  68 #define TBM_CACHE_INV       0x01 /**< cache invalidate  */
  69 #define TBM_CACHE_CLN       0x02 /**< cache clean */
  70 #define TBM_CACHE_ALL       0x10 /**< cache all */
  71 #define TBM_CACHE_FLUSH     (TBM_CACHE_INV|TBM_CACHE_CLN) /**< cache flush  */
  72 #define TBM_CACHE_FLUSH_ALL (TBM_CACHE_FLUSH|TBM_CACHE_ALL)     /**< cache flush all */
  73
  74 /*  TBM flag for cache control and lock control */
  75 /**
  76  * TBM_CACHE_CTRL_BACKEND indicates that the backend control the cache coherency.
  77  */
  78 #define TBM_CACHE_CTRL_BACKEND    (1 << 0)
  79
  80 /**
  81  * TBM_LOCK_CTRL_BACKEND indicates  that the backend control the lock of bos.
  82  */
  83 #define TBM_LOCK_CTRL_BACKEND    (1 << 1)
  84 /* unneeded version 2.0 */
  85
  86 #define TBM_USE_2_0_BACKEND      (1 << 2)
  87
  88 typedef struct _tbm_bufmgr_backend *tbm_bufmgr_backend;
  89
  90 /**
  91  * @brief TBM backend functions
  92  *  the set of function pointers for the backend module of TBM.
  93  */
  94 struct _tbm_bufmgr_backend {
  95         int flags;
  96
  97         void *priv;     /**< bufmgr private */
  98
  99         /**
 100     * @brief deinitialize the bufmgr private.
 101     * @param[in] bufmgr : the private of the bufmgr
 102     * @return 1 if this function succeeds, otherwise 0.
 103     */
 104         void (*bufmgr_deinit) (void *priv);
 105
 106         /**
 107     * @brief get the size of a bo.
 108     * @param[in] bo : the buffer object
 109     * @return 1 if this function succeeds, otherwise 0.
 110     */
 111         int (*bo_size) (tbm_bo bo);
 112
 113         /**
 114     * @brief allocate the buffer object
 115     * @param[in] bo : the buffer object
 116     * @param[in] size : the size of buffer object
 117     * @param[in] flags : the flags of memory type
 118     * @return pointer of the bo private.
 119     */
 120         void *(*bo_alloc) (tbm_bo bo, int size, int flags);
 121
 122         /**
 123     * @brief free the buffer object.
 124     * @param[in] bo : the buffer object
 125     */
 126         void (*bo_free) (tbm_bo bo);
 127
 128         /**
 129     * @brief import the buffer object associated with the key.
 130     * @remarks If the backend doesn't support a buffer sharing by tbm key,
 131                         fucntion pointer must be set to NULL.
 132     * @param[in] bo : the buffer object
 133     * @param[in] key : the key associated with the buffer object
 134     * @return pointer of the bo private.
 135     */
 136         void *(*bo_import) (tbm_bo bo, unsigned int key);
 137
 138         /**
 139     * @brief export the buffer object
 140     * @remarks If the backend doesn't support a buffer sharing by tbm key,
 141                         fucntion pointer must be set to NULL.
 142     * @param[in] bo : the buffer object
 143     * @return key associated with the buffer object
 144     */
 145         unsigned int (*bo_export) (tbm_bo bo);
 146
 147         /**
 148     * @brief get the tbm_bo_handle according to the device type.
 149     * @param[in] bo : the buffer object
 150     * @param[in] device : the device type to get a handle
 151     * @return the handle of the buffer object
 152     */
 153          tbm_bo_handle(*bo_get_handle) (tbm_bo bo, int device);
 154
 155         /**
 156     * @brief map the buffer object according to the device type and the option.
 157     * @param[in] bo : the buffer object
 158     * @param[in] device : the device type to get a handle
 159     * @param[in] option : the option to access the buffer object
 160     * @return the handle of the buffer object
 161     */
 162          tbm_bo_handle(*bo_map) (tbm_bo bo, int device, int opt);
 163
 164         /**
 165     * @brief unmap the buffer object.
 166     * @param[in] bo : the buffer object
 167     * @return 1 if this function succeeds, otherwise 0.
 168     */
 169         int (*bo_unmap) (tbm_bo bo);
 170
 171         /* version 2.0 dosen't need to backend function bo_cache_flush */
 172         /**
 173     * @brief flush the cache of the buffer object.
 174     * @param[in] bo : the buffer object
 175     * @param[in] flags : the flags of cache flush type
 176     * @return 1 if this function succeeds, otherwise 0.
 177     */
 178         int (*bo_cache_flush) (tbm_bo bo, int flags);
 179
 180         /* version 2.0 dosen't need to backend function bo_get_global_key */
 181         /**
 182     * @brief get the global key associated with the buffer object.
 183     * @param[in] bo : the buffer object
 184     * @return global key associated with the buffer object.
 185     */
 186         int (*bo_get_global_key) (tbm_bo bo);
 187
 188         /**
 189     * @brief lock the buffer object.
 190     * @param[in] bo : the buffer object
 191     * @return 1 if this function succeeds, otherwise 0.
 192     * @remark This function pointer could be null. (default: use the tizen global lock)
 193     */
 194         int (*bo_lock) (tbm_bo bo);
 195
 196         /**
 197     * @brief unlock the buffer object.
 198     * @param[in] bo : the buffer object
 199     * @return 1 if this function succeeds, otherwise 0.
 200     * @remark This function pointer could be null. (default: use the tizen global lock)
 201     */
 202         int (*bo_unlock) (tbm_bo bo);
 203
 204         /**
 205     * @brief lock the buffer object with a device and an opt.
 206     * @param[in] bo : the buffer object
 207     * @param[in] device : the device type to get a handle
 208     * @param[in] option : the option to access the buffer object
 209     * @return 1 if this function succeeds, otherwise 0.
 210     * @remark This function pointer could be null. (default: use the tizen global lock)
 211     */
 212         int (*bo_lock2) (tbm_bo bo, int device, int opt);
 213
 214         /**
 215     * @brief query the formats list and the num to be supported by backend.
 216     * @param[out] *formats : format array list. this array has to be allocated by backend funtion
 217     * @param[out] *num : the number of the formats to be supported by backend
 218     * @return 1 if this function succeeds, otherwise 0.
 219     */
 220         int (*surface_supported_format) (uint32_t ** formats, uint32_t * num);
 221
 222         /* version 2.0 dosen't need to backend function surface get size*/
 223         /**
 224     * @brief get the size of the surface with a format.
 225     * @param[in] surface : the surface
 226     * @param[in] width : the width of the surface
 227     * @param[in] height : the height of the surface
 228     * @param[in] format : the format of the surface
 229     * @return size of the surface if this function succeeds, otherwise 0.
 230     */
 231         int (*surface_get_size) (tbm_surface_h surface, int width, int height, tbm_format format);
 232
 233         /**
 234     * @brief get the plane data of the surface.
 235     * @param[in] surface : the surface
 236     * @param[in] width : the width of the surface
 237     * @param[in] height : the height of the surface
 238     * @param[in] format : the format of the surface
 239     * @param[in] plane_idx : the format of the surface
 240     * @param[out] size : the size of the plane
 241     * @param[out] offset : the offset of the plane
 242     * @param[out] pitch : the pitch of the plane
 243     * @param[out] bo_idx : the bo index of the plane
 244     * @return 1 if this function succeeds, otherwise 0.
 245     */
 246         int (*surface_get_plane_data) (tbm_surface_h surface, int width, int height, tbm_format format, int plane_idx, uint32_t * size, uint32_t * offset, uint32_t * pitch, int *bo_idx);
 247
 248         /**
 249     * @brief import the buffer object associated with the prime fd.
 250     * @remarks tbm_fd must be free by user.
 251     * @remarks If the backend doesn't support a buffer sharing by tbm fd,
 252                         fucntion pointer must be set to NULL.
 253     * @param[in] bo : the buffer object
 254     * @param[in] fd : the prime fd associated with the buffer object
 255     * @return pointer of the bo private.
 256     */
 257         void *(*bo_import_fd) (tbm_bo bo, tbm_fd fd);
 258
 259         /**
 260     * @brief export the buffer object
 261     * @remarks tbm_fd must be free by user.
 262     * @remarks If the backend doesn't support a buffer sharing by tbm fd,
 263                         fucntion pointer must be set to NULL.
 264     * @param[in] bo : the buffer object
 265     * @return tbm_fd associated with the buffer object
 266     */
 267          tbm_fd(*bo_export_fd) (tbm_bo bo);
 268
 269
 270         /* version 2.0 dosen't need to backend function fd_to_handle */
 271         /**
 272     * @brief get the tbm_bo_handle according to the device type and the prime fd.
 273     * @param[in] bufmgr : the tizen buffer manager
 274     * @param[in] fd : the prime fd associated with the buffer object
 275     * @param[in] device : the option to access the buffer object
 276     * @return the handle of the buffer object
 277     */
 278          tbm_bo_handle(*fd_to_handle) (tbm_bufmgr bufmgr, tbm_fd fd, int device);
 279
 280         /**
 281     * @brief get the num of bos with a format.
 282     * @param[in] format : the format of the surface
 283     * @return num of the bos if this function succeeds, otherwise 0.
 284     */
 285         int (*surface_get_num_bos) (tbm_format format);
 286
 287         /**
 288     * @brief get the tbm flags of memory type
 289     * @param[in] bo : the buffer object
 290     * @see #TBM_BO_FLAGS
 291     * @return tbm flags of memory type is this function succeeds, otherwise 0.
 292     */
 293         int (*bo_get_flags) (tbm_bo bo);
 294
 295         /* Padding for future extension */
 296         void (*reserved1) (void);
 297         void (*reserved2) (void);
 298         void (*reserved3) (void);
 299         void (*reserved4) (void);
 300         void (*reserved5) (void);
 301         void (*reserved6) (void);
 302 };
 303
 304 /**
 305  * @brief tbm module information
 306  *  data type for the module information
 307  */
 308 typedef struct {
 309         const char *modname;               /**< name of module, e.g. "foo" */
 310         const char *vendor;                        /**< vendor specific string */
 311         unsigned long abiversion;          /**< ABI version */
 312 } TBMModuleVersionInfo;
 313
 314 typedef int (*ModuleInitProc) (tbm_bufmgr, int);
 315
 316 #define MODULEINITPPROTO(func) int func(tbm_bufmgr, int) /**< prototype for init symbol of bakcend module */
 317
 318 /**
 319  * @brief tbm module data
 320  *  data type for the entry point of the backend module
 321  */
 322 typedef struct {
 323         TBMModuleVersionInfo *vers;     /**< tbm module informtaion */
 324         ModuleInitProc init;            /**< init function of a backend module */
 325 } TBMModuleData;
 326
 327 tbm_bufmgr_backend tbm_backend_alloc(void);
 328 void tbm_backend_free(tbm_bufmgr_backend backend);
 329 int tbm_backend_init(tbm_bufmgr bufmgr, tbm_bufmgr_backend backend);
 330
 331 void *tbm_backend_get_bufmgr_priv(tbm_bo bo);
 332 void *tbm_backend_get_priv_from_bufmgr(tbm_bufmgr bufmgr);
 333 void *tbm_backend_get_bo_priv(tbm_bo bo);
 334
 335 #endif                                                  /* _TBM_BUFMGR_BACKEND_H_ */