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 /* TBM_CACHE */
  67 #define TBM_CACHE_INV       0x01 /**< cache invalidate  */
  68 #define TBM_CACHE_CLN       0x02 /**< cache clean */
  69 #define TBM_CACHE_ALL       0x10 /**< cache all */
  70 #define TBM_CACHE_FLUSH     (TBM_CACHE_INV|TBM_CACHE_CLN) /**< cache flush  */
  71 #define TBM_CACHE_FLUSH_ALL (TBM_CACHE_FLUSH|TBM_CACHE_ALL)     /**< cache flush all */
  72
  73 /*  TBM flag for cache control and lock control */
  74 /**
  75  * TBM_CACHE_CTRL_BACKEND indicates that the backend control the cache coherency.
  76  */
  77 #define TBM_CACHE_CTRL_BACKEND    (1 << 0)
  78
  79 /**
  80  * TBM_LOCK_CTRL_BACKEND indicates  that the backend control the lock of bos.
  81  */
  82 #define TBM_LOCK_CTRL_BACKEND    (1 << 1)
  83
  84 typedef struct _tbm_bufmgr_backend *tbm_bufmgr_backend;
  85
  86 /**
  87  * @brief TBM backend functions
  88  *  the set of function pointers for the backend module of TBM.
  89  */
  90 struct _tbm_bufmgr_backend {
  91         int flags;
  92
  93         void *priv;     /**< bufmgr private */
  94
  95         /**
  96     * @brief deinitialize the bufmgr private.
  97     * @param[in] bufmgr : the private of the bufmgr
  98     * @return 1 if this function succeeds, otherwise 0.
  99     */
 100         void (*bufmgr_deinit) (void *priv);
 101
 102         /**
 103     * @brief get the size of a bo.
 104     * @param[in] bo : the buffer object
 105     * @return 1 if this function succeeds, otherwise 0.
 106     */
 107         int (*bo_size) (tbm_bo bo);
 108
 109         /**
 110     * @brief allocate the buffer object
 111     * @param[in] bo : the buffer object
 112     * @param[in] size : the size of buffer object
 113     * @param[in] flags : the flags of memory type
 114     * @return pointer of the bo private.
 115     */
 116         void *(*bo_alloc) (tbm_bo bo, int size, int flags);
 117
 118         /**
 119     * @brief free the buffer object.
 120     * @param[in] bo : the buffer object
 121     */
 122         void (*bo_free) (tbm_bo bo);
 123
 124         /**
 125     * @brief import the buffer object associated with the key.
 126     * @remarks If the backend doesn't support a buffer sharing by tbm key,
 127                         fucntion pointer must be set to NULL.
 128     * @param[in] bo : the buffer object
 129     * @param[in] key : the key associated with the buffer object
 130     * @return pointer of the bo private.
 131     */
 132         void *(*bo_import) (tbm_bo bo, unsigned int key);
 133
 134         /**
 135     * @brief export the buffer object
 136     * @remarks If the backend doesn't support a buffer sharing by tbm key,
 137                         fucntion pointer must be set to NULL.
 138     * @param[in] bo : the buffer object
 139     * @return key associated with the buffer object
 140     */
 141         unsigned int (*bo_export) (tbm_bo bo);
 142
 143         /**
 144     * @brief get the tbm_bo_handle according to the device type.
 145     * @param[in] bo : the buffer object
 146     * @param[in] device : the device type to get a handle
 147     * @return the handle of the buffer object
 148     */
 149          tbm_bo_handle(*bo_get_handle) (tbm_bo bo, int device);
 150
 151         /**
 152     * @brief map the buffer object according to the device type and the option.
 153     * @param[in] bo : the buffer object
 154     * @param[in] device : the device type to get a handle
 155     * @param[in] option : the option to access the buffer object
 156     * @return the handle of the buffer object
 157     */
 158          tbm_bo_handle(*bo_map) (tbm_bo bo, int device, int opt);
 159
 160         /**
 161     * @brief unmap the buffer object.
 162     * @param[in] bo : the buffer object
 163     * @return 1 if this function succeeds, otherwise 0.
 164     */
 165         int (*bo_unmap) (tbm_bo bo);
 166
 167         /**
 168     * @brief flush the cache of the buffer object.
 169     * @param[in] bo : the buffer object
 170     * @param[in] flags : the flags of cache flush type
 171     * @return 1 if this function succeeds, otherwise 0.
 172     */
 173         int (*bo_cache_flush) (tbm_bo bo, int flags);
 174
 175         /**
 176     * @brief get the global key associated with the buffer object.
 177     * @param[in] bo : the buffer object
 178     * @return global key associated with the buffer object.
 179     */
 180         int (*bo_get_global_key) (tbm_bo bo);
 181
 182         /**
 183     * @brief lock the buffer object.
 184     * @param[in] bo : the buffer object
 185     * @return 1 if this function succeeds, otherwise 0.
 186     * @remark This function pointer could be null. (default: use the tizen global lock)
 187     */
 188         int (*bo_lock) (tbm_bo bo);
 189
 190         /**
 191     * @brief unlock the buffer object.
 192     * @param[in] bo : the buffer object
 193     * @return 1 if this function succeeds, otherwise 0.
 194     * @remark This function pointer could be null. (default: use the tizen global lock)
 195     */
 196         int (*bo_unlock) (tbm_bo bo);
 197
 198         /**
 199     * @brief lock the buffer object with a device and an opt.
 200     * @param[in] bo : the buffer object
 201     * @param[in] device : the device type to get a handle
 202     * @param[in] option : the option to access the buffer object
 203     * @return 1 if this function succeeds, otherwise 0.
 204     * @remark This function pointer could be null. (default: use the tizen global lock)
 205     */
 206         int (*bo_lock2) (tbm_bo bo, int device, int opt);
 207
 208         /**
 209     * @brief query the formats list and the num to be supported by backend.
 210     * @param[out] *formats : format array list. this array has to be allocated by backend funtion
 211     * @param[out] *num : the number of the formats to be supported by backend
 212     * @return 1 if this function succeeds, otherwise 0.
 213     */
 214         int (*surface_supported_format) (uint32_t ** formats, uint32_t * num);
 215
 216         /**
 217     * @brief get the size of the surface with a format.
 218     * @param[in] surface : the surface
 219     * @param[in] width : the width of the surface
 220     * @param[in] height : the height of the surface
 221     * @param[in] format : the format of the surface
 222     * @return size of the surface if this function succeeds, otherwise 0.
 223     */
 224         int (*surface_get_size) (tbm_surface_h surface, int width, int height, tbm_format format);
 225
 226         /**
 227     * @brief get the plane data of the surface.
 228     * @param[in] surface : the surface
 229     * @param[in] width : the width of the surface
 230     * @param[in] height : the height of the surface
 231     * @param[in] format : the format of the surface
 232     * @param[in] plane_idx : the format of the surface
 233     * @param[out] size : the size of the plane
 234     * @param[out] offset : the offset of the plane
 235     * @param[out] pitch : the pitch of the plane
 236     * @param[out] bo_idx : the bo index of the plane
 237     * @return 1 if this function succeeds, otherwise 0.
 238     */
 239         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);
 240
 241         /**
 242     * @brief import the buffer object associated with the prime fd.
 243     * @remarks tbm_fd must be free by user.
 244     * @remarks If the backend doesn't support a buffer sharing by tbm fd,
 245                         fucntion pointer must be set to NULL.
 246     * @param[in] bo : the buffer object
 247     * @param[in] fd : the prime fd associated with the buffer object
 248     * @return pointer of the bo private.
 249     */
 250         void *(*bo_import_fd) (tbm_bo bo, tbm_fd fd);
 251
 252         /**
 253     * @brief export the buffer object
 254     * @remarks tbm_fd must be free by user.
 255     * @remarks If the backend doesn't support a buffer sharing by tbm fd,
 256                         fucntion pointer must be set to NULL.
 257     * @param[in] bo : the buffer object
 258     * @return tbm_fd associated with the buffer object
 259     */
 260          tbm_fd(*bo_export_fd) (tbm_bo bo);
 261
 262         /**
 263     * @brief get the tbm_bo_handle according to the device type and the prime fd.
 264     * @param[in] bufmgr : the tizen buffer manager
 265     * @param[in] fd : the prime fd associated with the buffer object
 266     * @param[in] device : the option to access the buffer object
 267     * @return the handle of the buffer object
 268     */
 269          tbm_bo_handle(*fd_to_handle) (tbm_bufmgr bufmgr, tbm_fd fd, int device);
 270
 271         /**
 272     * @brief get the num of bos with a format.
 273     * @param[in] format : the format of the surface
 274     * @return num of the bos if this function succeeds, otherwise 0.
 275     */
 276         int (*surface_get_num_bos) (tbm_format format);
 277
 278         /**
 279     * @brief get the tbm flags of memory type
 280     * @param[in] bo : the buffer object
 281     * @see #TBM_BO_FLAGS
 282     * @return tbm flags of memory type is this function succeeds, otherwise 0.
 283     */
 284         int (*bo_get_flags) (tbm_bo bo);
 285
 286         /* Padding for future extension */
 287         void (*reserved1) (void);
 288         void (*reserved2) (void);
 289         void (*reserved3) (void);
 290         void (*reserved4) (void);
 291         void (*reserved5) (void);
 292         void (*reserved6) (void);
 293 };
 294
 295 /**
 296  * @brief tbm module information
 297  *  data type for the module information
 298  */
 299 typedef struct {
 300         const char *modname;               /**< name of module, e.g. "foo" */
 301         const char *vendor;                        /**< vendor specific string */
 302         unsigned long abiversion;          /**< ABI version */
 303 } TBMModuleVersionInfo;
 304
 305 typedef int (*ModuleInitProc) (tbm_bufmgr, int);
 306
 307 #define MODULEINITPPROTO(func) int func(tbm_bufmgr, int) /**< prototype for init symbol of bakcend module */
 308
 309 /**
 310  * @brief tbm module data
 311  *  data type for the entry point of the backend module
 312  */
 313 typedef struct {
 314         TBMModuleVersionInfo *vers;     /**< tbm module informtaion */
 315         ModuleInitProc init;            /**< init function of a backend module */
 316 } TBMModuleData;
 317
 318 tbm_bufmgr_backend tbm_backend_alloc(void);
 319 void tbm_backend_free(tbm_bufmgr_backend backend);
 320 int tbm_backend_init(tbm_bufmgr bufmgr, tbm_bufmgr_backend backend);
 321
 322 void *tbm_backend_get_bufmgr_priv(tbm_bo bo);
 323 void *tbm_backend_get_priv_from_bufmgr(tbm_bufmgr bufmgr);
 324 void *tbm_backend_get_bo_priv(tbm_bo bo);
 325
 326 #endif                                                  /* _TBM_BUFMGR_BACKEND_H_ */