Update PM documentation

git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@3937 42af7a65-404d-4744-a932-0658087f49c3

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 @@
   <tr align="center" bgcolor="#e4e4e4">
     <td>
       <h1><big><font color="#3c34ec"><i>NuttX RTOS</i></font></big></h1>
-      <p>Last Updated: August 24, 2011</p>
+      <p>Last Updated: September 4, 2011</p>
     </td>
   </tr>
 </table>
@@ -381,34 +381,31 @@
   <td><br></td>
   <td>
     <p>
-      <li>Tiny in-memory, root pseudo-file-system.</li>
+      <li>Tiny, in-memory, root pseudo-file-system.</li>
     </p>
 </tr>
-
 <tr>
   <td><br></td>
   <td>
     <p>
-      <li>Supports character and block drivers.</li>
+      <li>Virtual file system supports drivers and mountpoints.</li>
     </p>
 </tr>
-
 <tr>
   <td><br></td>
   <td>
     <p>
       <li>
-        Network, USB (host), USB (device), serial, CAN, ADC, DAC driver architectures.
+        Mount-able volumes.  Bind mountpoint, filesystem, and block device driver.
       </li>
     </p>
 </tr>
-
 <tr>
   <td><br></td>
   <td>
     <p>
       <li>
-        RAMDISK, pipes, FIFO, <code>/dev/null</code>, <code>/dev/zero</code>, and loop drivers.
+        FAT12/16/32 filesystem support with optional FAT long file name support<small><sup>1</sup></small>.
       </li>
     </p>
 </tr>
@@ -417,7 +414,7 @@
   <td>
     <p>
       <li>
-        Mount-able volumes.  Bind mountpoint, filesystem, and block device driver.
+        NXFFS. The tiny NuttX wear-leveling FLASH file system.
       </li>
     </p>
 </tr>
@@ -425,51 +422,73 @@
   <td><br></td>
   <td>
     <p>
-      <li>
-        FAT12/16/32 filesystem support with optional FAT long file name support<small><sup>1</sup></small>.
-      </li>
+      <li>ROMFS filesystem support.</li>
     </p>
 </tr>
 <tr>
   <td><br></td>
   <td>
     <p>
-      <li>
-        NXFFS. The tiny NuttX wear-leveling FLASH file system.
-      </li>
+      <li><a href="NuttXNxFlat.html">NXFLAT</a>.
+      A new binary format call NXFLAT that can be used to 
+      execute separately linked programs in place in a file system.
+    </p>
+</tr>
+<tr>
+  <td><br></td>
+  <td>
+    <p><small>
+      <sup>1</sup>
+      FAT long file name support may be subject to certain Microsoft patent restrictions if enabled.
+      See the top-level <code>COPYING</code> file for details.
+    </small></p>
+</tr>
+
+<tr>
+  <td valign="top" width="22"><img height="20" width="20" src="favicon.ico"></td>
+  <td bgcolor="#5eaee1">
+    <b>Device Drivers</b>
+  </td>
+</tr>
+
+<tr>
+  <td><br></td>
+  <td>
+    <p>
+      <li>Supports character and block drivers as well as specialized driver interfaces.</li>
     </p>
 </tr>
 <tr>
   <td><br></td>
   <td>
     <p>
-      <li>Generic driver for SPI-based or SDIO-based MMC/SD/SDH cards.</li>
+      <li>
+        Network, USB (host), USB (device), serial, CAN, ADC, DAC driver architectures.
+      </li>
     </p>
 </tr>
 <tr>
   <td><br></td>
   <td>
     <p>
-      <li>ROMFS filesystem support.</li>
+      <li>
+        RAMDISK, pipes, FIFO, <code>/dev/null</code>, <code>/dev/zero</code>, and loop drivers.
+      </li>
     </p>
 </tr>
 <tr>
   <td><br></td>
   <td>
     <p>
-      <li><a href="NuttXNxFlat.html">NXFLAT</a>.
-      A new binary format call NXFLAT that can be used to 
-      execute separately linked programs in place in a file system.
+      <li>Generic driver for SPI-based or SDIO-based MMC/SD/SDH cards.</li>
     </p>
 </tr>
 <tr>
   <td><br></td>
   <td>
-    <p><small>
-      <sup>1</sup>
-      FAT long file name support may be subject to certain Microsoft patent restrictions if enabled.
-      See the top-level <code>COPYING</code> file for details.
-    </small></p>
+    <p>
+      <li><a href="NuttxPortingGuide.html#pwrmgmt">Power management</a> sub-system.</li>
+    </p>
 </tr>
 
 <tr>
@@ -2629,13 +2648,46 @@ nuttx-6.9 2011-xx-xx Gregory Nutt &lt;spudmonkey@racsa.co.cr&gt;
       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 &quot;fudge factor&quot; 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 &lt;spudmonkey@racsa.co.cr&gt;
 
     * 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 &lt;spudmonkey@racsa.co.cr&gt;
 
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 @@
       <h1><big><font color="#3c34ec">
         <i>NuttX RTOS Porting Guide</i>
       </font></big></h1>
