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 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.
190 tbm_backend_bo_data *(*bufmgr_import_fd)(tbm_backend_bufmgr_data *bufmgr_data,
191 tbm_fd fd, tbm_error_e *error);
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.
202 tbm_backend_bo_data *(*bufmgr_import_key)(tbm_backend_bufmgr_data *bufmgr_data,
203 tbm_key key, tbm_error_e *error);
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);
215 * @brief The bo functions for a backend module.
217 struct _tbm_backend_bo_func {
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.
223 void (*bo_free)(tbm_backend_bo_data *bo_data);
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.
231 int (*bo_get_size)(tbm_backend_bo_data *bo_data, tbm_error_e *error);
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.
240 tbm_bo_memory_type (*bo_get_memory_types)(tbm_backend_bo_data *bo_data,
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
250 tbm_bo_handle (*bo_get_handle)(tbm_backend_bo_data *bo_data,
251 tbm_bo_device_type device, tbm_error_e *error);
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
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);
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.
269 tbm_error_e (*bo_unmap)(tbm_backend_bo_data *bo_data);
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.
279 tbm_error_e (*bo_lock)(tbm_backend_bo_data *bo_data, tbm_bo_device_type device,
280 tbm_bo_access_option opt);
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.
288 tbm_error_e (*bo_unlock)(tbm_backend_bo_data *bo_data);
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
299 tbm_fd (*bo_export_fd)(tbm_backend_bo_data *bo_data, tbm_error_e *error);
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
309 tbm_key (*bo_export_key)(tbm_backend_bo_data *bo_data, tbm_error_e *error);
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);
321 * @brief The backend module information of the entry point to initialize a tbm
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.
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 */
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
339 tbm_backend_bufmgr_data *(*init)(tbm_bufmgr bufmgr, tbm_error_e *error);
342 * @brief deinitialize the bufmgr private data.
343 * @param[in] bufmgr_data : The backend module data
345 void (*deinit)(tbm_backend_bufmgr_data *bufmgr_data);
346 } tbm_backend_module;
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);
363 #endif /* _TBM_BACKEND_H_ */