power: rename APIs and removing leading _

Remove leading underscore from PM APIs. _ was used for internal APIs.

Signed-off-by: Anas Nashif <[email protected]>

Author: nashif

arch/arc/core/reset.S

@@ -90,7 +90,7 @@ done_cache_invalidate:
 
 #if defined(CONFIG_SYS_POWER_DEEP_SLEEP) && \
 	!defined(CONFIG_BOOTLOADER_CONTEXT_RESTORE)
-        jl @_sys_soc_resume_from_deep_sleep
+        jl @sys_soc_resume_from_deep_sleep
 #endif
 
 #ifdef CONFIG_INIT_STACKS

arch/x86/core/crt0.S

@@ -39,7 +39,7 @@
 #endif
 
 #ifdef CONFIG_SYS_POWER_DEEP_SLEEP
-	GTEXT(_sys_soc_resume_from_deep_sleep)
+	GTEXT(sys_soc_resume_from_deep_sleep)
 #endif
 
 #ifdef CONFIG_REALMODE
@@ -255,13 +255,13 @@ __csSet:
 	 * the ISR stack size are some multiple of STACK_ALIGN, which
 	 * is at least 4.
 	 *
-	 * This is also used to call the _sys_soc_resume_from_deep_sleep()
+	 * This is also used to call the sys_soc_resume_from_deep_sleep()
 	 * routine to avoid memory corruption if the system is resuming from
-	 * deep sleep. It is important that _sys_soc_resume_from_deep_sleep()
+	 * deep sleep. It is important that sys_soc_resume_from_deep_sleep()
 	 * restores the stack pointer to what it was at deep sleep before
          * enabling interrupts.  This is necessary to avoid
 	 * interfering with interrupt handler use of this stack.
-	 * If it is a cold boot then _sys_soc_resume_from_deep_sleep() should
+	 * If it is a cold boot then sys_soc_resume_from_deep_sleep() should
 	 * not do anything and must return immediately.
 	 */
 #ifdef CONFIG_INIT_STACKS
@@ -287,7 +287,7 @@ __csSet:
 #if defined(CONFIG_SYS_POWER_DEEP_SLEEP) && \
              !defined(CONFIG_BOOTLOADER_CONTEXT_RESTORE)
 	/*
-	 * Invoke _sys_soc_resume_from_deep_sleep() hook to handle resume from
+	 * Invoke sys_soc_resume_from_deep_sleep() hook to handle resume from
 	 * deep sleep. It should first check whether system is recovering from
 	 * deep sleep state. If it is, then this function should restore
 	 * states and resume at the point system went to deep sleep.
@@ -298,7 +298,7 @@ __csSet:
 	 * return and execution falls through to cold boot path.
 	 */
 
-	call _sys_soc_resume_from_deep_sleep
+	call sys_soc_resume_from_deep_sleep
 
 #endif
 

doc/subsystems/power_management.rst

@@ -103,10 +103,10 @@ Suspend Hook function
 
 .. code-block:: c
 
-   int _sys_soc_suspend(s32_t ticks);
+   int sys_soc_suspend(s32_t ticks);
 
 When the kernel is about to go idle, the power management subsystem calls the
-:code:`_sys_soc_suspend()` function, notifying the SOC interface that the kernel
+:code:`sys_soc_suspend()` function, notifying the SOC interface that the kernel
 is ready to enter the idle state.
 
 At this point, the kernel has disabled interrupts and computed the maximum
@@ -116,7 +116,7 @@ can be done in the available time. The power management operation must halt
 execution on a CPU or SOC low power state. Before entering the low power state,
 the SOC interface must setup a wake event.
 
-The power management subsystem expects the :code:`_sys_soc_suspend()` to
+The power management subsystem expects the :code:`sys_soc_suspend()` to
 return one of the following values based on the power management operations
 the SOC interface executed:
 
@@ -137,22 +137,22 @@ Resume Hook function
 
 .. code-block:: c
 
-   void _sys_soc_resume(void);
+   void sys_soc_resume(void);
 
 The power management subsystem optionally calls this hook function when exiting
 kernel idling if power management operations were performed in
-:code:`_sys_soc_suspend()`. Any necessary recovery operations can be performed
+:code:`sys_soc_suspend()`. Any necessary recovery operations can be performed
 in this function before the kernel scheduler schedules another thread. Some
 power states may not need this notification. It can be disabled by calling