-      <p>Last Updated: August 25, 2011</p>
+      <p>Last Updated: September 4, 2011</p>
     </td>
   </tr>
 </table>
@@ -110,7 +110,7 @@
     </ul>
   </ul>
   <a href="#NxFileSystem">5.0 NuttX File System</a><br>
-  <a href="#DeviceDrivers">6.0 NuttX Device Drivers</a><br>
+  <a href="#DeviceDrivers">6.0 NuttX Device Drivers</a>
   <ul>
     <a href="#chardrivers">6.1 Character Device Drivers</a><br>
     <a href="#blockdrivers">6.2 Block Device Drivers</a><br>
@@ -128,6 +128,12 @@
        <a href="#usbdevdrivers">6.3.10 USB Device-Side Drivers</a><br>
        <a href="#analogdrivers">6.3.11 Analog (ADC/DAC) Drivers</a>
     </ul>
+    <a href="#pwrmgmt">6.4 Power Management</a>
+    <ul>
+       <a href="#pmoverview">6.4.1 Overview</a><br>
+       <a href="#pminterfaces">6.4.2 Interfaces</a><br>
+       <a href="#pmcallbacks">6.4.3 Callbacks</a>
+    </ul>
   </ul>
   <a href="#apndxconfigs">Appendix A: NuttX Configuration Settings</a><br>
   <a href="#apndxtrademarks">Appendix B:  Trademarks</a>
@@ -3177,6 +3183,262 @@ extern void up_ledoff(int led);
   </li>
 </ul>
 
