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 import the bo data associated with the tdm_fd(prime fd).
 182         * @remarks tbm_fd must be free by user.
 183         * @remarks It must be supported at the backend module. To sharing the tdm_fd(prime fd)
 184         *        among the processes is the essential feature to run the graphic rendering.
 185         * @param[in] bufmgr_data The backend bufmgr data
 186         * @param[in] fd : the tdm_fd(prime fd) associated with the bo data
 187         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 188         * @return pointer of the bo data of the tbm backend.
 189         */
 190         tbm_backend_bo_data *(*bufmgr_import_fd)(tbm_backend_bufmgr_data *bufmgr_data,
 191                                                                         tbm_fd fd, tbm_error_e *error);
 192
 193         /**
 194         * @brief import the bo data associated with the tdm_key.
 195         * @remarks If the backend doesn't support a buffer sharing by tbm key,
 196         *        fucntion pointer must be set to NULL.
 197         * @param[in] bufmgr_data The backend bufmgr data
 198         * @param[in] key : the tdm_key associated with the bo data
 199         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 200         * @return pointer of the bo data of the tbm backend.
 201         */
 202         tbm_backend_bo_data *(*bufmgr_import_key)(tbm_backend_bufmgr_data *bufmgr_data,
 203                                                                                 tbm_key key, tbm_error_e *error);
 204
 205         /* Padding for future extension */
 206         void (*reserved1)(void);
 207         void (*reserved2)(void);
 208         void (*reserved3)(void);
 209         void (*reserved4)(void);
 210         void (*reserved5)(void);
 211         void (*reserved6)(void);
 212 };
 213
 214 /**
 215  * @brief The bo functions for a backend module.
 216  */
 217 struct _tbm_backend_bo_func {
 218         /**
 219         * @brief free the bo data.
 220         * @param[in] bo_data : the bo data of the tbm backend
 221         * @return #TBM_ERROR_NONE if success. Otherwise, error value.
 222         */
 223         void (*bo_free)(tbm_backend_bo_data *bo_data);
 224
 225         /**
 226         * @brief get the size of a bo data.
 227         * @param[in] bo_data : the bo data of the tbm backend
 228         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 229         * @return size if this function succeeds, otherwise 0.
 230         */
 231         int (*bo_get_size)(tbm_backend_bo_data *bo_data, tbm_error_e *error);
 232
 233         /**
 234         * @brief get the tbm memory types
 235         * @param[in] bo_data : the bo data of the tbm backend
 236         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 237         * @see #TBM_BO_FLAGS #tbm_bo_memory_type
 238         * @return tbm flags of memory type is this function succeeds, otherwise 0.
 239         */
 240         tbm_bo_memory_type (*bo_get_memory_types)(tbm_backend_bo_data *bo_data,
 241                                                                                 tbm_error_e *error);
 242
 243         /**
 244         * @brief get the tbm_bo_handle according to the device type.
 245         * @param[in] bo_data : the bo data of the tbm backend
 246         * @param[in] device : the device type to get a handle
 247         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 248         * @return the handle of the bo data
 249         */
 250         tbm_bo_handle (*bo_get_handle)(tbm_backend_bo_data *bo_data,
 251                                                                 tbm_bo_device_type device, tbm_error_e *error);
 252
 253         /**
 254         * @brief map the bo data according to the device type and the option.
 255         * @param[in] bo_data : the bo data of the tbm backend
 256         * @param[in] device : the device type to get a handle
 257         * @param[in] opt : the option to access the bo data
 258         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 259         * @return the handle of the bo data
 260         */
 261         tbm_bo_handle (*bo_map)(tbm_backend_bo_data *bo_data, tbm_bo_device_type device,
 262                                                 tbm_bo_access_option opt, tbm_error_e *error);
 263
 264         /**
 265         * @brief unmap the bo data.
 266         * @param[in] bo_data : the bo data of the tbm backend
 267         * @return #TBM_ERROR_NONE if success. Otherwise, error value.
 268         */
 269         tbm_error_e (*bo_unmap)(tbm_backend_bo_data *bo_data);
 270
 271         /**
 272         * @brief lock the bo data with a device and an opt.
 273         * @param[in] bo_data : the bo data of the tbm backend
 274         * @param[in] device : the device type to get a handle
 275         * @param[in] opt : the option to access the bo data
 276         * @return #TBM_ERROR_NONE if success. Otherwise, error value.
 277         * @remark This function pointer could be null.
 278         */
 279         tbm_error_e (*bo_lock)(tbm_backend_bo_data *bo_data, tbm_bo_device_type device,
 280                                                 tbm_bo_access_option opt);
 281
 282         /**
 283         * @brief unlock the bo data.
 284         * @param[in] bo_data : the bo data of the tbm backend
 285         * @return #TBM_ERROR_NONE if success. Otherwise, error value.
 286         * @remark This function pointer could be null.
 287         */
 288         tbm_error_e (*bo_unlock)(tbm_backend_bo_data *bo_data);
 289
 290         /**
 291         * @brief export the bo data to the tdm_fd(prime fd)
 292         * @remarks tbm_fd must be free by user.
 293         * @remarks It must be supported at the backend module. To sharing the tdm_fd(prime fd)
 294         *        among the processes is the essential feature to run the graphic rendering.
 295         * @param[in] bo_data : the bo data of the tbm backend
 296         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 297         * @return tbm_fd associated with the bo data
 298         */
 299         tbm_fd (*bo_export_fd)(tbm_backend_bo_data *bo_data, tbm_error_e *error);
 300
 301         /**
 302         * @brief export the bo data to the tdm_key
 303         * @remarks If the backend doesn't support a buffer sharing by tbm key,
 304         *        fucntion pointer must be set to NULL.
 305         * @param[in] bo_data : the bo data of the tbm backend
 306         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 307         * @return key associated with the bo data
 308         */
 309         tbm_key (*bo_export_key)(tbm_backend_bo_data *bo_data, tbm_error_e *error);
 310
 311         /* Padding for future extension */
 312         void (*reserved1)(void);
 313         void (*reserved2)(void);
 314         void (*reserved3)(void);
 315         void (*reserved4)(void);
 316         void (*reserved5)(void);
 317         void (*reserved6)(void);
 318 };
 319
 320 /**
 321  * @brief The backend module information of the entry point to initialize a tbm
 322  * backend module.
 323  * @remark
 324  * A backend module @b SHOULD define the global data symbol of which name is
 325  * @b "tbm_backend_module_data". tbm will read this symbol, @b "tbm_backend_module_data",
 326  * at the initial time and call init() function of #tbm_backend_module.
 327  */
 328 typedef struct _tbm_backend_module {
 329         const char *name;           /**< The module name of a backend module */
 330         const char *vendor;         /**< The vendor name of a backend module */
 331         unsigned long abi_version;  /**< The ABI version of a backend module */
 332
 333         /**
 334          * @brief The init function of a backend module
 335          * @param[in] bufmgr A tbm buffer manager object.
 336          * @return The backend module data
 337          * @see tbm_backend_bufmgr_data
 338          */
 339         tbm_backend_bufmgr_data *(*init)(tbm_bufmgr bufmgr, tbm_error_e *error);
 340
 341         /**
 342         * @brief deinitialize the bufmgr private data.
 343         * @param[in] bufmgr_data : The backend module data
 344         */
 345         void (*deinit)(tbm_backend_bufmgr_data *bufmgr_data);
 346 } tbm_backend_module;
 347
 348 #ifdef __cplusplus
 349 extern "C" {
 350 #endif
 351
 352 int                      tbm_backend_bufmgr_query_display_server(tbm_bufmgr bufmgr, tbm_error_e *error);
 353 tbm_backend_bufmgr_func *tbm_backend_bufmgr_alloc_bufmgr_func(tbm_bufmgr bufmgr, tbm_error_e *error);
 354 void                     tbm_backend_bufmgr_free_bufmgr_func(tbm_bufmgr bufmgr, tbm_backend_bufmgr_func *func);
 355 tbm_error_e              tbm_backend_bufmgr_register_bufmgr_func(tbm_bufmgr bufmgr, tbm_backend_bufmgr_func *func);
 356 tbm_backend_bo_func     *tbm_backend_bufmgr_alloc_bo_func(tbm_bufmgr bufmgr, tbm_error_e *error);
 357 void                     tbm_backend_bufmgr_free_bo_func(tbm_bufmgr bufmgr, tbm_backend_bo_func *func);
 358 tbm_error_e              tbm_backend_bufmgr_register_bo_func(tbm_bufmgr bufmgr, tbm_backend_bo_func *func);
 359
 360 #ifdef __cplusplus
 361 }
 362 #endif
 363 #endif                                                  /* _TBM_BACKEND_H_ */