-:code:`_sys_soc_pm_idle_exit_notification_disable()` from
-:code:`_sys_soc_suspend()`.
+:code:`sys_soc_pm_idle_exit_notification_disable()` from
+:code:`sys_soc_suspend()`.
 
 Resume From Deep Sleep Hook function
 ====================================
 
 .. code-block:: c
 
-   void _sys_soc_resume_from_deep_sleep(void);
+   void sys_soc_resume_from_deep_sleep(void);
 
 This function is optionally called when exiting from deep sleep if the SOC
 interface does not have bootloader support to handle resume from deep sleep.
@@ -231,7 +231,7 @@ in power saving mode. This method allows saving power even when the CPU is
 active. The components that use the devices need to be power aware and should
 be able to make decisions related to managing device power. In this method, the
 SOC interface can enter CPU or SOC low power states quickly when
-:code:`_sys_soc_suspend()` gets called. This is because it does not need to
+:code:`sys_soc_suspend()` gets called. This is because it does not need to
 spend time doing device power management if the devices are already put in
 the appropriate low power state by the application or component managing the
 devices.
@@ -240,7 +240,7 @@ Central method
 ==============
 
 In this method device power management is mostly done inside
-:code:`_sys_soc_suspend()` along with entering a CPU or SOC low power state.
+:code:`sys_soc_suspend()` along with entering a CPU or SOC low power state.
 
 If a decision to enter deep sleep is made, the implementation would enter it
 only after checking if the devices are not in the middle of a hardware
@@ -380,21 +380,21 @@ off, then such transactions would be left in an inconsistent state. This
 infrastructure guards such transactions by indicating to the SOC interface that
 the device is in the middle of a hardware transaction.
 
-When the :code:`_sys_soc_suspend()` is called, the SOC interface checks if any device
+When the :code:`sys_soc_suspend()` is called, the SOC interface checks if any device
 is busy. The SOC interface can then decide to execute a power management scheme other than deep sleep or
 to defer power management operations until the next call of
-:code:`_sys_soc_suspend()`.
+:code:`sys_soc_suspend()`.
 
 An alternative to using the busy status mechanism is to use the
 `distributed method`_ of device power management. In such a method where the
 device power management is handled in a distributed manner rather than centrally in
-:code:`_sys_soc_suspend()`, the decision to enter deep sleep can be made based
+:code:`sys_soc_suspend()`, the decision to enter deep sleep can be made based
 on whether all devices are already turned off.
 
 This feature can be also used to emulate a hardware feature found in some SOCs
 that causes the system to automatically enter deep sleep when all devices are idle.
 In such an usage, the busy status can be set by default and cleared as each
-device becomes idle. When :code:`_sys_soc_suspend()` is called, deep sleep can
+device becomes idle. When :code:`sys_soc_suspend()` is called, deep sleep can
 be entered if no device is found to be busy.
 
 Here are the APIs used to set, clear, and check the busy status of devices.

drivers/i2c/i2c_dw.c

