From cc34367c9f9c0807f69cc1a987d25be19fd83c23 Mon Sep 17 00:00:00 2001 From: patacongo Date: Sun, 4 Sep 2011 22:16:10 +0000 Subject: Update PM documentation git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@3937 42af7a65-404d-4744-a932-0658087f49c3 --- nuttx/Documentation/NuttX.html | 104 ++++++++--- nuttx/Documentation/NuttxPortingGuide.html | 266 ++++++++++++++++++++++++++++- nuttx/drivers/README.txt | 6 + nuttx/drivers/pm/pm_activity.c | 6 +- nuttx/drivers/pm/pm_changestate.c | 10 +- nuttx/drivers/pm/pm_checkstate.c | 8 +- nuttx/include/nuttx/pm.h | 39 +++-- 7 files changed, 381 insertions(+), 58 deletions(-) diff --git a/nuttx/Documentation/NuttX.html b/nuttx/Documentation/NuttX.html index 4e603e0d0..c93b87034 100644 --- a/nuttx/Documentation/NuttX.html +++ b/nuttx/Documentation/NuttX.html @@ -8,7 +8,7 @@

NuttX RTOS

-

Last Updated: August 24, 2011

+

Last Updated: September 4, 2011

@@ -381,34 +381,31 @@

-

  • Tiny in-memory, root pseudo-file-system.
    • +
  • Tiny, in-memory, root pseudo-file-system.

    • -

    -

  • Supports character and block drivers.
    • +
  • Virtual file system supports drivers and mountpoints.

    • -

  • - Network, USB (host), USB (device), serial, CAN, ADC, DAC driver architectures. + Mount-able volumes. Bind mountpoint, filesystem, and block device driver.

    • -

  • - RAMDISK, pipes, FIFO, /dev/null, /dev/zero, and loop drivers. + FAT12/16/32 filesystem support with optional FAT long file name support1.

    • @@ -417,7 +414,7 @@

  • - Mount-able volumes. Bind mountpoint, filesystem, and block device driver. + NXFFS. The tiny NuttX wear-leveling FLASH file system.

    • @@ -425,51 +422,73 @@

    -

  • - FAT12/16/32 filesystem support with optional FAT long file name support1. -
    • +
  • ROMFS filesystem support.


    • -

  • - NXFFS. The tiny NuttX wear-leveling FLASH file system. -
    • +
  • NXFLAT. + A new binary format call NXFLAT that can be used to + execute separately linked programs in place in a file system. +

    + + +
    + +

    + 1 + FAT long file name support may be subject to certain Microsoft patent restrictions if enabled. + See the top-level COPYING file for details. +

    + + + + + + Device Drivers + + + + +
    + +

    +

  • Supports character and block drivers as well as specialized driver interfaces.


    • -

  • Generic driver for SPI-based or SDIO-based MMC/SD/SDH cards.
    • +
  • + Network, USB (host), USB (device), serial, CAN, ADC, DAC driver architectures. +


    • -

  • ROMFS filesystem support.
    • +
  • + RAMDISK, pipes, FIFO, /dev/null, /dev/zero, and loop drivers. +


    • -

  • NXFLAT. - A new binary format call NXFLAT that can be used to - execute separately linked programs in place in a file system. +
  • Generic driver for SPI-based or SDIO-based MMC/SD/SDH cards.


    • -

    - 1 - FAT long file name support may be subject to certain Microsoft patent restrictions if enabled. - See the top-level COPYING file for details. -

    +

    +

  • Power management sub-system.
    • +

    @@ -2629,13 +2648,46 @@ nuttx-6.9 2011-xx-xx Gregory Nutt <spudmonkey@racsa.co.cr> Much more is needed. * graphics/, include/nuttx/nx: Add new NX interfaces for drawing circles -- both circular outlines and filled circles. - * graphic/nxglib/nxglib_spitline.c: Add a "fudge factor" that eliminates + * graphic/nxglib/nxglib_spitline.c: Add a "fudge factor" that eliminates some problems for rendering nearly horizontal, wide lines. + * drivers/analog, include/nuttx/analog, arch/arch/src/lpcxx: (1) Add + updates to the ADS1255 driver, (2) fix errors from my last merge (sorry), + (3) Add DAC infrastructure, (4) add AD5410 DAC driver, and (5) add + LPC17xx ADC and DAC drivers. All contributed by Li Zhuoyi (Lzyy). + * tools/mkexport.sh: Extended the script that implements the top-level + 'make export' logic. The script now also finds and bundles up all of + the architecture-specific header files as well. + * drivers/arch/arm/src/stm32/stm32_i2c.c: Add a reset to the I2C + initialization logic to prevent spurious interrups when the I2C + interrupts are enabled (submitted by Uros Platise). + * Scripts/makefiles/documents. Several adjustments, corrections and + typo fixes so that NuttX will build correctly on FreeBSD using the + ASH shell (submitted by Kurt Lidl). + * drivers/mtd/flash_eraseall.c: Add a callable function that accepts + the path to a block driver and then erases the underlying FLASH memory + (assuming that the block driver is an MTD driver wrapped in the FTL + layer). + * drivers/bch: Fixed some important bugs in the BCH driver (noted by + Li Zhuoyi (Lzyy)). This would have effected any large reads or writes + (larger than the hardware sector size). + * arch/*/src/Makefile: Use of -print-libgcc-file-name to get path to + libgcc.a may select the wrong libgcc.a if a multilib toolchain (like + CodeSourcery) is used. This can be a serious problem and can cause + crashes on Cortex-M3 if the ARM libgcc is used, for example. The fix + is to include ARCHCPUFLAGS on the gcc command line when asking it to + -print-libgcc-file-name. + * lib/time/lib_gmtimer.c: Correct several calculations that could lead + to errors in dates. + * drivers/pm: Add the beginnings of a NuttX power management sub-system. apps-6.9 2011-xx-xx Gregory Nutt <spudmonkey@racsa.co.cr> * apps/examples/nxlines: Extend the line drawing text to include drawing of circles. + * apps/system/i2c: Add an I2C test tool that should help to bring up I2C + devices (when it is fully functional). + * apps/nshlib/nsh_timcmds.c: Add the date command that can be used to + show or set the time (only if CONFIG_RTC is set). pascal-3.1 2011-xx-xx Gregory Nutt <spudmonkey@racsa.co.cr> diff --git a/nuttx/Documentation/NuttxPortingGuide.html b/nuttx/Documentation/NuttxPortingGuide.html index 17d7ad176..2a156f008 100644 --- a/nuttx/Documentation/NuttxPortingGuide.html +++ b/nuttx/Documentation/NuttxPortingGuide.html @@ -12,7 +12,7 @@

    NuttX RTOS Porting Guide

    -

    Last Updated: August 25, 2011

    +

    Last Updated: September 4, 2011

    @@ -110,7 +110,7 @@ 5.0 NuttX File System
    - 6.0 NuttX Device Drivers
    + 6.0 NuttX Device Drivers + 6.4 Power Management + Appendix A: NuttX Configuration Settings
    Appendix B: Trademarks @@ -3177,6 +3183,262 @@ extern void up_ledoff(int led); +

    6.4 Power Management

    + +

    6.4.1 Overview

    +

    + NuttX supports a simple power managment (PM) sub-system. This sub-system: +

    + +

    + The PM sub-system integrates the MCU idle loop with a collection of device drivers to support: +

    + +

    + 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 +
    The normal, full power operating mode. +
    IDLE +
    This is still basically normal operational mode, the system is, + however, 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 +
    Standby is a lower power consumption mode that may involve more + extensive power management steps such has disabling clocking or + setting the processor into reduced power consumption modes. In + this state, the system should still be able to resume normal + activity almost immediately. +
    SLEEP +
    The lowest power consumption mode. The most drastic power + reduction measures possible should be taken in this state. It + may require some time to get back to normal operation from + 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. +

    + +

    6.4.2 Interfaces

    +

    + All PM interfaces are declared in the file include/nuttx/pm.h. +

    + +

    6.4.2.1 pm_initialize()

    +

    Function Prototype:

    + +

    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 +

    + +

    6.4.2.2 pm_register()

    +

    Function Prototype:

    + +

    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 +
    An instance of struct pm_callback_s providing the driver callback functions. +
    +

    +

    Returned Value: +Zero (OK) on success; otherwise a negater errno value is returned. +

    + +

    6.4.2.3 pm_activity()

    +

    Function Prototype:

    + +

    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 +
    + Activity priority, range 0-9. + Larger values correspond to higher priorities. + Higher priority activity can prevent the system 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. +
    +

    +

    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!). +

    + +

    6.4.2.4 pm_checkstate()

    +

    Function Prototype:

    + +

    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. +

    + +

    6.4.2.5 pm_changestate()

    +

    Function Prototype:

    + +

    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 +
    Identifies the new PM state +
    +

    +

    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. +

    + +

    6.4.3 Callbacks

    +

    + 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. +

    + +

    6.4.3.1 prepare()

    +

    Function Prototype:

    + +

    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 +
    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 +
    Identifies the new PM state +
    +

    +

    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! +

    + +

    6.4.3.1 notify()

    +

    Function Prototype:

    + +

    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 +
    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 +
    Identifies the new PM state +
    +

    +

    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/nuttx/drivers/README.txt b/nuttx/drivers/README.txt index 3c337956f..e5a1483b2 100644 --- a/nuttx/drivers/README.txt +++ b/nuttx/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/nuttx/drivers/pm/pm_activity.c b/nuttx/drivers/pm/pm_activity.c index f1518520b..a0bae76fa 100644 --- a/nuttx/drivers/pm/pm_activity.c +++ b/nuttx/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/nuttx/drivers/pm/pm_changestate.c b/nuttx/drivers/pm/pm_changestate.c index e98e46236..50fa0640f 100644 --- a/nuttx/drivers/pm/pm_changestate.c +++ b/nuttx/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/nuttx/drivers/pm/pm_checkstate.c b/nuttx/drivers/pm/pm_checkstate.c index 6b23ad05c..3a7f13d47 100644 --- a/nuttx/drivers/pm/pm_checkstate.c +++ b/nuttx/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/nuttx/include/nuttx/pm.h b/nuttx/include/nuttx/pm.h index 36daadcbc..f5375fc6a 100644 --- a/nuttx/include/nuttx/pm.h +++ b/nuttx/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 -- cgit v1.2.3