TBM

From Tizen Wiki
Jump to: navigation, search

TBM stands for Tizen Buffer Manager.

Description

Tizen Buffer Manager (TBM) provides the abstraction interface for the graphic buffer manager in Tizen.

Porting Guide

The TBM has a frontend libary and a backend module. The TBM frontend library is hardware-independent and provides the generic buffer interface for users. On the other hand, the TBM backend module is hardware-dependent and provides the buffer interface depended on the target system. The chipset vendors have to provide their own backend modules in order for the TBM to work well in Tizen platform. This is because the vendors' way to manage the graphic buffers can be different among various chipset devices. TBM already has several backends for reference, such as libtbm-dumb, and libtbm-shm.

Tbm-backend.png

With TBM, the client and server can allocate buffers and share it between them. For example, a client allocates a graphic buffer, draws something on it with GL and sends it to the display server for displaying it on the screen without buffer copying. The TBM backend module is implemented as a shared library and the TBM frontend finds the libtbm-default.so file and loads it from the /usr/lib/bufmgr directory at runtime.

sh-3.2# ls -al
lrwxrwxrwx  1 root root    14 Jul 28  2016 libtbm_default.so -> libtbm_sprd.so
lrwxrwxrwx  1 root root    20 Jul 28  2016 libtbm_sprd.so -> libtbm_sprd.so.0.0.0
lrwxrwxrwx  1 root root    20 Jul 28  2016 libtbm_sprd.so.0 -> libtbm_sprd.so.0.0.0
-rwxr-xr-x  1 root root 26728 Jun 29  2016 libtbm_sprd.so.0.0.0

Initialing the TBM backend module

<<Tizen 5.5 or later>>

The TBM backend module must define the global data symbol with the name tbm_backend_module_data. The TBM frontend reads this symbol at the initialization time. TBM calls the init() function of the tbm_backend_module_data. For more information, see tbm_backend.h.

typedef struct _tbm_backend_module {
	const char *name;           /**< The module name of a backend module */
	const char *vendor;         /**< The vendor name of a backend module */
	unsigned long abi_version;  /**< The ABI version of a backend module */

	/**
	 * @brief The init function of a backend module
	 * @param[in] bufmgr A tbm buffer manager object.
	 * @return The backend module data
	 * @see tbm_backend_bufmgr_data
	 */
	tbm_backend_bufmgr_data *(*init)(tbm_bufmgr bufmgr, tbm_error_e *error);

	/**
	* @brief deinitialize the bufmgr private data.
	* @param[in] bufmgr_data : The backend module data
	*/
	void (*deinit)(tbm_backend_bufmgr_data *bufmgr_data);
} tbm_backend_module;
#include <tbm_backend.h>

static tbm_backend_bufmgr_data *bufmgr_data;

tbm_backend_bufmgr_data*
tbm_shm_init(tbm_bufmgr bufmgr, tbm_error_e *error)
{
    bufmgr_data = calloc(1, sizeof(tbm_backend_bufmgr_data));

    return (tbm_backend_bufmgr_data*)bufmgr_data;
}

void
tbm_shm_deinit(tbm_backend_bufmgr_data *bufmgr_data)
{
    free(bufmgr_data);
}

tbm_backend_module tbm_backend_module_data = {
	"shm",
	"Samsung",
	TBM_BACKEND_ABI_VERSION_3_0,
	tbm_shm_init,
	tbm_shm_deinit
};

The TDM backend must register the tbm_backend_bufmgr_func and tbm_backend_bo_func with the tbm_backend_bufmgr_register_bufmgr_func() and tbm_backend_bufmgr_alloc_bo_func() in the tbm_backend_module_data init() function.

#include <tbm_backend.h>

