doc/porting_guide/tbm_porting_guide_2.x.md

   1 ## Buffer Management
   2
   3 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`.
   4
   5 **Figure: TBM backend**
   6
   7 ![TBM backend](media/800px-tbm-backend.png)
   8
   9         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.
  10
  11         ```
  12         sh-3.2# ls -al
  13         lrwxrwxrwx  1 root root    14 Jul 28  2016 libtbm_default.so -> libtbm_sprd.so
  14         lrwxrwxrwx  1 root root    20 Jul 28  2016 libtbm_sprd.so -> libtbm_sprd.so.0.0.0
  15         lrwxrwxrwx  1 root root    20 Jul 28  2016 libtbm_sprd.so.0 -> libtbm_sprd.so.0.0.0
  16         -rwxr-xr-x  1 root root 26728 Jun 29  2016 libtbm_sprd.so.0.0.0
  17         ```
  18
  19 ### Initialing the TBM Backend Module
  20
  21         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.
  22
  23         > **Note**
  24         >
  25         > Do not change the name of the symbol in the TBM backend module.
  26
  27         ```cpp
  28         /*
  29               @brief tbm module data
  30                      Data type for the entry point of the backend module
  31                          */
  32         typedef struct {
  33                     TBMModuleVersionInfo *vers; /* TBM module information */
  34                             ModuleInitProc init; /* init function of a backend module */
  35         } TBMModuleData;
  36
  37 typedef int (*ModuleInitProc) (tbm_bufmgr, int);
  38 ```
  39
  40 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`).
  41
  42 ```cpp
  43 tbm_bufmgr_backend tbm_backend_alloc(void);
  44 void tbm_backend_free(tbm_bufmgr_backend backend);
  45 int tbm_backend_init(tbm_bufmgr bufmgr, tbm_bufmgr_backend backend);
  46 ```
  47
  48 ```cpp
  49 MODULEINITPPROTO (init_tbm_bufmgr_priv);
  50
  51 static TBMModuleVersionInfo DumbVersRec = {
  52             "shm",
  53                     "Samsung",
  54                             TBM_ABI_VERSION,
  55 };
  56
  57 TBMModuleData tbmModuleData = {&DumbVersRec, init_tbm_bufmgr_priv};
  58
  59 int
  60 init_tbm_bufmgr_priv(tbm_bufmgr bufmgr, int fd) {
  61             tbm_bufmgr_backend bufmgr_backend;
  62
  63                     bufmgr_shm = calloc(1, sizeof(struct _tbm_bufmgr_shm));
  64
  65                             bufmgr_backend = tbm_backend_alloc();
  66
  67                                     bufmgr_backend->priv = (void *)bufmgr_shm;
  68                                             bufmgr_backend->bufmgr_deinit = tbm_shm_bufmgr_deinit,
  69                                                             bufmgr_backend->bo_size = tbm_shm_bo_size,
  70                                                                     bufmgr_backend->bo_alloc = tbm_shm_bo_alloc,
  71                                                                             bufmgr_backend->bo_free = tbm_shm_bo_free,
  72                                                                                     bufmgr_backend->bo_import = tbm_shm_bo_import,
  73                                                                                             bufmgr_backend->bo_import_fd = NULL,
  74                                                                                                     bufmgr_backend->bo_export = tbm_shm_bo_export,
  75                                                                                                             bufmgr_backend->bo_export_fd = NULL,
  76                                                                                                                     bufmgr_backend->bo_get_handle = tbm_shm_bo_get_handle,
  77                                                                                                                             bufmgr_backend->bo_map = tbm_shm_bo_map,
  78                                                                                                                                     bufmgr_backend->bo_unmap = tbm_shm_bo_unmap,
  79                                                                                                                                             bufmgr_backend->bo_lock = NULL;
  80                                                     bufmgr_backend->bo_unlock = NULL;
  81                                                             bufmgr_backend->surface_get_plane_data = tbm_shm_surface_get_plane_data;
  82                                                                     bufmgr_backend->surface_supported_format = tbm_shm_surface_supported_format;
  83
  84                                                                             if (!tbm_backend_init(bufmgr, bufmgr_backend)) {
  85                                                                                                 tbm_backend_free(bufmgr_backend);
  86                                                                                                                 free(bufmgr_shm);
  87
  88                                                                                                                                 return 0;
  89                                                                                                                                             }
  90
  91                                                                                     return 1;
  92 }
  93 ```
  94
  95 ### Porting the OAL Interface
  96
  97 TBM provides the header files to implement the TBM backend module.
  98
  99 **Table: TBM backend module header files**
 100
 101 | Header file                              | Description                              |
 102 | ---------------------------------------- | ---------------------------------------- |
 103 | [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. |
 104 | [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. |
 105 | [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. |
 106 | [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`. |
 107
 108 #### TBM Backend Interface
 109
 110 The following table lists the TBM backend interface functions for initializing and deinitializing.
 111
 112 **Table: Initializing and deinitializing functions**
 113
 114 | Function                       | Description                              |           |
 115 | ------------------------------ | ---------------------------------------- | --------- |
 116 | `ModuleInitProc()`             | The `init` function of a backend module. | Mandatory |
 117 | `bufmgr_deinit()`              | Deinitialize the buffer manager privately. | Mandatory |
 118 | `bufmgr_bind_native_display()` | If the backend needs to get the native display, use this backend function. | Optional  |
 119
 120 The following table lists the TBM backend interface functions for `tbm_bo`.
 121
 122 **Table: tbm_bo functions**
 123
 124 | Function          | Description                              | Mandatory                                         |
 125 | ----------------- | ---------------------------------------- | ---------------------------------------- |
 126 | `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                                |
 127 | `bo_free()`       | Frees the buffer object. The frontend calls this function when it does not use the `bo` private. | Yes                                |
 128 | `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                                 |
 129 | `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                                 |
 130 | `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`.) |
 131 | `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`.) |
 132 | `bo_get_flags()`  | Gets the TBM flags of memory type.        | Yes                                |
 133 | `bo_size()`       | Gets the size of a buffer object.        | Yes                                |
 134 | `bo_get_handle()` | Gets the `tbm_bo_handle` according to the device type. | Yes                                |
 135 | `bo_map()`        | Maps the buffer object according to the device type and the option. | Yes                                |
 136 | `bo_unmap()`      | Unmaps the buffer object.                | Yes                                |
 137 | `bo_lock()`       | Locks the buffer object with a device and an opt. | No                                 |
 138 | `bo_unlock()`     | Unlocks the buffer object.               | No                                 |
 139
 140 The following table lists the TBM backend interface functions for `tbm_surface`.
 141
 142 **Table: tbm_surface functions**
 143
 144 | Function                     | Description                              | Mandatory          |
 145 | ---------------------------- | ---------------------------------------- | --------- |
 146 | `surface_supported_format()` | Queries the format list and the number to be supported by backend. | Yes |
 147 | `surface_get_plane_data()`   | Gets the plane data, such as the size, offset, pitch, and buffer object index of the surface. | Yes |
 148 | `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  |
 149
 150 The following table lists the TBM buffer memory types.
 151
 152 **Table: TBM buffer memory types**
 153
 154 | Buffer memory type   | Description                              |
 155 | -------------------- | ---------------------------------------- |
 156 | `TBM_BO_DEFAULT`     | Default memory: it depends on the backend |
 157 | `TBM_BO_SCANOUT`     | Scanout memory                           |
 158 | `TBM_BO_NONCACHABLE` | Non-cachable memory                      |
 159 | `TBM_BO_WC`          | Write-combine memory                     |
 160 | `TBM_BO_VENDOR`      | Vendor specific memory (depends on the backend) |
 161
 162 The following table lists the TBM buffer device types.
 163
 164 **Table: TBM buffer device types**
 165
 166 | Device type          | Description                              |
 167 | -------------------- | ---------------------------------------- |
 168 | `TBM_DEVICE_DEFAULT` | Device type to get the default handle |
 169 | `TBM_DEVICE_CPU`     | Device type to get the virtual memory |
 170 | `TBM_DEVICE_2D`      | Device type to get the 2D memory handle |
 171 | `TBM_DEVICE_3D`      | Device type to get the 3D memory handle |
 172 | `TBM_DEVICE_MM`      | Device type to get the multimedia handle |
 173
 174 The following table lists the TBM buffer access options.
 175
 176 **Table: TBM buffer access options**
 177
 178 | Access option       | Description                              |
 179 | ------------------- | ---------------------------------------- |
 180 | `TBM_OPTION_READ`   | Access option to read                |
 181 | `TBM_OPTION_WRITE`  | Access option to write               |
 182 | `TBM_OPTION_VENDOR` | Vendor-specific option that depends on the backend |
 183
 184 #### TBM DRM Helper Functions
 185
 186 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.
 187
 188 **Table: DRM helper functions**
 189
 190 | Function                                 | Description                              |
 191 | ---------------------------------------- | ---------------------------------------- |
 192 | `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. |
 193 | `tbm_drm_helper_wl_auth_server_deinit()` | Deinitializes the `drm` authentication in the display server. |
 194 | `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. |
 195 | `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. |
 196 | `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. |
 197 | `tbm_drm_helper_get_auth_info()`         | Client gets the authenticated `fd` and device info from the display server. |
 198
 199 ### TBM Backends
 200
 201 The following table lists the TBM backends.
 202
 203 **Table: TBM backends**
 204
 205 | Backend         | Project ([http://review.tizen.org](http://review.tizen.org/)) | Description                              |
 206 | --------------- | ---------------------------------------- | ---------------------------------------- |
 207 | `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. |
 208 | `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. |
 209 | `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. |
 210 | `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. |
 211 | `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. |
 212
 213 ### Reference
 214
 215 For more information about TBM and the TBM backend, see [Tizen Buffer Manager (TBM)](https://wiki.tizen.org/TBM).
 216