Last Updated: August 24, 2011
+Last Updated: September 4, 2011
-
-
-
-
/dev/null, /dev/zero, and loop drivers.
- -
+
+
+
/dev/null, /dev/zero, and loop drivers.
+ +
+
Last Updated: August 25, 2011
+Last Updated: September 4, 2011
+ NuttX supports a simple power managment (PM) sub-system. This sub-system: +
++ Monitors driver activity, and +
++ Provides hooks to place drivers (and the whole system) into reduce power + modes of operation. +
++ The PM sub-system integrates the MCU idle loop with a collection of device drivers to support: +
++ Reports of relevant driver or other system activity. +
++ Registration and callback mechanism to interface with individual device drivers. +
++ IDLE time polling of overall driver activity. +
++ Coordinated, global, system-wide transitions to lower power usage states. +
++ Various "sleep" and low power consumption states have various names and are sometimes used in conflicting ways. + In the NuttX PM logic, we will use the following terminology: +
+NORMAL
+ IDLE
+ IDLE and some simple simple steps to reduce power
+ consumption provided that they do not interfere with normal
+ Operation. Simply dimming the a backlight might be an example
+ somethat that would be done when the system is idle.
+ STANDBY
+ SLEEP
+ SLEEP (some MCUs may even require going through reset).
+
+ These various states are represented with type enum pm_state_e in include/nuttx/pm.h.
+
+ All PM interfaces are declared in the file include/nuttx/pm.h.
+
Function Prototype:
++#include <nuttx/pm.h> +void pm_initialize(void); ++
Description: +This function is called by MCU-specific one-time at power on reset in order to initialize the power management capabilities. +This function must be called very early in the intialization sequence before any other device drivers are initialize (since they may attempt to register with the power management subsystem). +
+Input Parameters: +None +
+Returned Value: +None +
+ +Function Prototype:
++#include <nuttx/pm.h> +int pm_register(FAR struct pm_callback_s *callbacks); ++
Description: + This function is called by a device driver in order to register to receive power management event callbacks. + Refer to the PM Callback section for more details. +
+Input Parameters: +
callbacks
+ struct pm_callback_s providing the driver callback functions.
+ Returned Value:
+Zero (OK) on success; otherwise a negater errno value is returned.
+
Function Prototype:
++#include <nuttx/pm.h> +void pm_activity(int priority); ++
Description: + This function is called by a device driver to indicate that it is performing meaningful activities (non-idle). + This increment an activty count and/or will restart a idle timer and prevent entering reduced power states. +
+Input Parameters: +
priority
+ Returned Value: + None +
+Assumptions: + This function may be called from an interrupt handler (this is the ONLY PM function that may be called from an interrupt handler!). +
+ +Function Prototype:
++#include <nuttx/pm.h> +enum pm_state_e pm_checkstate(void); ++
Description:
+ This function is called from the MCU-specific IDLE loop to monitor the the power management conditions.
+ This function returns the "recommended" power management state based on the PM configuration and activity reported in the last sampling periods.
+ The power management state is not automatically changed, however.
+ The IDLE loop must call pm_changestate() in order to make the state change.
+
+ These two steps are separated because the plaform-specific IDLE loop may have additional situational information that is not available to the the PM sub-system. + For example, the IDLE loop may know that the battery charge level is very low and may force lower power states even if there is activity. +
+
+ NOTE: That these two steps are separated in time and, hence, the IDLE loop could be suspended for a long period of time between calling pm_checkstate() and pm_changestate().
+ The IDLE loop may need to make these calls atomic by either disabling interrupts until the state change is completed.
+
Input Parameters: + None +
+Returned Value: + The recommended power management state. +
+ +Function Prototype:
++#include <nuttx/pm.h> + int pm_changestate(enum pm_state_e newstate); ++
Description: + This function is used by platform-specific power management logic. + It will announce the power management power management state change to all drivers that have registered for power management event callbacks. +
+Input Parameters: +
newstate
+ Returned Value:
+ 0 (OK) means that the callback function for all registered drivers returned OK (meaning that they accept the state change).
+ Non-zero means that one of the drivers refused the state change.
+ In this case, the system will revert to the preceding state.
+
Assumptions: + It is assumed that interrupts are disabled when this function is called. + This function is probably called from the IDLE loop... the lowest priority task in the system. + Changing driver power management states may result in renewed system activity and, as a result, can + suspend the IDLE thread before it completes the entire state change unless interrupts are disabled throughout the state change. +
+ +
+ The struct pm_callback_s includes the pointers to the driver callback functions.
+ This structure is defined include/nuttx/pm.h.
+ These callback functions can be used to provide power management information to the driver.
+
Function Prototype:
++int (*prepare)(FAR struct pm_callback_s *cb, enum pm_state_e pmstate); ++
Description: + Request the driver to prepare for a new power state. + This is a warning that the system is about to enter into a new power state. + The driver should begin whatever operations that may be required to enter power state. + The driver may abort the state change mode by returning a non-zero value from the callback function. +
+Input Parameters: +
cb
+ pmstate
+ Returned Value:
+ Zero (OK) means the event was successfully processed and that the driver is prepared for the PM state change.
+ Non-zero means that the driver is not prepared to perform the tasks needed achieve this power setting and will cause the state change to be aborted.
+ NOTE: The prepare() method will also be called when reverting from lower back to higher power consumption modes (say because another driver refused a lower power state change).
+ Drivers are not permitted to return non-zero values when reverting back to higher power
+ consumption modes!
+
Function Prototype:
++#include <nuttx/pm.h> +void (*notify)(FAR struct pm_callback_s *cb, enum pm_state_e pmstate); ++
Description: + Notify the driver of new power state. + This callback is called after all drivers have had the opportunity to prepare for the new power state. +
+Input Parameters: +
cb
+ pmstate
+ Returned Value:
+ None.
+ The driver already agreed to transition to the low power consumption state when when it returned OK to the prepare() call.
+
| diff --git a/drivers/README.txt b/drivers/README.txt index 3c337956f9a..e5a1483b220 100644 --- a/drivers/README.txt +++ b/drivers/README.txt @@ -81,6 +81,12 @@ pipes/ FIFO and named pipe drivers. Standard interfaces are declared in include/unistd.h +pm/ + Power management (PM) driver interfaces. These interfaces are used + to manage power usage of a platform by monitoring driver activity + and by placing drivers into reduce power usage modes when the + drivers are not active. + sensors/ Drivers for various sensors diff --git a/drivers/pm/pm_activity.c b/drivers/pm/pm_activity.c index f1518520b0f..a0bae76fa4e 100644 --- a/drivers/pm/pm_activity.c +++ b/drivers/pm/pm_activity.c @@ -81,13 +81,13 @@ * Description: * This function is called by a device driver to indicate that it is * performing meaningful activities (non-idle). This increment an activty - * cound and/or will restart a idle timer and prevent entering IDLE + * count and/or will restart a idle timer and prevent entering reduced * power states. * * Input Parameters: - * priority - activity priority, range 0-9. Larger values correspond to + * priority - Activity priority, range 0-9. Larger values correspond to * higher priorities. Higher priority activity can prevent the system - * fromentering reduced power states for a longer period of time. + * from entering reduced power states for a longer period of time. * * As an example, a button press might be higher priority activity because * it means that the user is actively interacting with the device. diff --git a/drivers/pm/pm_changestate.c b/drivers/pm/pm_changestate.c index e98e46236a1..50fa0640ff9 100644 --- a/drivers/pm/pm_changestate.c +++ b/drivers/pm/pm_changestate.c @@ -77,7 +77,7 @@ * Prepare every driver for the state change. * * Input Parameters: - * newstate - Idenfifies the new PM state + * newstate - Identifies the new PM state * * Returned Value: * 0 (OK) means that the callback function for all registered drivers @@ -122,7 +122,7 @@ static int pm_prepall(enum pm_state_e newstate) * Inform all drivers of the state change. * * Input Parameters: - * newstate - Idenfifies the new PM state + * newstate - Identifies the new PM state * * Returned Value: * None @@ -147,7 +147,7 @@ static inline void pm_changeall(enum pm_state_e newstate) { /* Yes.. notify the driver */ - (void)cb->notify(cb, newstate); + cb->notify(cb, newstate); } } } @@ -160,12 +160,12 @@ static inline void pm_changeall(enum pm_state_e newstate) * Name: pm_changestate * * Description: - * This function is used to platform-specific power managmeent logic. It + * This function is used by platform-specific power management logic. It * will announce the power management power management state change to all * drivers that have registered for power management event callbacks. * * Input Parameters: - * newstate - Idenfifies the new PM state + * newstate - Identifies the new PM state * * Returned Value: * 0 (OK) means that the callback function for all registered drivers diff --git a/drivers/pm/pm_checkstate.c b/drivers/pm/pm_checkstate.c index 6b23ad05c0b..3a7f13d47f5 100644 --- a/drivers/pm/pm_checkstate.c +++ b/drivers/pm/pm_checkstate.c @@ -93,10 +93,10 @@ * even if there is activity. * * NOTE: That these two steps are separated in time and, hence, the IDLE - * could be suspended for a long period of time between calling - * pm_checkstate() and pm_changestate(). There it is recommended that - * the IDLE loop make these calls atomic by either disabling interrupts - * until the state change is completed. + * loop could be suspended for a long period of time between calling + * pm_checkstate() and pm_changestate(). The IDLE loop may need to make + * these calls atomic by either disabling interrupts until the state change + * is completed. * * Input Parameters: * None diff --git a/include/nuttx/pm.h b/include/nuttx/pm.h index 36daadcbcb7..f5375fc6a2a 100644 --- a/include/nuttx/pm.h +++ b/include/nuttx/pm.h @@ -234,7 +234,7 @@ struct pm_callback_s * Name: prepare * * Description: - * Notify the driver to prepare for a new power confition .This is a + * Request the driver to prepare for a new power state. This is a * warning that the system is about to enter into a new power state. The * driver should begin whatever operations that may be required to enter * power state. The driver may abort the state change mode by returning @@ -244,12 +244,17 @@ struct pm_callback_s * cb - Returned to the driver. The driver version of the callback * strucure may include additional, driver-specific state * data at the end of the structure. - * pmstate - Idenfifies the new PM state + * pmstate - Identifies the new PM state * * Returned Value: - * 0 (OK) means the event was successfully processed. Non-zero means - * means that the driver is not prepared to perform the tasks needed - * achieve this power setting. + * 0 (OK) means the event was successfully processed and that the driver + * is prepared for the PM state change. Non-zero means that the driver + * is not prepared to perform the tasks needed achieve this power setting + * and will cause the state change to be aborted. NOTE: The prepare + * method will also be recalled when reverting from lower back to higher + * power consumption modes (say because another driver refused a lower + * power state change). Drivers are not permitted to return non-zero + * values when reverting back to higher power consumption modes! * **************************************************************************/ @@ -267,13 +272,11 @@ struct pm_callback_s * cb - Returned to the driver. The driver version of the callback * strucure may include additional, driver-specific state * data at the end of the structure. - * pmstate - Idenfifies the new PM state + * pmstate - Identifies the new PM state * * Returned Value: - * 0 (OK) means the event was successfully processed. Non-zero means - * means that the driver failed to enter the lower power consumption - * mode. Drivers are not permitted to return non-zero values when - * reverting to higher power consumption modes! + * None. The driver already agreed to transition to the low power + * consumption state when when it returned OK to the prepare() call. * **************************************************************************/ @@ -340,13 +343,13 @@ EXTERN int pm_register(FAR struct pm_callback_s *callbacks); * Description: * This function is called by a device driver to indicate that it is * performing meaningful activities (non-idle). This increment an activty - * cound and/or will restart a idle timer and prevent entering IDLE + * count and/or will restart a idle timer and prevent entering reduced * power states. * * Input Parameters: - * priority - activity priority, range 0-9. Larger values correspond to + * priority - Activity priority, range 0-9. Larger values correspond to * higher priorities. Higher priority activity can prevent the system - * fromentering reduced power states for a longer period of time. + * from entering reduced power states for a longer period of time. * * As an example, a button press might be higher priority activity because * it means that the user is actively interacting with the device. @@ -380,10 +383,10 @@ EXTERN void pm_activity(int priority); * even if there is activity. * * NOTE: That these two steps are separated in time and, hence, the IDLE - * could be suspended for a long period of time between calling - * pm_checkstate() and pm_changestate(). There it is recommended that - * the IDLE loop make these calls atomic by either disabling interrupts - * until the state change is completed. + * loop could be suspended for a long period of time between calling + * pm_checkstate() and pm_changestate(). The IDLE loop may need to make + * these calls atomic by either disabling interrupts until the state change + * is completed. * * Input Parameters: * None @@ -404,7 +407,7 @@ EXTERN enum pm_state_e pm_checkstate(void); * drivers that have registered for power management event callbacks. * * Input Parameters: - * newstate - Idenfifies the new PM state + * newstate - Identifies the new PM state * * Returned Value: * 0 (OK) means that the callback function for all registered drivers |