tbm_backend_bufmgr_data*
tbm_shm_init(tbm_bufmgr bufmgr, tbm_error_e *error)
{
	bufmgr_func->bufmgr_get_capabilities = tbm_shm_bufmgr_get_capabilities;
	bufmgr_func->bufmgr_bind_native_display = tbm_shm_bufmgr_bind_native_display;
	bufmgr_func->bufmgr_get_supported_formats = tbm_shm_bufmgr_get_supported_formats;
	bufmgr_func->bufmgr_get_plane_data = tbm_shm_bufmgr_get_plane_data;
	bufmgr_func->bufmgr_alloc_bo = tbm_shm_bufmgr_alloc_bo;
	bufmgr_func->bufmgr_alloc_bo_with_format = NULL;
	bufmgr_func->bufmgr_import_fd = tbm_shm_bufmgr_import_fd;
	bufmgr_func->bufmgr_import_key = NULL;

	bo_func->bo_free = tbm_shm_bo_free;
	bo_func->bo_get_size = tbm_shm_bo_get_size;
	bo_func->bo_get_memory_types = tbm_shm_bo_get_memory_type;
	bo_func->bo_get_handle = tbm_shm_bo_get_handle;
	bo_func->bo_map = tbm_shm_bo_map;
	bo_func->bo_unmap = tbm_shm_bo_unmap;
	bo_func->bo_lock = NULL;
	bo_func->bo_unlock = NULL;
	bo_func->bo_export_fd = tbm_sprd_bo_export_fd;
	bo_func->bo_export_key = NULL;

	err = tbm_backend_bufmgr_register_bo_func(bufmgr, bo_func);
	if (err != TBM_ERROR_NONE) {
		TBM_ERR("fail to register bo_func! err(%d)\n", err);
		if (error)
			*error = TBM_ERROR_INVALID_OPERATION;
		goto fail_register_bo_func;
	}
	bufmgr_shm->bo_func = bo_func;

	return (tbm_backend_bufmgr_data *)bufmgr_shm;
}

<<Tizen 5.5 or earlier>>

The TBMModuleData is for the entry point symbol to initialize the TBM backend module. The TBM backend module must have to define the global data symbol with the name of tbmModuleData. The TBM frontend loads the tbmModuleData global data symbol and calls the init() function at the initial time.

Note
Do not change the name of the symbol in the TBM backend module.
/*
   @brief tbm module data
   Data type for the entry point of the backend module
*/
typedef struct {
    TBMModuleVersionInfo *vers;	/* TBM module information */
    ModuleInitProc init; /* init function of a backend module */
} TBMModuleData;

typedef int (*ModuleInitProc) (tbm_bufmgr, int);

At the initialization of the backend module, the backend module allocates the tbm_bufmgr_backend instance (tbm_backend_alloc), fills the information, and initializes the backend module to the TBM (tbm_backend_init).

tbm_bufmgr_backend tbm_backend_alloc(void);
void tbm_backend_free(tbm_bufmgr_backend backend);
int tbm_backend_init(tbm_bufmgr bufmgr, tbm_bufmgr_backend backend);
MODULEINITPPROTO (init_tbm_bufmgr_priv);

static TBMModuleVersionInfo DumbVersRec =
{
    "shm",
    "Samsung",
    TBM_ABI_VERSION,
};

TBMModuleData tbmModuleData = {&DumbVersRec, init_tbm_bufmgr_priv};

int
init_tbm_bufmgr_priv(tbm_bufmgr bufmgr, int fd)
{
    tbm_bufmgr_backend bufmgr_backend;

    bufmgr_shm = calloc(1, sizeof(struct _tbm_bufmgr_shm));

    bufmgr_backend = tbm_backend_alloc();

    bufmgr_backend->priv = (void *)bufmgr_shm;
    bufmgr_backend->bufmgr_deinit = tbm_shm_bufmgr_deinit,
    bufmgr_backend->bo_size = tbm_shm_bo_size,
    bufmgr_backend->bo_alloc = tbm_shm_bo_alloc,
    bufmgr_backend->bo_free = tbm_shm_bo_free,
    bufmgr_backend->bo_import = tbm_shm_bo_import,
    bufmgr_backend->bo_import_fd = NULL,
    bufmgr_backend->bo_export = tbm_shm_bo_export,
    bufmgr_backend->bo_export_fd = NULL,
    bufmgr_backend->bo_get_handle = tbm_shm_bo_get_handle,
    bufmgr_backend->bo_map = tbm_shm_bo_map,
    bufmgr_backend->bo_unmap = tbm_shm_bo_unmap,
    bufmgr_backend->bo_lock = NULL;
    bufmgr_backend->bo_unlock = NULL;
    bufmgr_backend->surface_get_plane_data = tbm_shm_surface_get_plane_data;
    bufmgr_backend->surface_supported_format = tbm_shm_surface_supported_format;


    if (!tbm_backend_init(bufmgr, bufmgr_backend))
    {
        tbm_backend_free(bufmgr_backend);
        free(bufmgr_shm);

        return 0;
    }

    return 1;
}