@@ -433,7 +433,7 @@ static int i2c_dw_transfer(struct device *dev,
 
 	/*
 	 * While waiting at device_sync_sem, kernel can switch to idle
-	 * task which in turn can call _sys_soc_suspend() hook of Power
+	 * task which in turn can call sys_soc_suspend() hook of Power
 	 * Management App (PMA).
 	 * device_busy_set() call here, would indicate to PMA that it should not
 	 * execute PM policies that would turn off this ip block, causing an

include/power.h

@@ -20,7 +20,7 @@ extern "C" {
 
 #define SYS_PM_NOT_HANDLED		SYS_PM_ACTIVE_STATE
 
-extern unsigned char _sys_pm_idle_exit_notify;
+extern unsigned char sys_pm_idle_exit_notify;
 
 
 /**
@@ -40,15 +40,15 @@ extern unsigned char _sys_pm_idle_exit_notify;
 /**
  * @brief Function to disable power management idle exit notification
  *
- * _sys_soc_resume() would be called from the ISR of the event that caused
+ * sys_soc_resume() would be called from the ISR of the event that caused
  * exit from kernel idling after PM operations. For some power operations,
  * this notification may not be necessary. This function can be called in
- * _sys_soc_suspend to disable the corresponding _sys_soc_resume notification.
+ * sys_soc_suspend to disable the corresponding sys_soc_resume notification.
  *
  */
-static inline void _sys_soc_pm_idle_exit_notification_disable(void)
+static inline void sys_soc_pm_idle_exit_notification_disable(void)
 {
-	_sys_pm_idle_exit_notify = 0;
+	sys_pm_idle_exit_notify = 0;
 }
 
 /**
@@ -66,13 +66,13 @@ static inline void _sys_soc_pm_idle_exit_notification_disable(void)
  * function should return immediately.
  *
  */
-void _sys_soc_resume_from_deep_sleep(void);
+void sys_soc_resume_from_deep_sleep(void);
 
 /**
  * @brief Hook function to notify exit from kernel idling after PM operations
  *
  * This function would notify exit from kernel idling if a corresponding
- * _sys_soc_suspend() notification was handled and did not return
+ * sys_soc_suspend() notification was handled and did not return
  * SYS_PM_NOT_HANDLED.
  *
  * This function would be called from the ISR context of the event
@@ -84,11 +84,11 @@ void _sys_soc_resume_from_deep_sleep(void);
  * those cases, the ISR would be invoked immediately after the event wakes up
  * the CPU, before code following the CPU wait, gets a chance to execute. This
  * can be ignored if no operation needs to be done at the wake event
- * notification. Alternatively _sys_soc_pm_idle_exit_notification_disable() can
- * be called in _sys_soc_suspend to disable this notification.
+ * notification. Alternatively sys_soc_pm_idle_exit_notification_disable() can
+ * be called in sys_soc_suspend to disable this notification.
  *
  */
-void _sys_soc_resume(void);
+void sys_soc_resume(void);
 
 /**
  * @brief Hook function to allow entry to low power state
@@ -116,7 +116,7 @@ void _sys_soc_resume(void);
  * @retval SYS_PM_LOW_POWER_STATE If CPU low power state was entered.
  * @retval SYS_PM_DEEP_SLEEP If SOC low power state was entered.
  */
-extern int _sys_soc_suspend(s32_t ticks);
+extern int sys_soc_suspend(s32_t ticks);
 
 #ifdef CONFIG_PM_CONTROL_OS_DEBUG
 /**

kernel/idle.c

@@ -21,19 +21,19 @@
 
 #ifdef CONFIG_SYS_POWER_MANAGEMENT
 /*
- * Used to allow _sys_soc_suspend() implementation to control notification
+ * Used to allow sys_soc_suspend() implementation to control notification
  * of the event that caused exit from kernel idling after pm operations.
  */
-unsigned char _sys_pm_idle_exit_notify;
+unsigned char sys_pm_idle_exit_notify;
 
 #if defined(CONFIG_SYS_POWER_LOW_POWER_STATE)
-void __attribute__((weak)) _sys_soc_resume(void)
+void __attribute__((weak)) sys_soc_resume(void)
 {
 }
 #endif
 
 #if defined(CONFIG_SYS_POWER_DEEP_SLEEP)
-void __attribute__((weak)) _sys_soc_resume_from_deep_sleep(void)
+void __attribute__((weak)) sys_soc_resume_from_deep_sleep(void)
 {
 }
 #endif
@@ -77,7 +77,7 @@ static void sys_power_save_idle(void)
 #if (defined(CONFIG_SYS_POWER_LOW_POWER_STATE) || \
 	defined(CONFIG_SYS_POWER_DEEP_SLEEP))
 
-	_sys_pm_idle_exit_notify = 1U;
+	sys_pm_idle_exit_notify = 1U;
 
 	/*
 	 * Call the suspend hook function of the soc interface to allow
@@ -92,8 +92,8 @@ static void sys_power_save_idle(void)
 	 * idle processing re-enables interrupts which is essential for
 	 * the kernel's scheduling logic.
 	 */
