include/tbm_backend.h

   1 /**************************************************************************
   2
   3 libtbm
   4
   5 Copyright 2018 Samsung Electronics co., Ltd. All Rights Reserved.
   6
   7 Contact: SooChan Lim <sc1.lim@samsung.com>,
   8                  Sangjin Lee <lsj119@samsung.com>,
   9                  Boram Park <boram1288.park@samsung.com>,
  10                  Changyeon Lee <cyeon.lee@samsung.com>
  11
  12 Permission is hereby granted, free of charge, to any person obtaining a
  13 copy of this software and associated documentation files (the
  14 "Software"), to deal in the Software without restriction, including
  15 without limitation the rights to use, copy, modify, merge, publish,
  16 distribute, sub license, and/or sell copies of the Software, and to
  17 permit persons to whom the Software is furnished to do so, subject to
  18 the following conditions:
  19
  20 The above copyright notice and this permission notice (including the
  21 next paragraph) shall be included in all copies or substantial portions
  22 of the Software.
  23
  24 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  25 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  26 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
  27 IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR
  28 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  29 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  30 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  31
  32 **************************************************************************/
  33
  34 #ifndef _TBM_BACKEND_H_
  35 #define _TBM_BACKEND_H_
  36
  37 #include <tbm_type_common.h>
  38
  39 /**
  40  * \file tbm_backend.h
  41  * \brief The backend header file for Tizen Buffer Manager
  42  *   This header is for the implementation of the TBM backend module.
  43  *  This backend header is used from the 3.0 version of libtbm and from
  44  *  the 5.0 version of the tizen.
  45  * @code
  46  * #include <tbm_backend.h>
  47  * @endcode
  48  */
  49
  50 #define TBM_BACKEND_ABI_MINOR_MASK          0x0000FFFF
  51 #define TBM_BACKEND_ABI_MAJOR_MASK          0xFFFF0000
  52 #define TBM_BACKEND_GET_ABI_MINOR(v)    ((v) & TBM_BACKEND_ABI_MINOR_MASK)
  53 #define TBM_BACKEND_GET_ABI_MAJOR(v)    (((v) & TBM_BACKEND_ABI_MAJOR_MASK) >> 16)
  54 /*
  55  * ABI versions.  Each version has a major and minor revision.  Modules
  56  * using lower minor revisions must work with servers of a higher minor
  57  * revision.  There is no compatibility between different major revisions.
  58  * Whenever the ABI_MAJOR_VERSION is changed, the others must also be
  59  * changed.  The minor revision mask is 0x0000FFFF and the major revision
  60  * mask is 0xFFFF0000.
  61  */
  62 #define TBM_BACKEND_SET_ABI_VERSION(maj, min) \
  63                 ((((maj) << 16) & TBM_BACKEND_ABI_MAJOR_MASK) | ((min) & TBM_BACKEND_ABI_MINOR_MASK))
  64
  65 #define TBM_BACKEND_ABI_VERSION_1_0 TBM_BACKEND_SET_ABI_VERSION(1, 0)
  66 #define TBM_BACKEND_ABI_VERSION_2_0 TBM_BACKEND_SET_ABI_VERSION(2, 0)
  67 #define TBM_BACKEND_ABI_VERSION_3_0 TBM_BACKEND_SET_ABI_VERSION(3, 0)
  68 #define TBM_BACKEND_ABI_LATEST_VERSION TBM_BACKEND_ABI_VERSION_3_0 /**< the latest version of the tbm backend abi  */
  69
  70 /**
  71  * @brief The backend bufmgr data
  72  * @details
  73  * The init() function of #tbm_backend_module returns the backend module data.
  74  * This handle will be used in #tbm_backend_bufmgr_func.
  75  * @see tbm_backend_module, tbm_backend_bufmgr_func
  76  */
  77 typedef void tbm_backend_bufmgr_data;
  78
  79 /**
  80  * @brief The backend bo data
  81  * @details
  82  * The allocation function and the import function in #tbm_backend_bufmgr_func
  83  * returns the backend bo data. This handle will be used in #tbm_backend_bo_func.
  84  * @see tbm_backend_bufmgr_funce, tbm_backend_bo_func
  85  */
  86 typedef void tbm_backend_bo_data;
  87
  88 /**
  89  * @brief The type definition of the bufmgr functions
  90  */
  91 typedef struct _tbm_backend_bufmgr_func tbm_backend_bufmgr_func;
  92
  93 /**
  94  * @brief The type definition of the bo functions
  95  */
  96 typedef struct _tbm_backend_bo_func tbm_backend_bo_func;
  97
  98 /**
  99  * @brief The bufmgr functions for a backend module.
 100  */
 101 struct _tbm_backend_bufmgr_func {
 102         /**
 103          * @brief Get the capabilities of a buffer manager
 104          * @remarks The backend must support the TBM_BUFMGR_CAPABILITY_SHARE_FD.
 105          *        TBM_BUFMGR_CAPABILITY_SHARE_KEY will help you do debugging to
 106          *        develop the platform because the tbm_key will be the unique
 107          *        identification of the tbm_bo memory in the system.
 108          * @param[in] bufmgr_data The backend module data
 109          * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 110          * @return the capabilities of a backend modul
 111          */
 112         tbm_bufmgr_capability (*bufmgr_get_capabilities)(tbm_backend_bufmgr_data *bufmgr_data,
 113                                                                                 tbm_error_e *error);
 114
 115         /**
 116         * @brief set(bind) the native display
 117         * @param[in] bufmgr_data The backend bufmgr data
 118         * @param[in] native_display : the native display (wl_display in wayland window system)
 119         * @return #TBM_ERROR_NONE if success. Otherwise, error value.
 120         */
 121         tbm_error_e (*bufmgr_bind_native_display)(tbm_backend_bufmgr_data *bufmgr_data,
 122                                                                                         tbm_native_display *native_display);
 123
 124         /**
 125         * @brief get the formats list and the num to be supported by backend.
 126         * @param[in] bufmgr_data The backend bufmgr data
 127         * @param[out] **formats : format array list. it is allocated by backend funtion
 128         * @param[out] *num : the number of the formats to be supported by backend
 129         * @return #TBM_ERROR_NONE if success. Otherwise, error value.
 130         */
 131         tbm_error_e (*bufmgr_get_supported_formats)(tbm_backend_bufmgr_data *bufmgr_data,
 132                                                                                         uint32_t **formats, uint32_t *num);
 133
 134         /**
 135         * @brief get the plane data of the plane_idx according to the format.
 136         * @param[in] bufmgr_data The backend bufmgr data
 137         * @param[in] format : the format of the surface
 138         * @param[in] plane_idx : the index of the plane
 139         * @param[in] width : the width of the surface with the format
 140         * @param[in] height : the height of the surface with the format
 141         * @param[out] size : the size of the plane index
 142         * @param[out] offset : the offset of the plane index at the bo index
 143         * @param[out] pitch : the pitch of the plane index
 144         * @param[out] bo_idx : the bo index of the plane index
 145         * @return #TBM_ERROR_NONE if success. Otherwise, error value.
 146         */
 147         tbm_error_e (*bufmgr_get_plane_data)(tbm_backend_bufmgr_data *bufmgr_data,
 148                                                                         tbm_format format, int plane_idx, int width,
 149                                                                         int height, uint32_t *size, uint32_t *offset,
 150                                                                         uint32_t *pitch, int *bo_idx);
 151
 152         /**
 153         * @brief allocate the bo data of the tbm_backend
 154         * @param[in] bufmgr_data The backend bufmgr data
 155         * @param[in] size : the size of bo data
 156         * @param[in] mem_types : the memory types
 157         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 158         * @return pointer of the bo_data of the tbm backend.
 159         */
 160         tbm_backend_bo_data *(*bufmgr_alloc_bo)(tbm_backend_bufmgr_data *bufmgr_data,
 161                                                                 unsigned int size, tbm_bo_memory_type mem_types,
 162                                                                 tbm_error_e *error);
 163
 164         /**
 165         * @brief allocate the bo data of the bo index according to the format
 166         * @param[in] bufmgr_data The backend bufmgr data
 167         * @param[in] width : the width of the surface with the format
 168         * @param[in] height : the height of the surface with the format
 169         * @param[in] format : the format of the surface
 170         * @param[in] mem_types : the memory types
 171         * @param[in] bo_idx : the bo index of the surface
 172         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 173         * @return pointer of the bo data of the tbm backend.
 174         */
 175         tbm_backend_bo_data *(*bufmgr_alloc_bo_with_format)(tbm_backend_bufmgr_data *bufmgr_data,
 176                                                                                         int format, int bo_idx, int width,
 177                                                                                         int height, tbm_bo_memory_type mem_types,
 178                                                                                         tbm_error_e *error);
 179
 180         /**
 181          * @brief allocate the bo data for GPU which support tiled format
 182          * @param[in] bufmgr_data : The backend bufmgr data
 183          * @param[in] width : the width of surface
 184          * @param[in] height : the height of surface
 185          * @param[in] bpp: bpp of the surface format
 186          * @param[in] format : the format of surface
 187          * @param[in] flags : the flags of memory type
 188          * @param[in] bo_idx : the bo index of the surface
 189          * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 190          * @return pointer of the bo private.
 191          */
 192         tbm_backend_bo_data *(*bufmgr_alloc_bo_with_tiled_format)(tbm_backend_bufmgr_data *bufmgr_data,
 193                                                                                         int width, int height, int bpp, int format,
 194                                                                                         tbm_bo_memory_type flags, int bo_idx,
 195                                                                                         tbm_error_e *error);
 196
 197         /**
 198         * @brief import the bo data associated with the tdm_fd(prime fd).
 199         * @remarks tbm_fd must be free by user.
 200         * @remarks It must be supported at the backend module. To sharing the tdm_fd(prime fd)
 201         *        among the processes is the essential feature to run the graphic rendering.
 202         * @param[in] bufmgr_data The backend bufmgr data
 203         * @param[in] fd : the tdm_fd(prime fd) associated with the bo data
 204         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 205         * @return pointer of the bo data of the tbm backend.
 206         */
 207         tbm_backend_bo_data *(*bufmgr_import_fd)(tbm_backend_bufmgr_data *bufmgr_data,
 208                                                                         tbm_fd fd, tbm_error_e *error);
 209
 210         /**
 211         * @brief import the bo data associated with the tdm_key.
 212         * @remarks If the backend doesn't support a buffer sharing by tbm key,
 213         *        fucntion pointer must be set to NULL.
 214         * @param[in] bufmgr_data The backend bufmgr data
 215         * @param[in] key : the tdm_key associated with the bo data
 216         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 217         * @return pointer of the bo data of the tbm backend.
 218         */
 219         tbm_backend_bo_data *(*bufmgr_import_key)(tbm_backend_bufmgr_data *bufmgr_data,
 220                                                                                 tbm_key key, tbm_error_e *error);
 221
 222         /* Padding for future extension */
 223         void (*reserved1)(void);
 224         void (*reserved2)(void);
 225         void (*reserved3)(void);
 226         void (*reserved4)(void);
 227         void (*reserved5)(void);
 228         void (*reserved6)(void);
 229 };
 230
 231 /**
 232  * @brief The bo functions for a backend module.
 233  */
 234 struct _tbm_backend_bo_func {
 235         /**
 236         * @brief free the bo data.
 237         * @param[in] bo_data : the bo data of the tbm backend
 238         * @return #TBM_ERROR_NONE if success. Otherwise, error value.
 239         */
 240         void (*bo_free)(tbm_backend_bo_data *bo_data);
 241
 242         /**
 243         * @brief get the size of a bo data.
 244         * @param[in] bo_data : the bo data of the tbm backend
 245         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 246         * @return size if this function succeeds, otherwise 0.
 247         */
 248         int (*bo_get_size)(tbm_backend_bo_data *bo_data, tbm_error_e *error);
 249
 250         /**
 251         * @brief get the tbm memory types
 252         * @param[in] bo_data : the bo data of the tbm backend
 253         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 254         * @see #TBM_BO_FLAGS #tbm_bo_memory_type
 255         * @return tbm flags of memory type is this function succeeds, otherwise 0.
 256         */
 257         tbm_bo_memory_type (*bo_get_memory_types)(tbm_backend_bo_data *bo_data,
 258                                                                                 tbm_error_e *error);
 259
 260         /**
 261         * @brief get the tbm_bo_handle according to the device type.
 262         * @param[in] bo_data : the bo data of the tbm backend
 263         * @param[in] device : the device type to get a handle
 264         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 265         * @return the handle of the bo data
 266         */
 267         tbm_bo_handle (*bo_get_handle)(tbm_backend_bo_data *bo_data,
 268                                                                 tbm_bo_device_type device, tbm_error_e *error);
 269
 270         /**
 271         * @brief map the bo data according to the device type and the option.
 272         * @param[in] bo_data : the bo data of the tbm backend
 273         * @param[in] device : the device type to get a handle
 274         * @param[in] opt : the option to access the bo data
 275         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 276         * @return the handle of the bo data
 277         */
 278         tbm_bo_handle (*bo_map)(tbm_backend_bo_data *bo_data, tbm_bo_device_type device,
 279                                                 tbm_bo_access_option opt, tbm_error_e *error);
 280
 281         /**
 282         * @brief unmap the bo data.
 283         * @param[in] bo_data : the bo data of the tbm backend
 284         * @return #TBM_ERROR_NONE if success. Otherwise, error value.
 285         */
 286         tbm_error_e (*bo_unmap)(tbm_backend_bo_data *bo_data);
 287
 288         /**
 289         * @brief lock the bo data with a device and an opt.
 290         * @param[in] bo_data : the bo data of the tbm backend
 291         * @param[in] device : the device type to get a handle
 292         * @param[in] opt : the option to access the bo data
 293         * @return #TBM_ERROR_NONE if success. Otherwise, error value.
 294         * @remark This function pointer could be null.
 295         */
 296         tbm_error_e (*bo_lock)(tbm_backend_bo_data *bo_data, tbm_bo_device_type device,
 297                                                 tbm_bo_access_option opt);
 298
 299         /**
 300         * @brief unlock the bo data.
 301         * @param[in] bo_data : the bo data of the tbm backend
 302         * @return #TBM_ERROR_NONE if success. Otherwise, error value.
 303         * @remark This function pointer could be null.
 304         */
 305         tbm_error_e (*bo_unlock)(tbm_backend_bo_data *bo_data);
 306
 307         /**
 308         * @brief export the bo data to the tdm_fd(prime fd)
 309         * @remarks tbm_fd must be free by user.
 310         * @remarks It must be supported at the backend module. To sharing the tdm_fd(prime fd)
 311         *        among the processes is the essential feature to run the graphic rendering.
 312         * @param[in] bo_data : the bo data of the tbm backend
 313         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 314         * @return tbm_fd associated with the bo data
 315         */
 316         tbm_fd (*bo_export_fd)(tbm_backend_bo_data *bo_data, tbm_error_e *error);
 317
 318         /**
 319         * @brief export the bo data to the tdm_key
 320         * @remarks If the backend doesn't support a buffer sharing by tbm key,
 321         *        fucntion pointer must be set to NULL.
 322         * @param[in] bo_data : the bo data of the tbm backend
 323         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 324         * @return key associated with the bo data
 325         */
 326         tbm_key (*bo_export_key)(tbm_backend_bo_data *bo_data, tbm_error_e *error);
 327
 328         /* Padding for future extension */
 329         void (*reserved1)(void);
 330         void (*reserved2)(void);
 331         void (*reserved3)(void);
 332         void (*reserved4)(void);
 333         void (*reserved5)(void);
 334         void (*reserved6)(void);
 335 };
 336
 337 /**
 338  * @brief The backend module information of the entry point to initialize a tbm
 339  * backend module.
 340  * @remark
 341  * A backend module @b SHOULD define the global data symbol of which name is
 342  * @b "tbm_backend_module_data". tbm will read this symbol, @b "tbm_backend_module_data",
 343  * at the initial time and call init() function of #tbm_backend_module.
 344  */
 345 typedef struct _tbm_backend_module {
 346         const char *name;           /**< The module name of a backend module */
 347         const char *vendor;         /**< The vendor name of a backend module */
 348         unsigned long abi_version;  /**< The ABI version of a backend module */
 349
 350         /**
 351          * @brief The init function of a backend module
 352          * @param[in] bufmgr A tbm buffer manager object.
 353          * @return The backend module data
 354          * @see tbm_backend_bufmgr_data
 355          */
 356         tbm_backend_bufmgr_data *(*init)(tbm_bufmgr bufmgr, tbm_error_e *error);
 357
 358         /**
 359         * @brief deinitialize the bufmgr private data.
 360         * @param[in] bufmgr_data : The backend module data
 361         */
 362         void (*deinit)(tbm_backend_bufmgr_data *bufmgr_data);
 363 } tbm_backend_module;
 364
 365 #ifdef __cplusplus
 366 extern "C" {
 367 #endif
 368
 369 int                      tbm_backend_bufmgr_query_display_server(tbm_bufmgr bufmgr, tbm_error_e *error);
 370 tbm_backend_bufmgr_func *tbm_backend_bufmgr_alloc_bufmgr_func(tbm_bufmgr bufmgr, tbm_error_e *error);
 371 void                     tbm_backend_bufmgr_free_bufmgr_func(tbm_bufmgr bufmgr, tbm_backend_bufmgr_func *func);
 372 tbm_error_e              tbm_backend_bufmgr_register_bufmgr_func(tbm_bufmgr bufmgr, tbm_backend_bufmgr_func *func);
 373 tbm_backend_bo_func     *tbm_backend_bufmgr_alloc_bo_func(tbm_bufmgr bufmgr, tbm_error_e *error);
 374 void                     tbm_backend_bufmgr_free_bo_func(tbm_bufmgr bufmgr, tbm_backend_bo_func *func);
 375 tbm_error_e              tbm_backend_bufmgr_register_bo_func(tbm_bufmgr bufmgr, tbm_backend_bo_func *func);
 376
 377 #ifdef __cplusplus
 378 }
 379 #endif
 380 #endif                                                  /* _TBM_BACKEND_H_ */