From: Unsung Lee Date: Mon, 9 Sep 2024 04:19:24 +0000 (+0900) Subject: cpu-boosting: Update description of resource APIs X-Git-Tag: accepted/tizen/unified/20240924.153237~1 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=783efbd09403b876d27efc05f129056385b35f79;p=platform%2Fcore%2Fapi%2Fresource.git 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 --- diff --git a/include/cpu-boosting.h b/include/cpu-boosting.h index 03cd34f..20914c5 100644 --- 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);