cpu-boosting: Update description of resource APIs

Update description of resource APIs in @brief, @details, @remarks, @see, and @code
to supplement the explanation.

Change-Id: I3a5c34005e19956f8107da4c79edceaa6e902ff7
Signed-off-by: Unsung Lee <unsung.lee@samsung.com>

diff --git a/include/cpu-boosting.h b/include/cpu-boosting.h
index 03cd34f98216b9a36da575966d41e8eefee8ee2b..20914c52a4f791449b9765d913750e2f20a3c3c3 100644 (file)
--- a/include/cpu-boosting.h
+++ b/include/cpu-boosting.h
@@ -31,14 +31,14 @@ extern "C" {
 
 /**
  * @partner
- * @brief Sets cpu boosting for the target process (pid/tids).
+ * @brief Sets cpu boosting for the target process (pid/tids) to the desired level for as long as required.
  *
  * @details Another set request on the boosted target overrides the previous one.
  * @since_tizen 6.5
  *
  * @privlevel partner
  * @privilege http://tizen.org/privilege/internal/default/partner
- * @remarks This function is an internal API, so it can be used only by partner level developers. \n
+ * @remarks An internal API, so it can be used only by partner level developers. \n
  *          In addition, the developers cannot arbitrary choose whether to enforce this privilege or not.
  * @param[in] pid The target process pid/tids \n
  *                If pid.pid is nonzero, pid.tid and pid.tid_count are ignored, \n
@@ -56,6 +56,39 @@ extern "C" {
  * @retval #RESOURCE_ERROR_NONE                         Successful
  * @retval #RESOURCE_ERROR_PERMISSION_DENIED            Permission Denied
  * @retval #RESOURCE_ERROR_INVALID_PARAMETER            Invalid Parameter
+ * @see    resource_clear_cpu_boosting()
+ * @see    resource_get_cpu_boosting_level()
+ * @code
+ *      resource_pid_t pid;
+ *      cpu_boosting_level_e cpu_boosting_level = CPU_BOOSTING_LEVEL_STRONG;
+ *      cpu_boosting_flag_e flags = 0;
+ *      int timeout_msec = -1;
+ *      cpu_boosting_level_info_t cur_level_info;
+ *      int ret;
+ *
+ *      pid.pid = 0;
+ *      pid.tid = NULL;
+ *      pid.tid_count = 0;
+ *
+ *      // Set CPU boosting for the target process
+ *      ret = resource_set_cpu_boosting(pid, cpu_boosting_level, flags, timeout_msec);
+ *      if (ret != RESOURCE_ERROR_NONE)
+ *              return ret;
+ *
+ *      // Get CPU boosting level of the target process
+ *      ret = resource_get_cpu_boosting_level(pid, &cur_level_info);
+ *      if (ret != RESOURCE_ERROR_NONE)
+ *              return ret;
+ *
+ *      // Free the cpu boosting level list of threads
+ *      if (cur_level_info.tid_level)
+ *              free(cur_level_info.tid_level);
+ *
+ *      // Clear CPU boosting for the target process
+ *      ret = resource_clear_cpu_boosting(pid);
+ *      if (ret != RESOURCE_ERROR_NONE)
+ *              return ret;
+ * @endcode
  */
 int resource_set_cpu_boosting (resource_pid_t pid, cpu_boosting_level_e level, cpu_boosting_flag_e flags, int timeout_msec);
 
@@ -68,7 +101,7 @@ int resource_set_cpu_boosting (resource_pid_t pid, cpu_boosting_level_e level, c
  *
  * @privlevel partner
  * @privilege http://tizen.org/privilege/internal/default/partner
- * @remarks This function is an internal API, so it can be used only by partner level developers. \n
+ * @remarks An internal API, so it can be used only by partner level developers. \n
  *          In addition, the developers cannot arbitrary choose whether to enforce this privilege or not.
  * @param[in] pid The target process pid/tids \n
  *                If pid.pid is nonzero, pid.tid and pid.tid_count are ignored, \n
@@ -81,17 +114,21 @@ int resource_set_cpu_boosting (resource_pid_t pid, cpu_boosting_level_e level, c
  * @retval #RESOURCE_ERROR_NONE                         Successful
  * @retval #RESOURCE_ERROR_PERMISSION_DENIED            Permission Denied
  * @retval #RESOURCE_ERROR_INVALID_PARAMETER            Invalid Parameter
+ * @see    resource_set_cpu_boosting()
+ * @see    resource_get_cpu_boosting_level()
  */
 int resource_clear_cpu_boosting (resource_pid_t pid);
 
 /**
  * @partner
  * @brief Gets the cpu boosting level for the target process (pid/tids).
+ *
+ * @details Obtains a list of cpu boosting level and the number of threads.
  * @since_tizen 6.5
  *
  * @privlevel partner
  * @privilege http://tizen.org/privilege/internal/default/partner
- * @remarks This function is an internal API, so it can be used only by partner level developers. \n
+ * @remarks An internal API, so it can be used only by partner level developers. \n
  *          In addition, the developers cannot arbitrary choose whether to enforce this privilege or not.
  * @param[in] pid The target process pid/tids \n
  *                If pid.pid is nonzero, pid.tid and pid.tid_count are ignored, \n
@@ -107,18 +144,24 @@ int resource_clear_cpu_boosting (resource_pid_t pid);
  * @retval #RESOURCE_ERROR_NONE                         Successful
  * @retval #RESOURCE_ERROR_PERMISSION_DENIED            Permission Denied
  * @retval #RESOURCE_ERROR_INVALID_PARAMETER            Invalid Parameter
+ * @see    resource_set_cpu_boosting()
+ * @see    resource_clear_cpu_boosting()
  */
 int resource_get_cpu_boosting_level (resource_pid_t pid, cpu_boosting_level_info_t *level);
 
 /**
  * @partner
  * @brief Sets cpu resource inheritance from the source tid to the destination process (pid/tids).
+ *
+ * @details The cpu boosting level of the destination process becomes equal to the source cpu boosting level.
  * @since_tizen 6.5
  *
  * @privlevel partner
  * @privilege http://tizen.org/privilege/internal/default/partner
- * @remarks This function is an internal API, so it can be used only by partner level developers. \n
- *          In addition, the developers cannot arbitrary choose whether to enforce this privilege or not.
+ * @remarks An internal API, so it can be used only by partner level developers. \n
+ *          In addition, the developers cannot arbitrary choose whether to enforce this privilege or not. \n
+ *          It should be called from source after
+ *          calling the resource_register_cpu_inheritance_destination() function in the destination.
  * @param[in] source_tid The caller thread tid
  * @param[in] dest_process The name of destination process
  * @param[in] timeout_msec The timeout in milliseconds, -1 to apply inheritance permanently
@@ -127,18 +170,38 @@ int resource_get_cpu_boosting_level (resource_pid_t pid, cpu_boosting_level_info
  * @retval #RESOURCE_ERROR_NONE                         Successful
  * @retval #RESOURCE_ERROR_PERMISSION_DENIED            Permission Denied
  * @retval #RESOURCE_ERROR_INVALID_PARAMETER            Invalid Parameter
+ * @see    resource_clear_cpu_inheritance()
+ * @see    resource_register_cpu_inheritance_destination()
+ * @see    resource_unregister_cpu_inheritance_destination()
+ * @code
+ *      // Executed in the source side
+ *      // Set cpu resource inheritance
+ *      int ret = resource_set_cpu_inheritance(gettid(), "test-service", -1);
+ *      if (ret != RESOURCE_ERROR_NONE)
+ *              return ret;
+ *
+ *      // Clear cpu resource inheritance
+ *      ret = resource_clear_cpu_inheritance(gettid(), "test-service");
+ *      if (ret != RESOURCE_ERROR_NONE)
+ *              return ret;
+ * @endcode
  */
 int resource_set_cpu_inheritance (pid_t source_tid, const char *dest_process, int timeout_msec);
 
 /**
  * @partner
  * @brief Clears cpu resource inheritance from the source tid to the destination process (pid/tids).
+ *
+ * @details Terminates cpu boosting of the destination process, \n
+ *          which has already been boosted due to cpu resource inheritance.
  * @since_tizen 6.5
  *
  * @privlevel partner
  * @privilege http://tizen.org/privilege/internal/default/partner
- * @remarks This function is an internal API, so it can be used only by partner level developers. \n
- *          In addition, the developers cannot arbitrary choose whether to enforce this privilege or not.
+ * @remarks An internal API, so it can be used only by partner level developers. \n
+ *          In addition, the developers cannot arbitrary choose whether to enforce this privilege or not. \n
+ *          It should be called from source after
+ *          calling the resource_register_cpu_inheritance_destination() function in the destination.
  * @param[in] source_tid The caller thread's tid
  * @param[in] dest_process The name of destination process
  *
@@ -146,17 +209,22 @@ int resource_set_cpu_inheritance (pid_t source_tid, const char *dest_process, in
  * @retval #RESOURCE_ERROR_NONE                         Successful
  * @retval #RESOURCE_ERROR_PERMISSION_DENIED            Permission Denied
  * @retval #RESOURCE_ERROR_INVALID_PARAMETER            Invalid Parameter
+ * @see    resource_set_cpu_inheritance()
+ * @see    resource_register_cpu_inheritance_destination()
+ * @see    resource_unregister_cpu_inheritance_destination()
  */
 int resource_clear_cpu_inheritance (pid_t source_tid, const char *dest_process);
 
 /**
  * @partner
  * @brief Registers a destination process (pid/tids) for cpu resource inheritance.
+ *
+ * @details Registers the target process for CPU boosting through CPU resource inheritance.
  * @since_tizen 6.5
  *
  * @privlevel partner
  * @privilege http://tizen.org/privilege/internal/default/partner
- * @remarks This function is an internal API, so it can be used only by partner level developers. \n
+ * @remarks An internal API, so it can be used only by partner level developers. \n
  *          In addition, the developers cannot arbitrary choose whether to enforce this privilege or not.
  * @param[in] dest_process The name of destination process
  * @param[in] pid The destination process pid/tids \n
@@ -170,17 +238,40 @@ int resource_clear_cpu_inheritance (pid_t source_tid, const char *dest_process);
  * @retval #RESOURCE_ERROR_NONE                         Successful
  * @retval #RESOURCE_ERROR_PERMISSION_DENIED            Permission Denied
  * @retval #RESOURCE_ERROR_INVALID_PARAMETER            Invalid Parameter
+ * @see    resource_set_cpu_inheritance()
+ * @see    resource_clear_cpu_inheritance()
+ * @see    resource_unregister_cpu_inheritance_destination()
+ * @code
+ *      int ret;
+ *      resource_pid_t pid;
+ *      pid.pid = 0;
+ *      pid.tid = NULL;
+ *      pid.tid_count = 0;
+ *
+ *      // Executed in the destination side
+ *      // Register destination process for cpu resource inheritance (called in destination)
+ *      ret = resource_register_cpu_inheritance_destination("test-service", pid);
+ *      if (ret != RESOURCE_ERROR_NONE)
+ *              return;
+ *
+ *      // Unregister destination process for cpu resource inheritance
+ *      ret = resource_unregister_cpu_inheritance_destination("test-service");
+ *      if (ret != RESOURCE_ERROR_NONE)
+ *              return;
+ * @endcode
  */
 int resource_register_cpu_inheritance_destination (const char *dest_process, resource_pid_t pid);
 
 /**
  * @partner
  * @brief Unregisters a destination process for cpu resource inheritance.
+ *
+ * @details Prevents the destination process from receiving further cpu resource inheritance.
  * @since_tizen 6.5
  *
  * @privlevel partner
  * @privilege http://tizen.org/privilege/internal/default/partner
- * @remarks This function is an internal API, so it can be used only by partner level developers. \n
+ * @remarks An internal API, so it can be used only by partner level developers. \n
  *          In addition, the developers cannot arbitrary choose whether to enforce this privilege or not.
  * @param[in] dest_process The name of destination process
  *
@@ -188,6 +279,9 @@ int resource_register_cpu_inheritance_destination (const char *dest_process, res
  * @retval #RESOURCE_ERROR_NONE                         Successful
  * @retval #RESOURCE_ERROR_PERMISSION_DENIED            Permission Denied
  * @retval #RESOURCE_ERROR_INVALID_PARAMETER            Invalid Parameter
+ * @see    resource_set_cpu_inheritance()
+ * @see    resource_clear_cpu_inheritance()
+ * @see    resource_register_cpu_inheritance_destination()
  */
 int resource_unregister_cpu_inheritance_destination (const char *dest_process);