backend: modify the comments on the header file.

Change-Id: Ie8f972382d6fe07b934b7dff18a937bf1eb08a5b

diff --git a/src/tbm_backend.h b/src/tbm_backend.h
index a86d35d..b315720 100644 (file)
--- a/src/tbm_backend.h
+++ b/src/tbm_backend.h
@@ -55,7 +55,7 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  * ABI versions.  Each version has a major and minor revision.  Modules
  * using lower minor revisions must work with servers of a higher minor
  * revision.  There is no compatibility between different major revisions.
- * Whenever the ABI_ANSIC_VERSION is changed, the others must also be
+ * Whenever the ABI_MAJOR_VERSION is changed, the others must also be
  * changed.  The minor revision mask is 0x0000FFFF and the major revision
  * mask is 0xFFFF0000.
  */
@@ -68,7 +68,7 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #define TBM_BACKEND_ABI_LATEST_VERSION TBM_BACKEND_ABI_VERSION_3_0 /**< the latest version of the tbm backend abi  */
 
 /**
- * @brief The backend module data
+ * @brief The backend bufmgr data
  * @details
  * The init() function of #tbm_backend_module returns the backend module data.
  * This handle will be used in #tbm_backend_bufmgr_func.
@@ -101,6 +101,10 @@ typedef struct _tbm_backend_bo_func tbm_backend_bo_func;
 struct _tbm_backend_bufmgr_func {
        /**
         * @brief Get the capabilities of a buffer manager
+        * @remarks 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.
         * @param[in] bufmgr_data The backend module data
         * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
         * @return the capabilities of a backend modul
@@ -110,7 +114,7 @@ struct _tbm_backend_bufmgr_func {
 
        /**
        * @brief set(bind) the native display
-       * @param[in] bufmgr_data The backend module data
+       * @param[in] bufmgr_data The backend bufmgr data
        * @param[in] native_display : the native display (wl_display in wayland window system)
        * @return #TBM_ERROR_NONE if success. Otherwise, error value.
        */