Porting OAL Interface

<<Tizen 5.5 or later>>

TBM provides the header files to implement the TBM backend module.

Header file Description
tbm_backend.h This file includes the information to implement the TBM backend module.
tbm_drm_helper.h This file includes the helper function for the drm interface backend module.
tbm_type_common.h This is the user header file including the general information to use the TBM.
TBM Backend interface

The following table lists the bufmgr backend interface functions of the tbm_backend module. For more information, see tdm_backend.h.

Function Description
bufmgr_get_capabilities() Get the capabilities of a buffer manager.

The backend must support the TBM_BUFMGR_CAPABILITY_SHARE_FD. TBM_BUFMGR_CAPABILITY_SHARE_KEY will help you do debugging to develop the platform because the tbm_key will be the unique identification of the tbm_bo memory in the system.

Mandatory
bufmgr_bind_native_display() Set(bind) the native display.

If the backend needs to get the native display, use this backend function.

Optional
bufmgr_get_supported_formats() Get the formats list and the num to be supported by backend. Mandatory
bufmgr_get_plane_data() Get the plane data of the plane_idx according to the format. Mandatory
bufmgr_alloc_bo() Allocate the bo data of the tbm_backend

The backend must return the tbm_backend_bo_data pointer(handle).

Mandatory
bufmgr_alloc_bo_with_format() Allocate the bo data of the bo index according to the format

The backend must return the tbm_backend_bo_data pointer(handle).

Mandatory
bufmgr_alloc_bo_with_tiled_format() Allocate the bo data for GPU which support tiled format

The backend must return the tbm_backend_bo_data pointer(handle).

Mandatory
bufmgr_import_fd() Import the bo data associated with the tdm_fd(prime fd).

The tbm_fd must be frees by the user. If the backend does not support a buffer sharing by TBM fd, the function pointer must be set to NULL.

Mandatory
bufmgr_import_key() Import the bo data associated with the tdm_key.

If the backend does not support a buffer sharing by the TBM key, the function pointer must be set to NULL.

Mandatory

The following table lists the bo backend interface functions of the tbm_backend module. For more information, see tdm_backend.h.

Function Description
bo_free() Free the bo data. Mandatory
bo_get_size() Get the size of a bo data.

If the backend needs to get the native display, use this backend function.

Mandatory
bo_get_memory_types() Get the tbm_bo_memory_type. Mandatory
bo_get_handle() Get the tbm_bo_handle according to the device type. Mandatory
bo_map() Map the bo data according to the device type and the option. Mandatory
bo_unmap() Unmap the bo data. Mandatory
bo_lock() Lock the bo data with a device and an opt. Optional
bo_unlock() Unlock the bo data. Optional
bo_export_fd() Export the bo data to the tdm_fd(prime fd)

The tbm_fd must be freed by the user. If the backend does not support a buffer sharing by TBM fd, the function pointer must be set to NULL.

Mandatory
bo_export_key() Export the bo data to the tdm_key

If the backend does not support a buffer sharing by TBM key, the function pointer must be set to NULL.

Mandatory

The following table lists the TBM bufmgr capability, tbm_bufmgr_capability.

TBM bufmgr capability Description
TBM_BUFMGR_CAPABILITY_NONE Not Support capability
TBM_BUFMGR_CAPABILITY_SHARE_KEY Support sharing buffer by tbm key
TBM_BUFMGR_CAPABILITY_SHARE_FD Support sharing buffer by tbm fd
TBM_BUFMGR_CAPABILITY_TBM_SYNC Support timeline sync
TBM_BUFMGR_CAPABILITY_TILED_MEMORY Support tiled memory

