From: Youngjae Cho <y0.cho@samsung.com>
Date: Thu, 19 May 2022 02:22:02 +0000 (+0900)
Subject: power-internal: add new state POWER_STATE_EXIT
X-Git-Tag: accepted/tizen/unified/20220601.141615~2
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=71129f43d8359c0084cc165bfb63271becbaa805;p=platform%2Fcore%2Fapi%2Fdevice.git

power-internal: add new state POWER_STATE_EXIT

Change-Id: Idbc9ea3c9608f27651fa39dc6f252c1091a8ad06
Signed-off-by: Youngjae Cho <y0.cho@samsung.com>
---

diff --git a/include/power-internal.h b/include/power-internal.h
index febf2fc..8d06164 100644
--- a/include/power-internal.h
+++ b/include/power-internal.h
@@ -50,6 +50,7 @@ enum {
 	POWER_STATE_SLEEP_INDEX,
 	POWER_STATE_POWEROFF_INDEX,
 	POWER_STATE_REBOOT_INDEX,
+	POWER_STATE_EXIT_INDEX,
 	POWER_STATE_MAX_INDEX,
 };
 
@@ -58,6 +59,7 @@ enum {
 #define	POWER_STATE_SLEEP    (1ULL << POWER_STATE_SLEEP_INDEX)
 #define	POWER_STATE_POWEROFF (1ULL << POWER_STATE_POWEROFF_INDEX)
 #define	POWER_STATE_REBOOT   (1ULL << POWER_STATE_REBOOT_INDEX)
+#define	POWER_STATE_EXIT     (1ULL << POWER_STATE_EXIT_INDEX)
 #define	POWER_STATE_ALL      ((1ULL << POWER_STATE_MAX_INDEX) - (1ULL << POWER_STATE_MIN_INDEX))
 
 #define SIGNAME_CHANGE_STATE_TO_START         "ChangeStateToStart"
@@ -65,18 +67,39 @@ enum {
 #define SIGNAME_CHANGE_STATE_TO_SLEEP         "ChangeStateToSleep"
 #define SIGNAME_CHANGE_STATE_TO_POWEROFF      "ChangeStateToPowerOff"
 #define SIGNAME_CHANGE_STATE_TO_REBOOT        "ChangeStateToReboot"
+#define SIGNAME_CHANGE_STATE_TO_EXIT          "ChangeStateToExit"
 
 struct device_change_state_info {
-	uint64_t prev_state;
-	uint64_t next_state;
-	uint64_t id;
-	int reason;
+	uint64_t prev_state; /* previous state before the state transition, one of POWER_STATE_* */
+	uint64_t next_state; /* current state that has been transitioned, one of POWER_STATE_* */
+	uint64_t id;         /* unique id for each transition. it is used for wait-done */
+	int reason;          /* integer that signifies what event has triggered the transition */
 };
 
+/**
+ * Callback function that delivers information about a state transition.
+ */
 typedef void (*change_state_callback) (const struct device_change_state_info *info, void *user_data);
 
+/**
+ * Add callback for states to be transitioned.
+ *
+ * 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.
+ */
 int device_power_add_change_state_wait_callback(uint64_t state_bits, change_state_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.
+ */
 int device_power_change_state_wait_done(uint64_t id);
+
+/**
+ * Remove callback of state transition.
+ */
 void device_power_remove_change_state_wait_callback(uint64_t state_bits);
 
 #ifdef __cplusplus
diff --git a/src/power-internal.c b/src/power-internal.c
index 04a6d27..f913325 100644
--- a/src/power-internal.c
+++ b/src/power-internal.c
@@ -20,6 +20,7 @@ static const char *signame[POWER_STATE_MAX_INDEX] = {
 	[POWER_STATE_SLEEP_INDEX] = SIGNAME_CHANGE_STATE_TO_SLEEP,
 	[POWER_STATE_POWEROFF_INDEX] = SIGNAME_CHANGE_STATE_TO_POWEROFF,
 	[POWER_STATE_REBOOT_INDEX] = SIGNAME_CHANGE_STATE_TO_REBOOT,
+	[POWER_STATE_EXIT_INDEX] = SIGNAME_CHANGE_STATE_TO_EXIT,
 };
 
 static void signal_unsubscribed_callback(void *data)