@@ -119,7 +123,7 @@ struct _tbm_backend_bufmgr_func {
 
        /**
        * @brief get the formats list and the num to be supported by backend.
-       * @param[in] bufmgr_data The backend module data
+       * @param[in] bufmgr_data The backend bufmgr data
        * @param[out] **formats : format array list. it is allocated by backend funtion
        * @param[out] *num : the number of the formats to be supported by backend
        * @return #TBM_ERROR_NONE if success. Otherwise, error value.
@@ -128,16 +132,16 @@ struct _tbm_backend_bufmgr_func {
                                                                                        uint32_t **formats, uint32_t *num);
 
        /**
-       * @brief get the plane data of the surface.
-       * @param[in] bufmgr_data The backend module data
+       * @brief get the plane data of the plane_idx according to the format.
+       * @param[in] bufmgr_data The backend bufmgr data
        * @param[in] format : the format of the surface
-       * @param[in] plane_idx : the format of the surface
-       * @param[in] width : the width of the surface
-       * @param[in] height : the height of the surface
-       * @param[out] size : the size of the plane
-       * @param[out] offset : the offset of the plane
-       * @param[out] pitch : the pitch of the plane
-       * @param[out] bo_idx : the bo index of the plane
+       * @param[in] plane_idx : the index of the plane
+       * @param[in] width : the width of the surface with the format
+       * @param[in] height : the height of the surface with the format
+       * @param[out] size : the size of the plane index
+       * @param[out] offset : the offset of the plane index at the bo index
+       * @param[out] pitch : the pitch of the plane index
+       * @param[out] bo_idx : the bo index of the plane index
        * @return #TBM_ERROR_NONE if success. Otherwise, error value.
        */
        tbm_error_e (*bufmgr_get_plane_data)(tbm_backend_bufmgr_data *bufmgr_data,
@@ -146,54 +150,54 @@ struct _tbm_backend_bufmgr_func {
                                                                        uint32_t *pitch, int *bo_idx);
 
        /**
-       * @brief allocate the bo_data of the tbm_backend
-       * @param[in] bufmgr_data The backend module data
-       * @param[in] size : the size of buffer object
-       * @param[in] flags : the flags of memory type
+       * @brief allocate the bo data of the tbm_backend
+       * @param[in] bufmgr_data The backend bufmgr data
+       * @param[in] size : the size of bo data
+       * @param[in] mem_types : the memory types
        * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
        * @return pointer of the bo_data of the tbm backend.
        */
        tbm_backend_bo_data *(*bufmgr_alloc_bo)(tbm_backend_bufmgr_data *bufmgr_data,
-                                                               unsigned int size, tbm_bo_memory_type mem_type,
+                                                               unsigned int size, tbm_bo_memory_type mem_types,
                                                                tbm_error_e *error);
 
        /**
-       * @brief allocate the buffer object for tbm surface
-       * @param[in] bo : the buffer object
-       * @param[in] width : the width of surface
-       * @param[in] height : the height of surface
-       * @param[in] format : the format of surface
-       * @param[in] flags : the flags of memory type
-       * @param[in] bo_idx : the index of bo in surface
+       * @brief allocate the bo data of the bo index according to the format
+       * @param[in] bufmgr_data The backend bufmgr data
+       * @param[in] width : the width of the surface with the format
+       * @param[in] height : the height of the surface with the format
+       * @param[in] format : the format of the surface
+       * @param[in] mem_types : the memory types
+       * @param[in] bo_idx : the bo index of the surface
        * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
-       * @return pointer of the bo_data of the tbm backend.
+       * @return pointer of the bo data of the tbm backend.
        */
        tbm_backend_bo_data *(*bufmgr_alloc_bo_with_format)(tbm_backend_bufmgr_data *bufmgr_data,
                                                                                        int format, int bo_idx, int width,
-                                                                                       int height, tbm_bo_memory_type mem_type,
+                                                                                       int height, tbm_bo_memory_type mem_types,
                                                                                        tbm_error_e *error);
 
        /**
-       * @brief import the buffer object associated with the prime fd.
+       * @brief import the bo data associated with the tdm_fd(prime fd).
        * @remarks tbm_fd must be free by user.
-       * @remarks If the backend doesn't support a buffer sharing by tbm fd,
-       *               fucntion pointer must be set to NULL.
-       * @param[in] bufmgr_data The backend module data
-       * @param[in] fd : the prime fd associated with the buffer object
+       * @remarks It must be supported at the backend module. To sharing the tdm_fd(prime fd)
+       *        among the processes is the essential feature to run the graphic rendering.
+       * @param[in] bufmgr_data The backend bufmgr data
+       * @param[in] fd : the tdm_fd(prime fd) associated with the bo data
        * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
-       * @return pointer of the bo_data of the tbm backend.
+       * @return pointer of the bo data of the tbm backend.
        */
        tbm_backend_bo_data *(*bufmgr_import_fd)(tbm_backend_bufmgr_data *bufmgr_data,
                                                                        tbm_fd fd, tbm_error_e *error);
 
        /**
-       * @brief import the buffer object associated with the key.
+       * @brief import the bo data associated with the tdm_key.
        * @remarks If the backend doesn't support a buffer sharing by tbm key,
-                       fucntion pointer must be set to NULL.
-       * @param[in] bufmgr_data The backend module data
-       * @param[in] key : the key associated with the buffer object
+       *        fucntion pointer must be set to NULL.
+       * @param[in] bufmgr_data The backend bufmgr data
+       * @param[in] key : the tdm_key associated with the bo data
        * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
-       * @return pointer of the bo_data of the tbm backend.
+       * @return pointer of the bo data of the tbm backend.
        */
        tbm_backend_bo_data *(*bufmgr_import_key)(tbm_backend_bufmgr_data *bufmgr_data,
                                                                                tbm_key key, tbm_error_e *error);
@@ -212,14 +216,14 @@ struct _tbm_backend_bufmgr_func {
  */
 struct _tbm_backend_bo_func {
        /**
-       * @brief free the buffer object.
+       * @brief free the bo data.
        * @param[in] bo_data : the bo data of the tbm backend
        * @return #TBM_ERROR_NONE if success. Otherwise, error value.
        */
        void (*bo_free)(tbm_backend_bo_data *bo_data);
 
        /**
-       * @brief get the size of a bo.
+       * @brief get the size of a bo data.
        * @param[in] bo_data : the bo data of the tbm backend
        * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
        * @return size if this function succeeds, otherwise 0.
@@ -227,7 +231,7 @@ struct _tbm_backend_bo_func {
        int (*bo_get_size)(tbm_backend_bo_data *bo_data, tbm_error_e *error);
 
        /**
-       * @brief get the tbm memory type
+       * @brief get the tbm memory types
        * @param[in] bo_data : the bo data of the tbm backend
        * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
        * @see #TBM_BO_FLAGS #tbm_bo_memory_type
@@ -241,34 +245,34 @@ struct _tbm_backend_bo_func {
        * @param[in] bo_data : the bo data of the tbm backend
        * @param[in] device : the device type to get a handle
        * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
-       * @return the handle of the buffer object
+       * @return the handle of the bo data
        */
        tbm_bo_handle (*bo_get_handle)(tbm_backend_bo_data *bo_data,
                                                                tbm_bo_device_type device, tbm_error_e *error);
 
        /**
-       * @brief map the buffer object according to the device type and the option.
+       * @brief map the bo data according to the device type and the option.
        * @param[in] bo_data : the bo data of the tbm backend
        * @param[in] device : the device type to get a handle
-       * @param[in] opt : the option to access the buffer object
+       * @param[in] opt : the option to access the bo data
        * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
-       * @return the handle of the buffer object
+       * @return the handle of the bo data
        */
        tbm_bo_handle (*bo_map)(tbm_backend_bo_data *bo_data, tbm_bo_device_type device,
                                                tbm_bo_access_option opt, tbm_error_e *error);
 
        /**
-       * @brief unmap the buffer object.
+       * @brief unmap the bo data.
        * @param[in] bo_data : the bo data of the tbm backend
        * @return #TBM_ERROR_NONE if success. Otherwise, error value.
        */
        tbm_error_e (*bo_unmap)(tbm_backend_bo_data *bo_data);
 
        /**
-       * @brief lock the buffer object with a device and an opt.
+       * @brief lock the bo data with a device and an opt.
        * @param[in] bo_data : the bo data of the tbm backend
        * @param[in] device : the device type to get a handle
-       * @param[in] opt : the option to access the buffer object
+       * @param[in] opt : the option to access the bo data
        * @return #TBM_ERROR_NONE if success. Otherwise, error value.
        * @remark This function pointer could be null.
        */
@@ -276,7 +280,7 @@ struct _tbm_backend_bo_func {
                                                tbm_bo_access_option opt);
 
        /**
-       * @brief unlock the buffer object.
+       * @brief unlock the bo data.
        * @param[in] bo_data : the bo data of the tbm backend
        * @return #TBM_ERROR_NONE if success. Otherwise, error value.
        * @remark This function pointer could be null.
@@ -284,23 +288,23 @@ struct _tbm_backend_bo_func {
        tbm_error_e (*bo_unlock)(tbm_backend_bo_data *bo_data);
 
        /**
-       * @brief export the buffer object
+       * @brief export the bo data to the tdm_fd(prime fd)
        * @remarks tbm_fd must be free by user.
-       * @remarks If the backend doesn't support a buffer sharing by tbm fd,
-                       fucntion pointer must be set to NULL.
+       * @remarks It must be supported at the backend module. To sharing the tdm_fd(prime fd)
+       *        among the processes is the essential feature to run the graphic rendering.
        * @param[in] bo_data : the bo data of the tbm backend
        * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
-       * @return tbm_fd associated with the buffer object
+       * @return tbm_fd associated with the bo data
        */
        tbm_fd (*bo_export_fd)(tbm_backend_bo_data *bo_data, tbm_error_e *error);
 
        /**
-       * @brief export the buffer object
+       * @brief export the bo data to the tdm_key
        * @remarks If the backend doesn't support a buffer sharing by tbm key,
-                       fucntion pointer must be set to NULL.
-       * @param[in] bo : the buffer object
+       *        fucntion pointer must be set to NULL.
+       * @param[in] bo_data : the bo data of the tbm backend
        * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value.
-       * @return key associated with the buffer object
+       * @return key associated with the bo data
        */
        tbm_key (*bo_export_key)(tbm_backend_bo_data *bo_data, tbm_error_e *error);