The following table lists the TBM buffer memory types, tbm_bo_memory_type.

Buffer memory type Description
TBM_BO_DEFAULT Default memory: it depends on the backend
TBM_BO_SCANOUT Scanout memory
TBM_BO_NONCACHABLE Non-cachable memory
TBM_BO_WC Write-combine memory
TBM_BO_VENDOR Vendor specific memory (depends on the backend)

The following table lists the TBM buffer device types, tbm_bo_device_type.

Device type Description
TBM_DEVICE_DEFAULT The device type to get the default handle
TBM_DEVICE_CPU The device type to get the virtual memory
TBM_DEVICE_2D The device type to get the 2D memory handle
TBM_DEVICE_3D The device type to get the 3D memory handle
TBM_DEVICE_MM The device type to get the multimedia handle

The following table lists the TBM buffer access options, tbm_bo_access_option.

Access option Description
TBM_OPTION_READ The access option to read
TBM_OPTION_WRITE The access option to write
TBM_OPTION_VENDOR The vendor specific option that depends on the backend
TBM DRM helper function

If target uses the drm interface, the client needs to get the authenticated fd from the display server and the display server must share the drm master fd with the TDM backend module. The TBM frontend provides the helper functions for drm authentication with the wayland protocol and sharing the master fd with TDM backend module.

Function Description
tbm_drm_helper_wl_auth_server_init() If the TBM backend module need to use the authentication server, the backend module must call this function in the display server.
tbm_drm_helper_wl_auth_server_deinit() Deinitailizes the drm authentication in display server.
tbm_drm_helper_get_master_fd() If the TDM backend module already has a drm master fd, the TBM backend module can get the master fd from this function.
tbm_drm_helper_set_tbm_master_fd() If the TBM backend module opens the drm master fd, this function has to be called for sharing the drm master fd with TDM.
tbm_drm_helper_unset_tbm_master_fd() If the TBM backend module is opened and does not use the drm master fd, this function has to be called.
tbm_drm_helper_get_auth_info() Client gets the authenticated fd and device info from the display server.

<<Tizen 5.5 or earlier>>

TBM provides the header files to implement the TBM backend module.

Header file Description
tbm_bufmgr_backend.h This file includes the information to implement the TBM backend module.
tbm_drm_helper.h This file includes the helper function for the drm interface backend module.
tbm_bufmgr.h This is the user header file including the general information to use the TBM.
tbm_surface.h This is the user header file including the general information to use the tbm_surface.
TBM Backend interface

The following table lists the TBM Backend interface for initializing and deinitializing.

Function Description
ModuleInitProc() The init function of a backend module. Mandatory
bufmgr_deinit() Deinitializes the buffer manager private. Mandatory
bufmgr_bind_native_display() If the backend needs to get the native display, use this backend function. Optional

The following table lists the TBM backend interface functions for tbm_bo.

Function Description
bo_alloc() Allocates the buffer object.

If backend wants to reuse the bo private at frontend, return the same pointer of the bo private.

Mandatory
bo_free() Frees the buffer object.

The frontend calls this function when it does not use the bo private.

Mandatory
bo_import() Imports the buffer object associated with the key.

If the backend does not support a buffer sharing by the TBM key, the function pointer must be set to NULL.

Optional
bo_export() Exports the buffer object.

If the backend does not support a buffer sharing by TBM key, the function pointer must be set to NULL.

Optional
bo_import_fd() Imports the buffer object associated with the prime fd.

The tbm_fd must be frees by the user. If the backend does not support a buffer sharing by TBM fd, the function pointer must be set to NULL.

Mandatory

(Must support buffer sharing by TBM fd.)

bo_export_fd() Imports the buffer object associated with the prime fd.

The tbm_fd must be freed by the user. If the backend does not support a buffer sharing by TBM fd, the function pointer must be set to NULL.

Mandatory

(Must support buffer sharing by TBM fd.)

