src/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_ANSIC_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 module 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          * @param[in] bufmgr_data The backend module data
 105          * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 106          * @return the capabilities of a backend modul
 107          */
 108         tbm_bufmgr_capability (*bufmgr_get_capabilities)(tbm_backend_bufmgr_data *bufmgr_data,
 109                                                                                 tbm_error_e *error);
 110
 111         /**
 112         * @brief set(bind) the native display
 113         * @param[in] bufmgr_data The backend module data
 114         * @param[in] native_display : the native display (wl_display in wayland window system)
 115         * @return #TBM_ERROR_NONE if success. Otherwise, error value.
 116         */
 117         tbm_error_e (*bufmgr_bind_native_display)(tbm_backend_bufmgr_data *bufmgr_data,
 118                                                                                         tbm_native_display *native_display);
 119
 120         /**
 121         * @brief get the formats list and the num to be supported by backend.
 122         * @param[in] bufmgr_data The backend module data
 123         * @param[out] **formats : format array list. it is allocated by backend funtion
 124         * @param[out] *num : the number of the formats to be supported by backend
 125         * @return #TBM_ERROR_NONE if success. Otherwise, error value.
 126         */
 127         tbm_error_e (*bufmgr_get_supported_formats)(tbm_backend_bufmgr_data *bufmgr_data,
 128                                                                                         uint32_t **formats, uint32_t *num);
 129
 130         /**
 131         * @brief get the plane data of the surface.
 132         * @param[in] bufmgr_data The backend module data
 133         * @param[in] format : the format of the surface
 134         * @param[in] plane_idx : the format of the surface
 135         * @param[in] width : the width of the surface
 136         * @param[in] height : the height of the surface
 137         * @param[out] size : the size of the plane
 138         * @param[out] offset : the offset of the plane
 139         * @param[out] pitch : the pitch of the plane
 140         * @param[out] bo_idx : the bo index of the plane
 141         * @return #TBM_ERROR_NONE if success. Otherwise, error value.
 142         */
 143         tbm_error_e (*bufmgr_get_plane_data)(tbm_backend_bufmgr_data *bufmgr_data,
 144                                                                         tbm_format format, int plane_idx, int width,
 145                                                                         int height, uint32_t *size, uint32_t *offset,
 146                                                                         uint32_t *pitch, int *bo_idx);
 147
 148         /**
 149         * @brief allocate the bo_data of the tbm_backend
 150         * @param[in] bufmgr_data The backend module data
 151         * @param[in] size : the size of buffer object
 152         * @param[in] flags : the flags of memory type
 153         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 154         * @return pointer of the bo_data of the tbm backend.
 155         */
 156         tbm_backend_bo_data *(*bufmgr_alloc_bo)(tbm_backend_bufmgr_data *bufmgr_data,
 157                                                                 unsigned int size, tbm_bo_memory_type mem_type,
 158                                                                 tbm_error_e *error);
 159
 160         /**
 161         * @brief allocate the buffer object for tbm surface
 162         * @param[in] bo : the buffer object
 163         * @param[in] width : the width of surface
 164         * @param[in] height : the height of surface
 165         * @param[in] format : the format of surface
 166         * @param[in] flags : the flags of memory type
 167         * @param[in] bo_idx : the index of bo in surface
 168         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 169         * @return pointer of the bo_data of the tbm backend.
 170         */
 171         tbm_backend_bo_data *(*bufmgr_alloc_bo_with_format)(tbm_backend_bufmgr_data *bufmgr_data,
 172                                                                                         int format, int bo_idx, int width,
 173                                                                                         int height, tbm_bo_memory_type mem_type,
 174                                                                                         tbm_error_e *error);
 175
 176         /**
 177         * @brief import the buffer object associated with the prime fd.
 178         * @remarks tbm_fd must be free by user.
 179         * @remarks If the backend doesn't support a buffer sharing by tbm fd,
 180         *               fucntion pointer must be set to NULL.
 181         * @param[in] bufmgr_data The backend module data
 182         * @param[in] fd : the prime fd associated with the buffer object
 183         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 184         * @return pointer of the bo_data of the tbm backend.
 185         */
 186         tbm_backend_bo_data *(*bufmgr_import_fd)(tbm_backend_bufmgr_data *bufmgr_data,
 187                                                                         tbm_fd fd, tbm_error_e *error);
 188
 189         /**
 190         * @brief import the buffer object associated with the key.
 191         * @remarks If the backend doesn't support a buffer sharing by tbm key,
 192                         fucntion pointer must be set to NULL.
 193         * @param[in] bufmgr_data The backend module data
 194         * @param[in] key : the key associated with the buffer object
 195         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 196         * @return pointer of the bo_data of the tbm backend.
 197         */
 198         tbm_backend_bo_data *(*bufmgr_import_key)(tbm_backend_bufmgr_data *bufmgr_data,
 199                                                                                 tbm_key key, tbm_error_e *error);
 200
 201         /* Padding for future extension */
 202         void (*reserved1)(void);
 203         void (*reserved2)(void);
 204         void (*reserved3)(void);
 205         void (*reserved4)(void);
 206         void (*reserved5)(void);
 207         void (*reserved6)(void);
 208 };
 209
 210 /**
 211  * @brief The bo functions for a backend module.
 212  */
 213 struct _tbm_backend_bo_func {
 214         /**
 215         * @brief free the buffer object.
 216         * @param[in] bo_data : the bo data of the tbm backend
 217         * @return #TBM_ERROR_NONE if success. Otherwise, error value.
 218         */
 219         void (*bo_free)(tbm_backend_bo_data *bo_data);
 220
 221         /**
 222         * @brief get the size of a bo.
 223         * @param[in] bo_data : the bo data of the tbm backend
 224         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 225         * @return size if this function succeeds, otherwise 0.
 226         */
 227         int (*bo_get_size)(tbm_backend_bo_data *bo_data, tbm_error_e *error);
 228
 229         /**
 230         * @brief get the tbm memory type
 231         * @param[in] bo_data : the bo data of the tbm backend
 232         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 233         * @see #TBM_BO_FLAGS #tbm_bo_memory_type
 234         * @return tbm flags of memory type is this function succeeds, otherwise 0.
 235         */
 236         tbm_bo_memory_type (*bo_get_memory_types)(tbm_backend_bo_data *bo_data,
 237                                                                                 tbm_error_e *error);
 238
 239         /**
 240         * @brief get the tbm_bo_handle according to the device type.
 241         * @param[in] bo_data : the bo data of the tbm backend
 242         * @param[in] device : the device type to get a handle
 243         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 244         * @return the handle of the buffer object
 245         */
 246         tbm_bo_handle (*bo_get_handle)(tbm_backend_bo_data *bo_data,
 247                                                                 tbm_bo_device_type device, tbm_error_e *error);
 248
 249         /**
 250         * @brief map the buffer object according to the device type and the option.
 251         * @param[in] bo_data : the bo data of the tbm backend
 252         * @param[in] device : the device type to get a handle
 253         * @param[in] opt : the option to access the buffer object
 254         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 255         * @return the handle of the buffer object
 256         */
 257         tbm_bo_handle (*bo_map)(tbm_backend_bo_data *bo_data, tbm_bo_device_type device,
 258                                                 tbm_bo_access_option opt, tbm_error_e *error);
 259
 260         /**
 261         * @brief unmap the buffer object.
 262         * @param[in] bo_data : the bo data of the tbm backend
 263         * @return #TBM_ERROR_NONE if success. Otherwise, error value.
 264         */
 265         tbm_error_e (*bo_unmap)(tbm_backend_bo_data *bo_data);
 266
 267         /**
 268         * @brief lock the buffer object with a device and an opt.
 269         * @param[in] bo_data : the bo data of the tbm backend
 270         * @param[in] device : the device type to get a handle
 271         * @param[in] opt : the option to access the buffer object
 272         * @return #TBM_ERROR_NONE if success. Otherwise, error value.
 273         * @remark This function pointer could be null.
 274         */
 275         tbm_error_e (*bo_lock)(tbm_backend_bo_data *bo_data, tbm_bo_device_type device,
 276                                                 tbm_bo_access_option opt);
 277
 278         /**
 279         * @brief unlock the buffer object.
 280         * @param[in] bo_data : the bo data of the tbm backend
 281         * @return #TBM_ERROR_NONE if success. Otherwise, error value.
 282         * @remark This function pointer could be null.
 283         */
 284         tbm_error_e (*bo_unlock)(tbm_backend_bo_data *bo_data);
 285
 286         /**
 287         * @brief export the buffer object
 288         * @remarks tbm_fd must be free by user.
 289         * @remarks If the backend doesn't support a buffer sharing by tbm fd,
 290                         fucntion pointer must be set to NULL.
 291         * @param[in] bo_data : the bo data of the tbm backend
 292         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 293         * @return tbm_fd associated with the buffer object
 294         */
 295         tbm_fd (*bo_export_fd)(tbm_backend_bo_data *bo_data, tbm_error_e *error);
 296
 297         /**
 298         * @brief export the buffer object
 299         * @remarks If the backend doesn't support a buffer sharing by tbm key,
 300                         fucntion pointer must be set to NULL.
 301         * @param[in] bo : the buffer object
 302         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
 303         * @return key associated with the buffer object
 304         */
 305         tbm_key (*bo_export_key)(tbm_backend_bo_data *bo_data, tbm_error_e *error);
 306
 307         /* Padding for future extension */
 308         void (*reserved1)(void);
 309         void (*reserved2)(void);
 310         void (*reserved3)(void);
 311         void (*reserved4)(void);
 312         void (*reserved5)(void);
 313         void (*reserved6)(void);
 314 };
 315
 316 /**
 317  * @brief The backend module information of the entry point to initialize a tbm
 318  * backend module.
 319  * @remark
 320  * A backend module @b SHOULD define the global data symbol of which name is
 321  * @b "tbm_backend_module_data". tbm will read this symbol, @b "tbm_backend_module_data",
 322  * at the initial time and call init() function of #tbm_backend_module.
 323  */
 324 typedef struct _tbm_backend_module {
 325         const char *name;           /**< The module name of a backend module */
 326         const char *vendor;         /**< The vendor name of a backend module */
 327         unsigned long abi_version;  /**< The ABI version of a backend module */
 328
 329         /**
 330          * @brief The init function of a backend module
 331          * @param[in] bufmgr A tbm buffer manager object.
 332          * @return The backend module data
 333          * @see tbm_backend_bufmgr_data
 334          */
 335         tbm_backend_bufmgr_data *(*init)(tbm_bufmgr bufmgr, tbm_error_e *error);
 336
 337         /**
 338         * @brief deinitialize the bufmgr private data.
 339         * @param[in] bufmgr_data : The backend module data
 340         */
 341         void (*deinit)(tbm_backend_bufmgr_data *bufmgr_data);
 342 } tbm_backend_module;
 343
 344 #ifdef __cplusplus
 345 extern "C" {
 346 #endif
 347
 348 int                      tbm_backend_bufmgr_query_display_server(tbm_bufmgr bufmgr, tbm_error_e *error);
 349 tbm_backend_bufmgr_func *tbm_backend_bufmgr_alloc_bufmgr_func(tbm_bufmgr bufmgr, tbm_error_e *error);
 350 void                     tbm_backend_bufmgr_free_bufmgr_func(tbm_bufmgr bufmgr, tbm_backend_bufmgr_func *func);
 351 tbm_error_e              tbm_backend_bufmgr_register_bufmgr_func(tbm_bufmgr bufmgr, tbm_backend_bufmgr_func *func);
 352 tbm_backend_bo_func     *tbm_backend_bufmgr_alloc_bo_func(tbm_bufmgr bufmgr, tbm_error_e *error);
 353 void                     tbm_backend_bufmgr_free_bo_func(tbm_bufmgr bufmgr, tbm_backend_bo_func *func);
 354 tbm_error_e              tbm_backend_bufmgr_register_bo_func(tbm_bufmgr bufmgr, tbm_backend_bo_func *func);
 355
 356 #ifdef __cplusplus
 357 }
 358 #endif
 359 #endif                                                  /* _TBM_BACKEND_H_ */