1 /**************************************************************************
5 Copyright 2018 Samsung Electronics co., Ltd. All Rights Reserved.
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>
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:
20 The above copyright notice and this permission notice (including the
21 next paragraph) shall be included in all copies or substantial portions
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.
32 **************************************************************************/
34 #ifndef _TBM_BACKEND_H_
35 #define _TBM_BACKEND_H_
37 #include <tbm_type_common.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.
46 * #include <tbm_backend.h>
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)
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
62 #define TBM_BACKEND_SET_ABI_VERSION(maj, min) \
63 ((((maj) << 16) & TBM_BACKEND_ABI_MAJOR_MASK) | ((min) & TBM_BACKEND_ABI_MINOR_MASK))
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 */
71 * @brief The backend bufmgr data
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
77 typedef void tbm_backend_bufmgr_data;
80 * @brief The backend bo data
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
86 typedef void tbm_backend_bo_data;
89 * @brief The type definition of the bufmgr functions
91 typedef struct _tbm_backend_bufmgr_func tbm_backend_bufmgr_func;
94 * @brief The type definition of the bo functions
96 typedef struct _tbm_backend_bo_func tbm_backend_bo_func;
99 * @brief The bufmgr functions for a backend module.
101 struct _tbm_backend_bufmgr_func {
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
112 tbm_bufmgr_capability (*bufmgr_get_capabilities)(tbm_backend_bufmgr_data *bufmgr_data,
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.
121 tbm_error_e (*bufmgr_bind_native_display)(tbm_backend_bufmgr_data *bufmgr_data,
122 tbm_native_display *native_display);
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.
131 tbm_error_e (*bufmgr_get_supported_formats)(tbm_backend_bufmgr_data *bufmgr_data,
132 uint32_t **formats, uint32_t *num);
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.
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);
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.
160 tbm_backend_bo_data *(*bufmgr_alloc_bo)(tbm_backend_bufmgr_data *bufmgr_data,
161 unsigned int size, tbm_bo_memory_type mem_types,
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.
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,
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.
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,
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.
207 tbm_backend_bo_data *(*bufmgr_import_fd)(tbm_backend_bufmgr_data *bufmgr_data,
208 tbm_fd fd, tbm_error_e *error);
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.
219 tbm_backend_bo_data *(*bufmgr_import_key)(tbm_backend_bufmgr_data *bufmgr_data,
220 tbm_key key, tbm_error_e *error);
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);
232 * @brief The bo functions for a backend module.
234 struct _tbm_backend_bo_func {
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.
240 void (*bo_free)(tbm_backend_bo_data *bo_data);
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.
248 int (*bo_get_size)(tbm_backend_bo_data *bo_data, tbm_error_e *error);
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.
257 tbm_bo_memory_type (*bo_get_memory_types)(tbm_backend_bo_data *bo_data,
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
267 tbm_bo_handle (*bo_get_handle)(tbm_backend_bo_data *bo_data,
268 tbm_bo_device_type device, tbm_error_e *error);
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
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);
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.
286 tbm_error_e (*bo_unmap)(tbm_backend_bo_data *bo_data);
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.
296 tbm_error_e (*bo_lock)(tbm_backend_bo_data *bo_data, tbm_bo_device_type device,
297 tbm_bo_access_option opt);
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.
305 tbm_error_e (*bo_unlock)(tbm_backend_bo_data *bo_data);
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
316 tbm_fd (*bo_export_fd)(tbm_backend_bo_data *bo_data, tbm_error_e *error);
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
326 tbm_key (*bo_export_key)(tbm_backend_bo_data *bo_data, tbm_error_e *error);
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);
338 * @brief The backend module information of the entry point to initialize a tbm
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.
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 */
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
356 tbm_backend_bufmgr_data *(*init)(tbm_bufmgr bufmgr, tbm_error_e *error);
359 * @brief deinitialize the bufmgr private data.
360 * @param[in] bufmgr_data : The backend module data
362 void (*deinit)(tbm_backend_bufmgr_data *bufmgr_data);
363 } tbm_backend_module;
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);
380 #endif /* _TBM_BACKEND_H_ */