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,
 232                                 tbm_format format);
 233
 234         /**
 235         * @brief get the plane data of the surface.
 236         * @param[in] surface : the surface
 237         * @param[in] width : the width of the surface
 238         * @param[in] height : the height of the surface
 239         * @param[in] format : the format of the surface
 240         * @param[in] plane_idx : the format of the surface
 241         * @param[out] size : the size of the plane
 242         * @param[out] offset : the offset of the plane
 243         * @param[out] pitch : the pitch of the plane
 244         * @param[out] bo_idx : the bo index of the plane
 245         * @return 1 if this function succeeds, otherwise 0.
 246         */
 247         int (*surface_get_plane_data)(tbm_surface_h surface, int width, int height,
 248                                       tbm_format format, int plane_idx, uint32_t *size, uint32_t *offset,
 249                                       uint32_t *pitch, int *bo_idx);
 250
 251         /**
 252         * @brief import the buffer object associated with the prime fd.
 253         * @remarks tbm_fd must be free by user.
 254         * @remarks If the backend doesn't support a buffer sharing by tbm fd,
 255                         fucntion pointer must be set to NULL.
 256         * @param[in] bo : the buffer object
 257         * @param[in] fd : the prime fd associated with the buffer object
 258         * @return pointer of the bo private.
 259         */
 260         void *(*bo_import_fd)(tbm_bo bo, tbm_fd fd);
 261
 262         /**
 263         * @brief export the buffer object
 264         * @remarks tbm_fd must be free by user.
 265         * @remarks If the backend doesn't support a buffer sharing by tbm fd,
 266                         fucntion pointer must be set to NULL.
 267         * @param[in] bo : the buffer object
 268         * @return tbm_fd associated with the buffer object
 269         */
 270         tbm_fd (*bo_export_fd)(tbm_bo bo);
 271
 272         /* version 2.0 dosen't need to backend function fd_to_handle */
 273         /**
 274         * @brief get the tbm_bo_handle according to the device type and the prime fd.
 275         * @param[in] bufmgr : the tizen buffer manager
 276         * @param[in] fd : the prime fd associated with the buffer object
 277         * @param[in] device : the option to access the buffer object
 278         * @return the handle of the buffer object
 279         */
 280         tbm_bo_handle(*fd_to_handle)(tbm_bufmgr bufmgr, tbm_fd fd, int device);
 281
 282         /* version 2.0 dosen't need to backend function surface_get_num_bos */
 283         /**
 284         * @brief get the num of bos with a format.
 285         * @param[in] format : the format of the surface
 286         * @return num of the bos if this function succeeds, otherwise 0.
 287         */
 288         int (*surface_get_num_bos)(tbm_format format);
 289
 290         /**
 291         * @brief get the tbm flags of memory type
 292         * @param[in] bo : the buffer object
 293         * @see #TBM_BO_FLAGS
 294         * @return tbm flags of memory type is this function succeeds, otherwise 0.
 295         */
 296         int (*bo_get_flags)(tbm_bo bo);
 297
 298         /**
 299         * @brief get the tbm flags of memory type
 300         * @param[in] bo : the buffer object
 301         * @see #TBM_BO_FLAGS
 302         * @return tbm flags of memory type is this function succeeds, otherwise 0.
 303         */
 304         int (*bufmgr_bind_native_display)(tbm_bufmgr bufmgr, void *NativeDisplay);
 305
 306         /**
 307         * @brief get the plane data of the surface.
 308         * @param[in] width : the width of the surface
 309         * @param[in] height : the height of the surface
 310         * @param[in] format : the format of the surface
 311         * @param[in] plane_idx : the format of the surface
 312         * @param[out] size : the size of the plane
 313         * @param[out] offset : the offset of the plane
 314         * @param[out] pitch : the pitch of the plane
 315         * @param[out] bo_idx : the bo index of the plane
 316         * @return 1 if this function succeeds, otherwise 0.
 317         */
 318         int (*surface_get_plane_data2)(int width, int height,
 319                                        tbm_format format, int plane_idx, uint32_t *size, uint32_t *offset,
 320                                        uint32_t *pitch, int *bo_idx);
 321
 322         /* Padding for future extension */
 323         void (*reserved1)(void);
 324         void (*reserved2)(void);
 325         void (*reserved3)(void);
 326         void (*reserved4)(void);
 327         void (*reserved5)(void);
 328         void (*reserved6)(void);
 329 };
 330
 331 /**
 332  * @brief tbm module information
 333  *  data type for the module information
 334  */
 335 typedef struct {
 336         const char *modname;               /**< name of module, e.g. "foo" */
 337         const char *vendor;                        /**< vendor specific string */
 338         unsigned long abiversion;          /**< ABI version */
 339 } TBMModuleVersionInfo;
 340
 341 typedef int (*ModuleInitProc) (tbm_bufmgr, int);
 342
 343 #define MODULEINITPPROTO(func) int func(tbm_bufmgr, int) /**< prototype for init symbol of bakcend module */
 344
 345 /**
 346  * @brief tbm module data
 347  *  data type for the entry point of the backend module
 348  */
 349 typedef struct {
 350         TBMModuleVersionInfo *vers;     /**< tbm module informtaion */
 351         ModuleInitProc init;            /**< init function of a backend module */
 352 } TBMModuleData;
 353
 354 tbm_bufmgr_backend tbm_backend_alloc(void);
 355 void tbm_backend_free(tbm_bufmgr_backend backend);
 356 int tbm_backend_init(tbm_bufmgr bufmgr, tbm_bufmgr_backend backend);
 357
 358 void *tbm_backend_get_bufmgr_priv(tbm_bo bo);
 359 void *tbm_backend_get_priv_from_bufmgr(tbm_bufmgr bufmgr);
 360 void *tbm_backend_get_bo_priv(tbm_bo bo);
 361 int tbm_backend_is_display_server(void);
 362
 363 #endif                                                  /* _TBM_BUFMGR_BACKEND_H_ */