From: Youngjae Cho Date: Mon, 18 Jul 2022 05:43:31 +0000 (+0900) Subject: power: elaborate description X-Git-Tag: accepted/tizen/unified/20220927.132359~2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=37e6821b51d294f2ee2e38fa0af4e4a448605afa;p=platform%2Fcore%2Fapi%2Fdevice.git power: elaborate description Change-Id: I485b6da54b51ba9e8e1bb79d8e56a88dfb324d02 Signed-off-by: Youngjae Cho --- diff --git a/include/power-internal.h b/include/power-internal.h index 817c1d4..ed85e41 100644 --- a/include/power-internal.h +++ b/include/power-internal.h @@ -77,63 +77,94 @@ struct device_change_state_info { }; /** - * Callback function that delivers information about a state transition. + * @brief Called when a device power state is changed + * @details If both change_state_wait_callback and change_state_callback have registered to the same power state, \n + * then the change_state_wait_callback will be invoked first and the change_state_callback will follow. + * @param[out] info Information about state change + * @param[out] user_data User data passed from the callback registration */ typedef void (*change_state_wait_callback) (const struct device_change_state_info *info, void *user_data); /** - * Add callback for states to be transitioned. The action caused by the transition, - * e.g., wake unlock for sleep or shutdown for reboot, would be defered until calling - * device_power_change_state_wait_done(). - * - * uint64_t state_bits: bitwise-ORing of interesting state. - * change_state_wait_callback cb: For every state transition to the state_bit, the cb will be invoked. - * void *user_data: user data for the callback. + * @brief Add a callback to observe power state change + * @details Register a callback for specific power state. \n + * The callback will be invoked when the deviced changes state to the designated power state. \n + * An actual action, such as triggering poweroff on changing state to POWER_STATE_POWEROFF or \n + * wake unlock on changing state to POWER_STATE_SLEEP, will be deferred to give a chance \n + * for the API caller to prepare for the action. + * @sinze_tizen 6.5 + * @param[in] state_bits Bitwise ORed power state + * @param[in] cb Callback function + * @param[in] user_data Data to be passed to the callback function + * @return 0 on success, + * otherwise a negative error value + * @retval #DEVICE_ERROR_NONE Successful + * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed */ int device_power_add_change_state_wait_callback(uint64_t state_bits, change_state_wait_callback cb, void *user_data); /** - * Notify the deviced that it is ready to transition state. - * - * uint64_t id: id of device_change_state_info that has received through callback. + * @brief Notify the deviced that it is ready for the actual action. + * @details Notify the deviced that it is ok to take an actual action of change state. \n + * This API only works on the id received from change_state_wait_callback. + * @since_tizen 6.5 + * @param[in] id Id of a state change + * @return 0 on success, + * otherwise a negative error value + * @retval #DEVICE_ERROR_NONE Successful + * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed */ int device_power_change_state_wait_done(uint64_t id); /** - * Remove callback of state transition. + * @brief Remove callback that has registered to power state. + * @since_tizen 6.5 + * @param[in] state_bits Bitwise ORed power state */ void device_power_remove_change_state_wait_callback(uint64_t state_bits); /** - * Async callback of device_power_change_state() - * - * uint64_t state: which state it has transitioned. - * int retval: result of the method call. - * void *user_data: user data for the callback. + * @brief Async callback of device_power_change_state(). + * @details If both change_state_wait_callback and change_state_callback have registered to the same power state, \n + * then the change_state_wait_callback will be invoked first and the change_state_callback will follow. + * @since_tizen 6.5 + * @param[out] state State to be changed + * @param[out] retval Return of change state + * @param[out] user_data The user data passed from the change state function */ typedef void (*change_state_callback) (uint64_t state, int retval, void *user_data); /** - * Send a request to the deviced for changing power state. It doesn't ensure the whole execution - * of a callback subroutine - think of a request for sleep/poweroff/reboot state. To ensure - * the whole execution of a callback, use device_power_add_change_state_wait_callback() additionally. - * If both change_state_wait_callback and change_state_callback has registered to a state, - * it is unpredictable which callback will be invoked first. - * - * uint64_t state: which state to transition to - * int timeout_sec: maximum timeout of async method call. if it expires, then the second parameter of - * a callback function, int retval, gives -ETIMEDOUT error. If it is 0 or negative, it is set to - * the default, 10 seconds. - * change_state_callback cb: async callback function, nullable - * void *user_data: user data for the callback. + * @brief Send request for changing power state asynchronously. + * @since_tizen 6.5 + * @param[in] state Target state + * @param[in] timeout_sec Timeout for the async reply in second, maximum of 10 seconds + * @param[in] cb Async callback of the request + * @param[in] user_data Data to be passed to the callback function + * @return 0 on success, + * otherwise a negative error value + * @retval #DEVICE_ERROR_NONE Successful + * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed */ int device_power_change_state(uint64_t state, int timeout_sec, change_state_callback cb, void *user_data); /** - * Return 0 if cloning partition is in progress. + * @brief Check if reboot is possible on the current device state + * @since_tizen 6.5 + * @return 1 if a device is able to reboot, + * otherwise return 0 */ int device_power_check_reboot_allowed(void); +/** + * @brief Get internal power state of the deviced + * @since_tizen 6.5 + * @param[out] state Internal power state of the deviced + * @return 0 on success, + * otherwise a negative error value + * @retval #DEVICE_ERROR_NONE Successful + * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed + */ int device_power_get_state(uint64_t *state); #ifdef __cplusplus