-	if (_sys_soc_suspend(ticks) == SYS_PM_NOT_HANDLED) {
-		_sys_pm_idle_exit_notify = 0U;
+	if (sys_soc_suspend(ticks) == SYS_PM_NOT_HANDLED) {
+		sys_pm_idle_exit_notify = 0U;
 		k_cpu_idle();
 	}
 #else
@@ -108,11 +108,11 @@ void _sys_power_save_idle_exit(s32_t ticks)
 	/* Some CPU low power states require notification at the ISR
 	 * to allow any operations that needs to be done before kernel
 	 * switches task or processes nested interrupts. This can be
-	 * disabled by calling _sys_soc_pm_idle_exit_notification_disable().
+	 * disabled by calling sys_soc_pm_idle_exit_notification_disable().
 	 * Alternatively it can be simply ignored if not required.
 	 */
-	if (_sys_pm_idle_exit_notify) {
-		_sys_soc_resume();
+	if (sys_pm_idle_exit_notify) {
+		sys_soc_resume();
 	}
 #endif
 

samples/boards/nrf52/power_mgr/README.rst

@@ -10,7 +10,7 @@ This sample demonstrates a power manager app that uses the Zephyr
 power management infrastructure to enter into Low Power state.
 
 This app will cycle through the following power schemes each time idle thread
-calls _sys_soc_suspend() hook function :
+calls sys_soc_suspend() hook function :
 
 1. Low Power State: Low Power State is SOC specific and being in this state is
    transparent to devices. SOC and devices do not lose context in this Mode.

samples/boards/nrf52/power_mgr/src/power.c

@@ -68,7 +68,7 @@ static int low_power_state_entry(void)
 	} else {
 		printk("--> Entering into Low Power State -");
 	}
-	_sys_soc_set_power_state(pm_state);
+	sys_soc_set_power_state(pm_state);
 	return SYS_PM_LOW_POWER_STATE;
 }
 
@@ -83,24 +83,24 @@ static int low_power_suspend_entry(void)
 {
 	printk("--> Entering into Deep Sleep State -");
 	/* Don't need pm idle exit event notification */
-	_sys_soc_pm_idle_exit_notification_disable();
+	sys_soc_pm_idle_exit_notification_disable();
 	/* Save device states and turn off peripherals as necessary */
 	suspend_devices();
-	_sys_soc_set_power_state(SYS_POWER_STATE_DEEP_SLEEP);
+	sys_soc_set_power_state(SYS_POWER_STATE_DEEP_SLEEP);
 	 /* Exiting from Deep Sleep State */
 	low_power_suspend_exit();
 
 	return SYS_PM_DEEP_SLEEP;
 }
 
-/* Function name : _sys_soc_suspend
+/* Function name : sys_soc_suspend
  * Return Value : Power Mode Entered Success/Failure
  * Input : Idleness in number of Ticks
  *
  * Description: All request from Idle thread to Enter into
  * Low Power Mode or Deep Sleep State land in this function
  */
-int _sys_soc_suspend(s32_t ticks)
+int sys_soc_suspend(s32_t ticks)
 {
 	int ret = SYS_PM_NOT_HANDLED;
 
@@ -142,14 +142,14 @@ int _sys_soc_suspend(s32_t ticks)
 				low_power_state_exit();
 			}
 			post_ops_done = 1;
-			_sys_soc_power_state_post_ops(pm_state);
+			sys_soc_power_state_post_ops(pm_state);
 		}
 	}
 
 	return ret;
 }
 
-void _sys_soc_resume(void)
+void sys_soc_resume(void)
 {
 	/*
 	 * This notification is called from the ISR of the event
@@ -163,14 +163,14 @@ void _sys_soc_resume(void)
 	 * The kernel scheduler will get control after the ISR finishes
 	 * and it may schedule another thread.
 	 *
-	 * Call _sys_soc_pm_idle_exit_notification_disable() if this
+	 * Call sys_soc_pm_idle_exit_notification_disable() if this
 	 * notification is not required.
 	 */
 	if (!post_ops_done) {
 		if (pm_state == SYS_POWER_STATE_CPU_LPS) {
 			low_power_state_exit();
 		}
 		post_ops_done = 1;
-		_sys_soc_power_state_post_ops(pm_state);
+		sys_soc_power_state_post_ops(pm_state);
 	}
 }

samples/boards/quark_se_c1000/power_mgr/README.rst

@@ -10,7 +10,7 @@ A sample implementation of a power manager app that uses the Zephyr
 power management infrastructure.
 
 This app will cycle through the various power schemes at every call
-to _sys_soc_suspend() hook function.
+to sys_soc_suspend() hook function.
 It will cycle through the following states:
 
 1. CPU Low Power State