--- /dev/null
+## Buffer Management
+
+TBM has a frontend library and a backend module. The TBM frontend library is hardware-independent and provides a generic buffer interface. On the other hand, the TBM backend module is hardware-dependent and provides a buffer interface dependent on the target system. Chipset vendors have to provide their own backend modules in order for TBM to work well on the Tizen platform. This is because the way each vendor manages the graphic buffers can be different between various chipset devices. TBM already has several reference backends, such as `libtbm-dumb`, and `libtbm-shm`.
+
+**Figure: TBM backend**
+
+
+
+ With TBM, the client and server can allocate buffers and share buffers 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
+
+ The `TBMModuleData` is for the entry point symbol to initialize the TBM backend module. The TBM backend module must 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.
+
+ ```cpp
+ /*
+ @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);
+```
+
+The TBM backend module initialization consists of allocating the `tbm_bufmgr_backend` instance (`tbm_backend_alloc`), entering the necessary information, and the initialization itself (`tbm_backend_init`).
+
+```cpp
+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);
+```
+
+```cpp
+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 the OAL Interface
+
+TBM provides the header files to implement the TBM backend module.
+
+**Table: TBM backend module header files**
+
+| Header file | Description |
+| ---------------------------------------- | ---------------------------------------- |
+| [tbm_bufmgr_backend.h](https://review.tizen.org/gerrit/gitweb?p=platform/core/uifw/libtbm.git;a=blob;f=src/tbm_bufmgr_backend.h;h=839ec996de16493e40b90c72066448d770575bca;hb=refs/heads/tizen) | This file includes information on implementing the TBM backend module. |
+| [tbm_drm_helper.h](https://review.tizen.org/gerrit/gitweb?p=platform/core/uifw/libtbm.git;a=blob;f=src/tbm_drm_helper.h;h=0c93a378d2ddf64f2bcb9ebf6a1d0b85563670a2;hb=refs/heads/tizen) | This file includes helper functions for the DRM interface backend module. |
+| [tbm_bufmgr.h](https://review.tizen.org/gerrit/gitweb?p=platform/core/uifw/libtbm.git;a=blob;f=src/tbm_bufmgr.h;h=50fcf08101c2cb0a4b8750f3eda30d375c981ea7;hb=refs/heads/tizen) | This is the user header file including general information on how to use the TBM. |
+| [tbm_surface.h](https://review.tizen.org/gerrit/gitweb?p=platform/core/uifw/libtbm.git;a=blob;f=src/tbm_surface.h;h=0686a4ed2d0e26c0386e9f1232f0aa2a6e7f5eb6;hb=refs/heads/tizen) | This is the user header file including general information on how to use `tbm_surface`. |
+
+#### TBM Backend Interface
+
+The following table lists the TBM backend interface functions for initializing and deinitializing.
+
+**Table: Initializing and deinitializing functions**
+
+| Function | Description | |
+| ------------------------------ | ---------------------------------------- | --------- |
+| `ModuleInitProc()` | The `init` function of a backend module. | Mandatory |
+| `bufmgr_deinit()` | Deinitialize the buffer manager privately. | 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`.
+
+**Table: tbm_bo functions**
+
+| Function | Description | Mandatory |
+| ----------------- | ---------------------------------------- | ---------------------------------------- |
+| `bo_alloc()` | Allocates the buffer object. If the backend wants to reuse the `bo` private at frontend, return the same pointer of the `bo` private. | Yes |
+| `bo_free()` | Frees the buffer object. The frontend calls this function when it does not use the `bo` private. | Yes |
+| `bo_import()` | Imports the buffer object associated with the key. If the backend does not support buffer sharing by the TBM key, the function pointer must be set to `NULL`. | No |
+| `bo_export()` | Exports the buffer object. If the backend does not support buffer sharing by TBM key, the function pointer must be set to `NULL`. | No |
+| `bo_import_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 buffer sharing by TBM `fd`, the function pointer must be set to `NULL`. | Yes (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 buffer sharing by TBM `fd`, the function pointer must be set to `NULL`. | Yes (Must support buffer sharing by TBM `fd`.) |
+| `bo_get_flags()` | Gets the TBM flags of memory type. | Yes |
+| `bo_size()` | Gets the size of a buffer object. | Yes |
+| `bo_get_handle()` | Gets the `tbm_bo_handle` according to the device type. | Yes |
+| `bo_map()` | Maps the buffer object according to the device type and the option. | Yes |
+| `bo_unmap()` | Unmaps the buffer object. | Yes |
+| `bo_lock()` | Locks the buffer object with a device and an opt. | No |
+| `bo_unlock()` | Unlocks the buffer object. | No |
+
+The following table lists the TBM backend interface functions for `tbm_surface`.
+
+**Table: tbm_surface functions**
+
+| Function | Description | Mandatory |
+| ---------------------------- | ---------------------------------------- | --------- |
+| `surface_supported_format()` | Queries the format list and the number to be supported by backend. | Yes |
+| `surface_get_plane_data()` | Gets the plane data, such as the size, offset, pitch, and buffer object index of the surface. | Yes |
+| `surface_bo_alloc()` | Allocates the buffer object for the 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()`. | No |
+
+The following table lists the TBM buffer memory types.
+
+**Table: 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.
+
+**Table: TBM buffer device types**
+
+| Device type | Description |
+| -------------------- | ---------------------------------------- |
+| `TBM_DEVICE_DEFAULT` | Device type to get the default handle |
+| `TBM_DEVICE_CPU` | Device type to get the virtual memory |
+| `TBM_DEVICE_2D` | Device type to get the 2D memory handle |
+| `TBM_DEVICE_3D` | Device type to get the 3D memory handle |
+| `TBM_DEVICE_MM` | Device type to get the multimedia handle |
+
+The following table lists the TBM buffer access options.
+
+**Table: TBM buffer access options**
+
+| Access option | Description |
+| ------------------- | ---------------------------------------- |
+| `TBM_OPTION_READ` | Access option to read |
+| `TBM_OPTION_WRITE` | Access option to write |
+| `TBM_OPTION_VENDOR` | Vendor-specific option that depends on the backend |
+
+#### TBM DRM Helper Functions
+
+If the 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 shares the master `fd` with the TDM backend module.
+
+**Table: DRM helper functions**
+
+| 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()` | Deinitializes the `drm` authentication in the 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
+
+The following table lists the TBM backends.
+
+**Table: TBM backends**
+
+| Backend | Project ([http://review.tizen.org](http://review.tizen.org/)) | Description |
+| --------------- | ---------------------------------------- | ---------------------------------------- |
+| `libtbm-shm` | [platform/adaptation/libtbm-shm](https://review.tizen.org/gerrit/gitweb?p=platform/adaptation/libtbm-shm.git;a=summary) | Backend for a target device which 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](https://review.tizen.org/gerrit/gitweb?p=platform/adaptation/libtbm-dumb.git;a=summary) | Backend for a 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](https://review.tizen.org/gerrit/gitweb?p=platform/adaptation/spreadtrum/libtbm-sprd.git;a=summary) | Backend for a target device which uses the Spreadtrum chipset only. The `sprd` backend module uses the `drm` gem memory interface but some `ioctl` are only provided by the `sprd drm` kernel. |
+| `libtbm-exynos` | [platform/adaptation/samsung_exynos/libtbm-exynos](https://review.tizen.org/gerrit/gitweb?p=platform/adaptation/samsung_exynos/libtbm-exynos.git;a=summary) | Backend for a target device which uses the exynos chipset only. The `exynos` backend module uses the `drm` gem memory interface but some `ioctl` are only provided by `exynos drm` kernel. |
+| `libtbm-vigs` | [platform/adaptation/emulator/libtbm-vigs](https://review.tizen.org/gerrit/gitweb?p=platform/adaptation/emulator/libtbm-vigs.git;a=summary) | Backend for a target device which supports the VIGS interface. The `vigs` backend is used by the emulator target. |
+
+### Reference
+
+For more information about TBM and the TBM backend, see [Tizen Buffer Manager (TBM)](https://wiki.tizen.org/TBM).
+
projects / platform / core / uifw / libtbm.git / commitdiff