+<h2><a name="pwrmgmt">6.4 Power Management</a></h2>
+
+<h3><a name="pmoverview">6.4.1 Overview</a></h3>
+<p>
+  NuttX supports a simple power managment (PM) sub-system.  This sub-system:
+</p>
+<ul>
+  <li>
+    <p>
+      Monitors driver activity, and
+    </p>
+  </li>
+  <li>
+    <p>
+      Provides hooks to place drivers (and the whole system) into reduce power
+      modes of operation.
+    </p>
+  </li>
+</ul>
+<p>
+  The PM sub-system integrates the MCU idle loop with a collection of device drivers to support:
+</p>
+<ul>
+  <li>
+    <p>
+      Reports of relevant driver or other system activity. 
+    </p>
+  </li>
+  <li>
+    <p>
+      Registration and callback mechanism to interface with individual device drivers. 
+    </p>
+  </li>
+  <li>
+    <p>
+      IDLE time polling of overall driver activity.
+    </p>
+  </li>
+  <li>
+    <p>
+      Coordinated, global, system-wide transitions to lower power usage states.
+    </p>
+  </li>
+</ul>
+<p>
+  Various &quot;sleep&quot; 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:
+</p>
+<dl>
+  <dt><code>NORMAL</code>
+  <dd>The normal, full power operating mode.
+  <dt><code>IDLE</code>
+  <dd>This is still basically normal operational mode, the system is,
+      however, <code>IDLE</code> 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.
+  <dt><code>STANDBY</code>
+  <dd>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.
+  <dt><code>SLEEP</code>
+  <dd>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
+      <code>SLEEP</code> (some MCUs may even require going through reset).
+</dl>
+<p>
+  These various states are represented with type <code>enum pm_state_e</code> in <code>include/nuttx/pm.h</code>.
+</p>
+
+<h3><a name="pminterfaces">6.4.2 Interfaces</a></h3>
+<p>
+  All PM interfaces are declared in the file <code>include/nuttx/pm.h</code>.
+</p>
+
+<h4><a name="pminitialize">6.4.2.1 pm_initialize()</a></h4>
+<p><b>Function Prototype:</b></p>
+<ul><pre>
+#include &lt;nuttx/pm.h&gt;
+void pm_initialize(void);
+</pre></ul>
+<p><b>Description:</b>
+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 <i>very</i> early in the intialization sequence <i>before</i> any other device drivers are initialize (since they may attempt to register with the power management subsystem).
+</p>
+<p><b>Input Parameters:</b>
+None
+</p>
+<p><b>Returned Value:</b>
+None
+</p>
+
+<h4><a name="pmregister">6.4.2.2 pm_register()</a></h4>
+<p><b>Function Prototype:</b></p>
+<ul><pre>
+#include &lt;nuttx/pm.h&gt;
+int pm_register(FAR struct pm_callback_s *callbacks);
+</pre></ul>
+<p><b>Description:</b>
+  This function is called by a device driver in order to register to receive power management event callbacks.
+  Refer to the <a href="#pmcallbacks">PM Callback</a> section for more details.
+</p>
+<p><b>Input Parameters:</b>
+ <dl>
+   <dt><code>callbacks</code>
+   <dd>An instance of <code>struct pm_callback_s</code> providing the driver callback functions.
+ </dl>
+</p>
+<p><b>Returned Value:</b>
+Zero (<code>OK</code>) on success; otherwise a negater <code>errno</code> value is returned.
+</p>
+
+<h4><a name="pmactivity">6.4.2.3 pm_activity()</a></h4>
+<p><b>Function Prototype:</b></p>
+<ul><pre>
+#include &lt;nuttx/pm.h&gt;
+void pm_activity(int priority);
+</pre></ul>
+<p><b>Description:</b>
+ 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.
+</p>
+<p><b>Input Parameters:</b>
+ <dl>
+   <dt><code>priority</code>
+   <dd>
+     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.
+ </dl>
+</p>
+<p><b>Returned Value:</b>
+  None
+</p>
+<p><b>Assumptions:</b>
+  This function may be called from an interrupt handler (this is the ONLY PM function that may be called from an interrupt handler!).
+</p>
+
+<h4><a name="pmcheckstate">6.4.2.4 pm_checkstate()</a></h4>
+<p><b>Function Prototype:</b></p>
+<ul><pre>
+#include &lt;nuttx/pm.h&gt;
+enum pm_state_e pm_checkstate(void);
+</pre></ul>
+<p><b>Description:</b>
+  This function is called from the MCU-specific IDLE loop to monitor the the power management conditions.
+  This function returns the &quot;recommended&quot; 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 <code>pm_changestate()</code> in order to make the state change.
+</p>
+<p>
+  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.
+</p>
+<p>
+  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 <code>pm_checkstate()</code> and <code>pm_changestate()</code>.
+  The IDLE loop may need to make these calls atomic by either disabling interrupts until the state change is completed.
+</p>
+<p><b>Input Parameters:</b>
+  None
+</p>
+<p><b>Returned Value:</b>
+  The recommended power management state.
+</p>
+
+<h4><a name="pmchangestate">6.4.2.5 pm_changestate()</a></h4>
+<p><b>Function Prototype:</b></p>
+<ul><pre>
+#include &lt;nuttx/pm.h&gt;
+ int pm_changestate(enum pm_state_e newstate);
+</pre></ul>
+<p><b>Description:</b>
+  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.
+</p>
+<p><b>Input Parameters:</b>
+ <dl>
+   <dt><code>newstate</code>
+   <dd>Identifies the new PM state
+ </dl>
+</p>
+<p><b>Returned Value:</b>
+  0 (<code>OK</code>) means that the callback function for all registered drivers returned <code>OK</code> (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.
+</p>
+<p><b>Assumptions:</b>
+   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.
+</p>
+
+<h3><a name="pmcallbacks">6.4.3 Callbacks</a></h3>
+<p>
+  The <code>struct pm_callback_s</code> includes the pointers to the driver callback functions.
+  This structure is defined <code>include/nuttx/pm.h</code>.
+  These callback functions can be used to provide power management information to the driver.
+</p>
+
+<h4><a name="pmprepare">6.4.3.1 prepare()</a></h4>
+<p><b>Function Prototype:</b></p>
+<ul><pre>
+int (*prepare)(FAR struct pm_callback_s *cb, enum pm_state_e pmstate);
+</pre></ul>
+<p><b>Description:</b>
+   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.
+</p>
+<p><b>Input Parameters:</b>
+ <dl>
+   <dt><code>cb</code>
+   <dd>Returned to the driver.
+   The driver version of the callback strucure may include additional, driver-specific state data at the end of the structure.
+   <dt><code>pmstate</code>
+   <dd>Identifies the new PM state
+ </dl>
+</p>
+<p><b>Returned Value:</b>
+   Zero (<code>OK</code>) 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 <code>prepare()</code> 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!
+</p>
+
+<h4><a name="pmnotify">6.4.3.1 notify()</a></h4>
+<p><b>Function Prototype:</b></p>
+<ul><pre>
+#include &lt;nuttx/pm.h&gt;
+void (*notify)(FAR struct pm_callback_s *cb, enum pm_state_e pmstate);
+</pre></ul>
+<p><b>Description:</b>
+  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.
+</p>
+<p><b>Input Parameters:</b>
+ <dl>
+   <dt><code>cb</code>
+   <dd>Returned to the driver.
+   The driver version of the callback strucure may include additional, driver-specific state data at the end of the structure.
+   <dt><code>pmstate</code>
+   <dd>Identifies the new PM state
+ </dl>
+</p>
+<p><b>Returned Value:</b>
+  None.
+  The driver already agreed to transition to the low power consumption state when when it returned <code>OK</code> to the <code>prepare()</code> call.
+</p>
+
 <table width ="100%">
   <tr bgcolor="#e4e4e4">
     <td>
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