bo_get_flags() Gets the TBM flags of memory type Mandatory
bo_size() Gets the size of a buffer object. Mandatory
bo_get_handle() Gets the tbm_bo_handle according to the device type. Mandatory
bo_map() Maps the buffer object according to the device type and the option. Mandatory
bo_unmap() Unmaps the buffer object. Mandatory
bo_lock() Locks the buffer object with a device and an opt. Optional
bo_unlock() Unlocks the buffer object. Optional

The following table lists the TBM backend interface for tbm_surface.

Function Description
surface_supported_format() Queries the formats list and the number to be supported by backend. Mandatory
surface_get_plane_data() Gets the plane data, such as the size, ofeset, pitch, and buffer object index of the surface. Mandatory
surface_bo_alloc() Allocates the buffer object for TBM surface with width, height, format, and buffer object index.

If the backend does not want to allocate the buffer of the TBM surface with width, format and height, the function pointer must be set to NULL. The TBM frontend allocation buffer of the TBM surface with data is gained from the surface_get_plane_data().

Optional

The following table lists the TBM buffer memory types.

Buffer memory type Description
TBM_BO_DEFAULT Default memory: it depends on the backend
TBM_BO_SCANOUT Scanout memory
TBM_BO_NONCACHABLE Non-cachable memory
TBM_BO_WC Write-combine memory
TBM_BO_VENDOR Vendor specific memory (depends on the backend)

The following table lists the TBM buffer device types.

Device type Description
TBM_DEVICE_DEFAULT The device type to get the default handle
TBM_DEVICE_CPU The device type to get the virtual memory
TBM_DEVICE_2D The device type to get the 2D memory handle
TBM_DEVICE_3D The device type to get the 3D memory handle
TBM_DEVICE_MM The device type to get the multimedia handle

The following table lists the TBM buffer access options.

Access option Description
TBM_OPTION_READ The access option to read
TBM_OPTION_WRITE The access option to write
TBM_OPTION_VENDOR The vendor specific option that depends on the backend
TBM DRM helper function

If target uses the drm interface, the client needs to get the authenticated fd from the display server and the display server must share the drm master fd with the TDM backend module. The TBM frontend provides the helper functions for drm authentication with the wayland protocol and sharing the master fd with TDM backend module.

Function Description
tbm_drm_helper_wl_auth_server_init() If the TBM backend module need to use the authentication server, the backend module must call this function in the display server.
tbm_drm_helper_wl_auth_server_deinit() Deinitailizes the drm authentication in display server.
tbm_drm_helper_get_master_fd() If the TDM backend module already has a drm master fd, the TBM backend module can get the master fd from this function.
tbm_drm_helper_set_tbm_master_fd() If the TBM backend module opens the drm master fd, this function has to be called for sharing the drm master fd with TDM.
tbm_drm_helper_unset_tbm_master_fd() If the TBM backend module is opened and does not use the drm master fd, this function has to be called.
tbm_drm_helper_get_auth_info() Client gets the authenticated fd and device info from the display server.

TBM Backends

Backend Project (http://review.tizen.org) Description
libtbm-shm platform/adaptation/libtbm-shm
  • The backend for the target device whitch supports the SHM memory interface.
  • The SHM backend module uses the XSI shared memory segment and does not have hardware dependencies.
libtbm-dumb platform/adaptation/libtbm-dumb
  • The backend for the target device which supports the DUMB memory interface.
  • If the target kernel supports the drm interface, the target can use the dumb backend because the DUMB memory interface is the default drm memory interface.
libtbm-sprd platform/adaptation/spreadtrum/libtbm-sprd
  • The backend for the target device which uses the Spreadtrum chipset only.
  • The sprd backend module uses the drm gem memory interface but some ioctl only provided by the sprd drm kernel.
libtbm-exynos platform/adaptation/samsung_exynos/libtbm-exynos
  • The backend for the target device which uses the exynos chipset only.
  • The exynos backend module uses the drm gem memory interface but some ioctl only provided by exynos drm kernel.
libtbm-vigs platform/adaptation/emulator/libtbm-vigs
  • The backend for the target device which supports the VIGS interface.
  • The vigs backend is used by the emulator target.


Reference

For more detailed information about the TBM and TBM backend, see Tizen Buffer Manager (TBM).