From a076cdb2698b55c0224ec374f05333f1e14363b6 Mon Sep 17 00:00:00 2001 From: Unsung Lee Date: Tue, 18 Oct 2022 16:43:35 +0900 Subject: [PATCH] Modify headers to meet public API conditions modify the privilege description for cpu-boosting APIs. Change-Id: Ic4484b9ba61a26809600d08c4ebb83898669f6d5 Signed-off-by: Unsung Lee --- include/cpu-boosting-type.h | 40 ++++++++++++++------ include/cpu-boosting.h | 74 ++++++++++++++++++++++++++++--------- 2 files changed, 84 insertions(+), 30 deletions(-) diff --git a/include/cpu-boosting-type.h b/include/cpu-boosting-type.h index 25555e0..a5e862a 100644 --- a/include/cpu-boosting-type.h +++ b/include/cpu-boosting-type.h @@ -29,31 +29,47 @@ extern "C" { #endif +/** + * @brief Enumeration for cpu boosting flag. + * @since_tizen 6.5 + */ typedef enum resource_cpu_boosting_flag { - CPU_BOOSTING_RESET_ON_FORK = 0x01, + CPU_BOOSTING_RESET_ON_FORK = 0x01, /**< CPU RESET ON FORK */ } cpu_boosting_flag_e; +/** + * @brief Enumeration for cpu boosting level. + * @since_tizen 6.5 + */ typedef enum resource_cpu_boosting_level { - CPU_BOOSTING_LEVEL_NONE = 0, - CPU_BOOSTING_LEVEL_STRONG = 1, - CPU_BOOSTING_LEVEL_MEDIUM, - CPU_BOOSTING_LEVEL_WEAK, - CPU_BOOSTING_LEVEL_END, + CPU_BOOSTING_LEVEL_NONE = 0, /**< CPU BOOSTING LEVEL NONE */ + CPU_BOOSTING_LEVEL_STRONG = 1, /**< CPU BOOSTING LEVEL STRONG */ + CPU_BOOSTING_LEVEL_MEDIUM, /**< CPU BOOSTING LEVEL MEDIUM */ + CPU_BOOSTING_LEVEL_WEAK, /**< CPU BOOSTING LEVEL WEAK */ + CPU_BOOSTING_LEVEL_END, /**< CPU BOOSTING LEVEL END */ } cpu_boosting_level_e; +/** + * @brief Structure for process and thread group. + * @since_tizen 6.5 + */ typedef struct resource_pid_info { - pid_t pid; - pid_t *tid; - int tid_count; + pid_t pid; /**< process id */ + pid_t *tid; /**< thread group */ + int tid_count; /**< the number of thread */ } resource_pid_t; +/** + * @brief Structure for level of thread group. + * @since_tizen 6.5 + */ typedef struct resource_cpu_boosting_level_info { - int *tid_level; - int tid_count; + int *tid_level; /**< levels of thread group */ + int tid_count; /**< the number of thread */ } cpu_boosting_level_info_t; #ifdef __cplusplus } #endif -#endif // __TIZEN_SYSTEM_CPU_BOOSTING_TYPE_H__ +#endif /* __TIZEN_SYSTEM_CPU_BOOSTING_TYPE_H__ */ diff --git a/include/cpu-boosting.h b/include/cpu-boosting.h index 03ed613..03cd34f 100644 --- a/include/cpu-boosting.h +++ b/include/cpu-boosting.h @@ -30,14 +30,16 @@ extern "C" { #endif /** - * @brief Set cpu boosting for the target process (pid/tids). - * @since_tizen 6.5 + * @partner + * @brief Sets cpu boosting for the target process (pid/tids). * * @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 + * 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 * and cpu boosting is applied for all the threads of pid.pid. \n @@ -46,23 +48,28 @@ extern "C" { * The caller must (de)allocate the buffer in the pid.tid pointer. * @param[in] level The cpu boosting level * @param[in] flags The cpu boosting flag bits - * If CPU_BOOSTING_RESET_ON_FORK is set, child processes or threads created by fork() or pthread_create() + * If #CPU_BOOSTING_RESET_ON_FORK is set, child processes or threads created by fork() or pthread_create() * do not inherit boosted CPU schedulder and priority from the parent. * @param[in] timeout_msec The timeout in milliseconds, -1 to apply boosting permanently * * @return 0 on success, otherwise a negative error value. + * @retval #RESOURCE_ERROR_NONE Successful + * @retval #RESOURCE_ERROR_PERMISSION_DENIED Permission Denied + * @retval #RESOURCE_ERROR_INVALID_PARAMETER Invalid Parameter */ int resource_set_cpu_boosting (resource_pid_t pid, cpu_boosting_level_e level, cpu_boosting_flag_e flags, int timeout_msec); /** - * @brief Clear cpu boosting for the boosted process (pid/tids). - * @since_tizen 6.5 + * @partner + * @brief Clears cpu boosting for the boosted process (pid/tids). * * @details The default non-boosting configuration (SCHED_OTHER and nice=0) is applied. + * @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. * @param[in] pid The target process pid/tids \n * If pid.pid is nonzero, pid.tid and pid.tid_count are ignored, \n * and cpu boosting is cleared for all the threads of pid.pid. \n @@ -71,13 +78,21 @@ int resource_set_cpu_boosting (resource_pid_t pid, cpu_boosting_level_e level, c * The caller must (de)allocate the buffer in the pid.tid pointer. * * @return 0 on success, otherwise a negative error value. + * @retval #RESOURCE_ERROR_NONE Successful + * @retval #RESOURCE_ERROR_PERMISSION_DENIED Permission Denied + * @retval #RESOURCE_ERROR_INVALID_PARAMETER Invalid Parameter */ int resource_clear_cpu_boosting (resource_pid_t pid); /** - * @brief Get the cpu boosting level for the target process (pid/tids). + * @partner + * @brief Gets the cpu boosting level for the target process (pid/tids). * @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. * @param[in] pid The target process pid/tids \n * If pid.pid is nonzero, pid.tid and pid.tid_count are ignored, \n * and all the threads of pid.pid are checked. \n @@ -85,49 +100,64 @@ int resource_clear_cpu_boosting (resource_pid_t pid); * If pid.pid is zero and pid.tid is NULL, the calling thread is checked. \n * The caller must (de)allocate the buffer in the pid.tid pointer. * @param[out] level The boosting level for the target process (pid/tids) \n - * level->tid_level will be allocated and filled with cpu_boosting_level_e for tids requested by the pid argument. \n + * level->tid_level will be allocated and filled with #cpu_boosting_level_e for tids requested by the pid argument. \n * The caller must deallocate the buffer in the level->tid_level pointer after using it. * * @return 0 on success, otherwise a negative error value. + * @retval #RESOURCE_ERROR_NONE Successful + * @retval #RESOURCE_ERROR_PERMISSION_DENIED Permission Denied + * @retval #RESOURCE_ERROR_INVALID_PARAMETER Invalid Parameter */ int resource_get_cpu_boosting_level (resource_pid_t pid, cpu_boosting_level_info_t *level); /** - * @brief Set cpu resource inheritance from the source tid to the destination process (pid/tids). + * @partner + * @brief Sets cpu resource inheritance from the source tid to the destination process (pid/tids). * @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. * @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 * * @return 0 on success, otherwise a negative error value. + * @retval #RESOURCE_ERROR_NONE Successful + * @retval #RESOURCE_ERROR_PERMISSION_DENIED Permission Denied + * @retval #RESOURCE_ERROR_INVALID_PARAMETER Invalid Parameter */ int resource_set_cpu_inheritance (pid_t source_tid, const char *dest_process, int timeout_msec); /** - * @brief Clear cpu resource inheritance from the source tid to the destination process (pid/tids). + * @partner + * @brief Clears cpu resource inheritance from the source tid to the destination process (pid/tids). * @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. * @param[in] source_tid The caller thread's tid * @param[in] dest_process The name of destination process * * @return 0 on success, otherwise a negative error value. + * @retval #RESOURCE_ERROR_NONE Successful + * @retval #RESOURCE_ERROR_PERMISSION_DENIED Permission Denied + * @retval #RESOURCE_ERROR_INVALID_PARAMETER Invalid Parameter */ int resource_clear_cpu_inheritance (pid_t source_tid, const char *dest_process); /** - * @brief Register a destination process (pid/tids) for cpu resource inheritance. + * @partner + * @brief Registers a destination process (pid/tids) for 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. * @param[in] dest_process The name of destination process * @param[in] pid The destination process pid/tids \n * If pid.pid is nonzero, pid.tid and pid.tid_count are ignored, \n @@ -137,19 +167,27 @@ int resource_clear_cpu_inheritance (pid_t source_tid, const char *dest_process); * The caller must (de)allocate the buffer in the pid.tid pointer. * * @return 0 on success, otherwise a negative error value. + * @retval #RESOURCE_ERROR_NONE Successful + * @retval #RESOURCE_ERROR_PERMISSION_DENIED Permission Denied + * @retval #RESOURCE_ERROR_INVALID_PARAMETER Invalid Parameter */ int resource_register_cpu_inheritance_destination (const char *dest_process, resource_pid_t pid); /** - * @brief Unregister a destination process for cpu resource inheritance. + * @partner + * @brief Unregisters a destination process for 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. * @param[in] dest_process The name of destination process * * @return 0 on success, otherwise a negative error value. + * @retval #RESOURCE_ERROR_NONE Successful + * @retval #RESOURCE_ERROR_PERMISSION_DENIED Permission Denied + * @retval #RESOURCE_ERROR_INVALID_PARAMETER Invalid Parameter */ int resource_unregister_cpu_inheritance_destination (const char *dest_process); @@ -158,4 +196,4 @@ int resource_unregister_cpu_inheritance_destination (const char *dest_process); } #endif -#endif // __TIZEN_SYSTEM_CPU_BOOSTING_H__ +#endif /* __TIZEN_SYSTEM_CPU_BOOSTING_H__ */ -- 2.34.1