1    /*
     2     * Copyright (c) 2013, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     */
    32    /*
    33     *  ======== Power.xdc ========
    34     *
    35     *
    36     */
    37    
    38    package ti.sysbios.family.c674;
    39    
    40    import xdc.rov.ViewInfo;
    41    
    42    import ti.sysbios.knl.Queue;
    43    
    44    /*!
    45     *  ======== Power ========
    46     *  Power management support for C6748 and OMAP-L138 devices.
    47     *
    48     *  The SYS/BIOS Power Manager, (Power module) provides APIs that allow you to
    49     *  reduce power consumption of C6748 and OMAP-L138 applications.  It provides
    50     *  the following core functionality:
    51     *
    52     *  Resource tracking.  You can set and release program dependencies upon power
    53     *  manageable resources.  For example, when a dependency is set on a UART, if
    54     *  it is the first dependency upon the UART, then Power will automatically
    55     *  enable the clock to the UART module.  And when the last dependency on the
    56     *  UART is released, Power will automatically disable the clock to the UART.
    57     *
    58     *  Voltage and frequency scaling.  You can dynamically change the voltage and
    59     *  frequency for the CPU domain, or the peripheral domain.  Since power
    60     *  consumption is linearly proportional to frequency and quadratically
    61     *  proportional to voltage, this can significantly reduce power consumption
    62     *  of the device.
    63     *
    64     *  CPU idling.  You can configure Power to automatically idle (i.e., clock
    65     *  gate) the CPU while waiting for the next interrupt, at which time new
    66     *  processing is required.  This is a "lightweight" sleep mechanism and has
    67     *  negligible CPU wakeup latency.
    68     *
    69     *  Activate sleep modes.  You can dynamically activate processor sleep modes
    70     *  that will perform clock gating and in some cases voltage reduction.  These
    71     *  sleep modes are "heavier weight" compared to idling, with longer wakeup
    72     *  latency, but provide significant savings during application standby times.
    73     *
    74     *  Coordinate scaling and sleep modes.  You can register application functions
    75     *  to be called upon specific power events, for example, before activating a
    76     *  particular sleep mode.  The Power module will call these functions at the
    77     *  appropriate times, allowing coordination between affected software
    78     *  components, and power saving actions of the Power module.
    79     *
    80     *  For further overview of the Power module, please see:
    81     *  @p(html)
    82     *  <a href=https://processors.wiki.ti.com/index.php/Power_Module_for_C6748_and_OMAP-L138><i>Power Module for C6748 and OMAP-L138</i></a>
    83     *  @p
    84     *
    85     *  @p(html)
    86     *  <h3> Calling Context </h3>
    87     *  <table border="1" cellpadding="3">
    88     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
    89     *
    90     *    <tr><th> Function                 </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th><th>  Main  </th><th>  Startup  </th></tr>
    91     *    <!-- -->
    92     *    <tr><td> {@link #changeSetpoint} </td><td>   N    </td><td>   Y*    </td><td>   Y </td><td>   N    </td><td>   N    </td></tr>
    93     *    <tr><td> {@link #configure} </td><td>   Y    </td><td>   Y    </td><td>   Y </td><td>   Y    </td><td>   Y    </td></tr>
    94     *    <tr><td> {@link #getCapabilities}  </td><td>   Y    </td><td>   Y    </td><td>   Y   </td><td>   Y    </td><td>   Y    </td></tr>
    95     *    <tr><td> {@link #getConstraintInfo}  </td><td>   Y    </td><td>   Y    </td><td>   Y   </td><td>   Y    </td><td>   Y    </td></tr>
    96     *    <tr><td> {@link #getCurrentSetpoint}  </td><td>   Y    </td><td>   Y    </td><td>   Y   </td><td>   Y    </td><td>   Y    </td></tr>
    97     *    <tr><td> {@link #getDependencyCount}  </td><td>   Y    </td><td>   Y    </td><td>   Y   </td><td>   Y    </td><td>   Y    </td></tr>
    98     *    <tr><td> {@link #getNumSetpoints}  </td><td>   Y    </td><td>   Y    </td><td>   Y   </td><td>   Y    </td><td>   Y    </td></tr>
    99     *    <tr><td> {@link #getSepointInfo}  </td><td>   Y    </td><td>   Y    </td><td>   Y   </td><td>   Y    </td><td>   Y    </td></tr>
   100     *    <tr><td> {@link #getTransitionLatency}  </td><td>   Y    </td><td>   Y    </td><td>   Y   </td><td>   Y    </td><td>   Y    </td></tr>
   101     *    <tr><td> {@link #registerConstraint}  </td><td>   N    </td><td>   N    </td><td>   Y   </td><td>   Y    </td><td>   Y    </td></tr>
   102     *    <tr><td> {@link #registerNotify}  </td><td>   N    </td><td>   N    </td><td>   Y   </td><td>   Y    </td><td>   Y    </td></tr>
   103     *    <tr><td> {@link #releaseDependency}  </td><td>   Y    </td><td>   Y    </td><td>   Y   </td><td>   Y    </td><td>   Y    </td></tr>
   104     *    <tr><td> {@link #setDependency}  </td><td>   Y    </td><td>   Y    </td><td>   Y   </td><td>   Y    </td><td>   Y    </td></tr>
   105     *    <tr><td> {@link #signalEvent}  </td><td>   Y*    </td><td>   Y*    </td><td>   Y   </td><td>   N    </td><td>   N    </td></tr>
   106     *    <tr><td> {@link #sleepDSP}  </td><td>   N    </td><td>   Y*    </td><td>   Y   </td><td>   N    </td><td>   N    </td></tr>
   107     *    <tr><td> {@link #unregisterConstraint}  </td><td>   Y    </td><td>   Y    </td><td>   Y   </td><td>   Y    </td><td>   Y    </td></tr>
   108     *    <tr><td> {@link #unregisterNotify}  </td><td>   Y    </td><td>   Y    </td><td>   Y   </td><td>   Y    </td><td>   Y    </td></tr>
   109     *    <tr><td colspan="6"> Definitions: <br />
   110     *       <ul>
   111     *         <li> <b>Hwi</b>: API is callable from a Hwi thread </li>
   112     *         <li> <b>Swi</b>: API is callable from a Swi thread </li>
   113     *         <li> <b>Task</b>: API is callable from a Task thread </li>
   114     *         <li> <b>Main</b>: API is callable from main() </li>
   115     *         <li> <b>Startup</b>: API is callable during any module startup </li>
   116     *         <li> <b>Y</b>: Yes </li>
   117     *         <li> <b>Y*</b>: Yes, but see API description for restrictions </li>
   118     *         <li> <b>N</b>: No </li>
   119     *       </ul>
   120     *    </td></tr>
   121     *
   122     *  </table>
   123     *  @p
   124     */
   125    @ModuleStartup            /* Initialize Power */
   126    @Template("./Power.xdt")  /* Template for contitional initiatialization calls */
   127    
   128    module Power inherits ti.sysbios.interfaces.IPower
   129    {
   130        /*! Power attributes structure. */
   131        struct Attrs {
   132            Bool scaleVoltage;          /*! Scale voltage along with frequency */
   133            Bool waitForVoltageScale;   /*! Wait during down voltage ramp */
   134        };
   135    
   136        /*! Scaling configuration structure. */
   137        struct Config {
   138            Bool scaleVoltage;              /*! Scale voltage with frequency? */
   139            Bool waitForVoltageScale;       /*! Wait for down ramp? */
   140        };
   141    
   142        /*! Setpoint info structure. */
   143        struct SetpointInfo {
   144            UInt frequency;                 /*! Clock frequency */
   145            UInt voltage;                   /*! Voltage */
   146        };
   147    
   148        /*! Sleep attributes override structure. */
   149        struct SleepOverride {
   150            UInt sleepVoltage; /*! override sleep voltage (millivolts) for Power_SLEEP */
   151            UInt bypassedPLLs; /*! override PLLs to bypass for Power_SLEEP */
   152        };
   153    
   154        typedef UArg * ConstraintHandle; /*! Handle for a registered constraint */
   155    
   156        typedef Void * NotifyHandle; /*! Handle for a registered notification */
   157    
   158        /*! Idle function prototype */
   159        typedef Void (*FuncPtr)();
   160    
   161        /*!
   162         *  ======== Constraint ========
   163         *  Constraints that can be registered with Power
   164         */
   165        enum Constraint {
   166            DISALLOWED_CPU_SETPOINT_MASK = 1, /*! Disallowed CPU domain setpoints */
   167            DISALLOWED_PER_SETPOINT_MASK = 2, /*! Disallowed peripheral domain setpoints */
   168            DISALLOWEDSLEEPSTATE_MASK = 3     /*! Disallowed sleep states */
   169        };
   170    
   171        /*!
   172         *  ======== Domain ========
   173         *  Scaling domains
   174         */
   175        enum Domain {
   176            CPU = 0, /*! CPU domain */
   177            PER      /*! Peripheral domain */
   178        };
   179    
   180        /*!
   181         *  ======== Event ========
   182         *  Power Event enumerations
   183         */
   184        enum Event {
   185            GOINGTOSTANDBY = 0, /*! Going to Power_STANDBY */
   186            AWAKEFROMSTANDBY,   /*! Awake from Power_STANDBY */
   187            GOINGTOSLEEP,       /*! Going to Power_SLEEP */
   188            AWAKEFROMSLEEP,     /*! Awake from Power_SLEEP */
   189            GOINGTODEEPSLEEP,   /*! Going to Power_DEEPSLEEP */
   190            AWAKEFROMDEEPSLEEP, /*! Awake from Power_DEEPSLEEP */
   191            PENDING_CPU_SETPOINTCHANGE, /*! A CPU setpoint change is about to occur */
   192            PENDING_PER_SETPOINTCHANGE, /*! A peripheral setpoint change is about to occur */
   193            DONE_CPU_SETPOINTCHANGE, /*! A CPU setpoint change has just completed */
   194            DONE_PER_SETPOINTCHANGE, /*! A peripheral setpoint change has just completed */
   195            INVALIDEVENT
   196        };
   197    
   198        /*!
   199         *  ======== NUMEVENTS ========
   200         *  @_nodoc
   201         */
   202        metaonly const UInt NUMEVENTS = INVALIDEVENT;
   203    
   204        /*!
   205         *  ======== NotifyResponse ========
   206         *  Return values from a notify function.
   207         */
   208        enum NotifyResponse {
   209            NOTIFYDONE = 0,  /*! Client has finished processing the notification */
   210            NOTIFYNOTDONE, /*! Client needs to wait (delayed completion) to finish processing the notification */
   211            NOTIFYERROR /*! An error occurred while processing the notification */
   212        };
   213    
   214        const UInt EXTERNAL = 0x8; /*! Used to specify external controller wakeup source for Power_DEEPSLEEP */
   215        const UInt RTC_ALARM = 0x10; /*! Used to specify an RTC alarm wakeup source for Power_DEEPSLEEP */
   216    
   217        const UInt PLL0 = 0x1; /*! Used to specify bypass PLL0 during Power_SLEEP */
   218        const UInt PLL1 = 0x2; /*! Used to specify bypass PLL1 during Power_SLEEP */
   219    
   220        const UInt CVFSCALING = 0x8; /*! Bitmask for V/F scaling capability */
   221        const UInt CRESOURCETRACKING = 0x200; /*! Bitmask for resource tracking capability */
   222    
   223        /*!
   224         *  ======== Resource ========
   225         *  Resource enumerations.  Some of these are not applicable for C6746 and
   226         *  C6742 derivative devices.
   227         */
   228        enum Resource {
   229            RSRC_EDMA3_CC_0   = 0, /*! EDMA3_0 Channel Controller 0 */
   230            RSRC_EDMA3_TC_0   = 1, /*! EDMA3_0 Transfer Controller 0 */
   231            RSRC_EDMA3_TC_1   = 2, /*! EDMA3_0 Transfer Controller 1 */
   232            RSRC_EMIFA        = 3, /*! EMIFA */
   233            RSRC_SPI_0        = 4, /*! SPI0 */
   234            RSRC_MMCSD_0      = 5, /*! MMC/SD0 */
   235            RSRC_AINTC        = 6, /*! ARM Interrupt Controller */
   236            RSRC_RSVD1        = 7, /*! RESERVED */
   237            RSRC_UART_0       = 8, /*! UART0 */
   238            RSRC_RSVD2        = 9, /*! RESERVED */
   239            RSRC_EDMA3_CC_1   = 10, /*! EDMA3_1 Channel Controller 0 */
   240            RSRC_USB0         = 11, /*! USB0 */
   241            RSRC_USB1         = 12, /*! USB1 */
   242            RSRC_GPIO         = 13, /*! GPIO */
   243            RSRC_UHPI         = 14, /*! HPI */
   244            RSRC_EMAC         = 15, /*! EMAC */
   245            RSRC_DDR2         = 16, /*! DDR2/mDDR */
   246            RSRC_MCASP_0      = 17, /*! McASP0 */
   247            RSRC_SATA         = 18, /*! SATA */
   248            RSRC_VPIF         = 19, /*! VPIF */
   249            RSRC_SPI_1        = 20, /*! SPI1 */
   250            RSRC_I2C_1        = 21, /*! I2C1 */
   251            RSRC_UART_1       = 22, /*! UART1 */
   252            RSRC_UART_2       = 23, /*! UART2 */
   253            RSRC_MCBSP_0      = 24, /*! McBSP0 */
   254            RSRC_MCBSP_1      = 25, /*! McBSP1 */
   255            RSRC_LCDC         = 26, /*! LCDC */
   256            RSRC_EHRPWM       = 27, /*! eHRPWM0/1 */
   257            RSRC_MMCSD_1      = 28, /*! MMC/SD1 */
   258            RSRC_UPP          = 29, /*! uPP */
   259            RSRC_ECAP         = 30, /*! eCAP0/1/2 */
   260            RSRC_EDMA3_TC_2   = 31, /*! EDMA3_1 Transfer Controller 0 */
   261            RSRC_END          = 32
   262        };
   263    
   264        /*!
   265         *  ======== SleepCode ========
   266         *  Sleep modes
   267         */
   268        enum SleepCode {
   269            STANDBY = 0x1,
   270            SLEEP = 0x2,
   271            DEEPSLEEP = 0x4
   272        };
   273    
   274        /*!
   275         *  ======== Status ========
   276         *  Function return codes
   277         */
   278        enum Status {
   279            SOK = 0,
   280            EFAIL = 1,
   281            EINVALIDEVENT = 2,
   282            EINVALIDHANDLE = 3,
   283            EINVALIDPOINTER = 4,
   284            EINVALIDVALUE = 5,
   285            ENOTIMPLEMENTED = 6,
   286            ENOTSUPPORTED = 7,
   287            EOUTOFRANGE = 8,
   288            ETIMEOUT = 9,
   289            EBUSY = 10,
   290            EINITFAILURE = 11,
   291            ETOOMANYCALLS = 12
   292        };
   293    
   294        /*! Power Management Interface (PMI) control library options */
   295        enum pmiLib {
   296            pmiLib_evm6748,       /*! evm6748 with dedicated I2C control of PMIC */
   297            pmiLib_shared_evm6748,/*! evm6748 with shared I2C control of PMIC */
   298            pmiLib_lcdk,          /*! LCDK with no voltage scaling */
   299            pmiLib_null,          /*! evm6748 with no voltage scaling */
   300            pmiLib_user           /*! user will provide custom PMI library */
   301        };
   302    
   303        /*! Power Scaling Library (PSCL) configuration library options */
   304        enum psclLib {
   305            psclLib_evm6748,     /*! evm6748 with 300MHz device */
   306            psclLib_evm6748_372, /*! evm6748 with 372MHz device */
   307            psclLib_evm6748_408, /*! evm6748 with 408MHz device */
   308            psclLib_evm6748_456, /*! evm6748 with 456MHz device */
   309            psclLib_lcdk,        /*! LCDK with 456MHz device */
   310            psclLib_null,        /*! evm6748 with 300MHz device, no scaling */
   311            psclLib_user         /*! user will provide custom PSCL library */
   312        };
   313    
   314        /*!
   315         * On-chip memory region.  The memory region for placing Power's code and
   316         * data that must reside on-chip.  Default is IRAM.
   317         */
   318        metaonly config String onChipRegion = "IRAM";
   319    
   320        /*!
   321         *  ======== idle ========
   322         *  Idle the CPU during idle time?
   323         */
   324        override config Bool idle = false;
   325    
   326        /*!
   327         *  ======== idleCpu ========
   328         *  This configuration parameter has been deprecated. Use {@link #idle}
   329         *  instead.
   330         */
   331        /*! Idle the CPU during idle time?  Default is false. */
   332        metaonly config Bool idleCpu = false;
   333    
   334        /*! Idle function.  Default is Power_idleStopClock. */
   335        metaonly config FuncPtr idleFunc = Power.idleStopClock;
   336    
   337        /*! Enable resource tracking?  Default is false. */
   338        config Bool trackResources = false;
   339    
   340        /*! Enable voltage and frequency (V/F) scaling?  Default is false. */
   341        config Bool enableScaling = false;
   342    
   343        /*! Initial CPU domain setpoint.  Default is 2. */
   344        config UInt initialSetpointCPU = 2;
   345    
   346        /*! Initial peripheral (PER) domain setpoint.  Default is 0. */
   347        config UInt initialSetpointPER = 0;
   348    
   349        /*!
   350         *  Move to initial setpoints during program initialization?
   351         *  Default is false.
   352         */
   353        metaonly config Bool moveToSetpoints = false;
   354    
   355        /*! Scale voltage along with frequency?  Default is true. */
   356        metaonly config Bool scaleVoltage = true;
   357    
   358        /*! Wait while voltage is scaling downward?  Default is true. */
   359        metaonly config Bool waitVoltage = true;
   360    
   361        /*! Select the PMI control library */
   362        metaonly config pmiLib pmiControlLib = pmiLib_evm6748;
   363    
   364        /*! Select the PSCL configuration library */
   365        metaonly config psclLib psclConfigLib = psclLib_evm6748;
   366    
   367        /*!
   368         *  ======== changeSetpoint ========
   369         *  Initiate a change to the V/F setpoint of the CPU, or the peripheral
   370         *  domain.
   371         *
   372         *  Power_changeSetpoint() changes the voltage and frequency of a
   373         *  scalable domain.
   374         *
   375         *  The domain parameter indicates the relevant scaling domain. The
   376         *  domains that can be scaled vary by platform, and are enumerated as
   377         *  Power_Domain. For example, for the TMS320C6748, there are two
   378         *  scalable domains: the CPU domain (Power_CPU) and the peripheral
   379         *  domain (Power_PER).
   380         *
   381         *  The newSetpoint parameter is a numeric value that indexes into a table
   382         *  of frequency/voltage pairs, as defined by the underlying scaling
   383         *  configuration library.
   384         *
   385         *  The notifyTimeout parameter is the maximum amount of time (in system
   386         *  Clock ticks) to wait for registered notification functions (set by
   387         *  Power_registerNotify()) to respond to a delayed completion, before
   388         *  declaring failure and returning Power_ETIMEOUT.
   389         *
   390         *  For example, if notifyTimeout is set to 200, Power_changeSetpoint()
   391         *  waits up to 200 ticks (typically 200 milliseconds) before declaring
   392         *  that function has failed to respond. Power uses notifyTimeout for each
   393         *  type of notification. For example, if notification functions are
   394         *  registered for both before and after setpoint changes,
   395         *  Power_changeSetpoint() waits up to notifyTimeout on each type of
   396         *  notification.
   397         *
   398         *  All registered notification functions are called from the context of
   399         *  Power_changeSetpoint().
   400         *
   401         *  The application should treat return values of Power_ETIMEOUT or
   402         *  Power_EFAIL as critical system failures. These values indicate the
   403         *  notification client is taking too long or is unresponsive, and the
   404         *  system is in an unknown state.
   405         *
   406         *  Power_changeSetpoint() disables Swi and Task scheduling when it
   407         *  begins making a change. However, Hwis may run during the notification
   408         *  process. After the setpoint has been changed, Swi and Task scheduling
   409         *  are re-enabled, and a context switch occurs only if some other thread
   410         *  has since been made ready to run.
   411         *
   412         *  @param(domain)  The relevant scaling domain (Power_CPU or Power_PER)
   413         *
   414         *  @param(newSetpoint)  The new V/F setpoint to be scaled to
   415         *
   416         *  @param(notifyTimeout)  The maximum time (in Clock ticks) to wait for
   417         *                  client notifications to complete
   418         *
   419         *  @b(returns)     Power_SOK if the operation succeeded and the new
   420         *                  setpoint is in effect
   421         *
   422         *  @b(returns)     Power_EFAIL if a general failure occurred; the
   423         *                  requested transition did not occur
   424         *
   425         *  @b(returns)     Power_ENOTIMPLEMENTED if V/F scaling is not implemented
   426         *                  on this platform
   427         *
   428         *  @b(returns)     Power_ENOTSUPPORTED if the operation failed because
   429         *                  a client registered a constraint with Power indicating
   430         *                  that it cannot support the requested setpoint
   431         *
   432         *  @b(returns)     Power_EOUTOFRANGE if the operation failed because
   433         *                  the domain or newSetpoint parameter is not a valid value
   434         *                  for the platform
   435         *
   436         *  @b(returns)     Power_ETIMEOUT if the operation failed because
   437         *                  a registered notification function did not complete its
   438         *                  processing within the specified notifyTimeout
   439         *
   440         *  @b(returns)     Power_EBUSY if the operation failed because the
   441         *                  operation cannot be performed at this time; Power is
   442         *                  busy processing a previous request
   443         *
   444         *  @b(returns)     Power_EINITFAILURE if there was a previous failure when
   445         *                  V/F scaling support was being initialized; V/F scaling
   446         *                  is unavailable
   447         *
   448         *  @a(constraints)
   449         *  Power_changeSetpoint() cannot be called from a Hwi or main()
   450         *
   451         *  Power_changeSetpoint() can be called from a Swi only if notifyTimeout
   452         *  is zero
   453         */
   454        Status changeSetpoint(Domain domain, UInt newSetpoint, UInt notifyTimeout);
   455    
   456        /*!
   457         *  ======== configure ========
   458         *  Set new configuration parameters for Power.
   459         *
   460         *  Power_configure() specifies new configuration properties for the Power
   461         *  module. It overrides those specified in the static configuration.
   462         *
   463         *  Configuration parameters are specified via a Power_Attrs structure.
   464         *  In this structure, 'scaleVoltage' indicates whether Power should scale
   465         *  voltages during setpoint changes, and when switching to sleep modes that
   466         *  support voltage reduction. It corresponds to the {@link #scaleVoltage}
   467         *  configuration property. If 'scaleVoltage' is TRUE, the voltage is
   468         *  scaled down if possible when going to a lower frequency or activating
   469         *  sleep modes. If 'scaleVoltage' is FALSE, the voltage is not scaled
   470         *  lower. The voltage is always scaled up if the new (destination)
   471         *  setpoint frequency is higher than that supported at the current voltage.
   472         *
   473         *  In the Power_attrs structure, the 'waitForVoltageScale' flag indicates
   474         *  whether Power should wait for a down-voltage transition to complete
   475         *  before returning from Power_changeSetpoint(). It corresponds to the
   476         *  {@link #waitVoltage} configuration property. (Such transition times can
   477         *  be long, and they typically depend upon power supply load.) Currently,
   478         *  it is recommended that this property always be TRUE. Note that the
   479         *  Power module always waits during up-voltage transitions; this is
   480         *  required to avoid overclocking the device.
   481         *
   482         *  @param(attrs)   An {@link #Attrs} structure defining new
   483         *                  configuration parameters
   484         *
   485         *  @b(returns)     Power_SOK if the configuration was changed
   486         *
   487         *  @b(returns)     Power_EINVALIDVALUE if the change failed because one of
   488         *                  the attributes is invalid
   489         */
   490        Status configure(Attrs attrs);
   491    
   492        /*!
   493         *  ======== getCapabilities ========
   494         *  Get info on Power's capabilities on the current platform.
   495         *
   496         *  The capsMask parameter should point to the location where
   497         *  Power_getCapabilities() should write a bitmask that defines the
   498         *  capabilities.
   499         *
   500         *  You can use the following constants to check for capabilities
   501         *  in the bitmask:
   502         *
   503         *    Power_CRESOURCETRACKING  -  Power supports dynamic resource tracking
   504         *
   505         *    Power_CVFSCALING  -  Power supports voltage and frequency scaling
   506         *
   507         *  @param(capsMask)  Location of a bitmask to be written with capabilities
   508         *                    flags
   509         *
   510         *  @b(returns)     Power_SOK if the operation succeeded
   511         *
   512         *  @b(returns)     Power_EINVALIDPOINTER if the operation failed because
   513         *                  capsMask was NULL
   514         */
   515        Status getCapabilities(UInt * capsMask);
   516    
   517        /*!
   518         *  ======== getConstraintInfo ========
   519         *  Get info on the aggregate of constraints that have been registered with
   520         *  Power.
   521         *
   522         *  Power_getConstraintInfo() returns information about constraints that are
   523         *  currently registered with the Power module, via previous calls to
   524         *  Power_registerConstraint().
   525         *
   526         *  The type parameter identifies the type of constraint being queried. The
   527         *  constraint types vary by platform, and are enumerated as
   528         *  Power_Constraint.  Currently the following are supported:
   529         *
   530         *    Power_DISALLOWEDSLEEPSTATE_MASK  -   Sleep states that should
   531         *        not be activated.
   532         *
   533         *    Power_DISALLOWED_CPU_SETPOINT_MASK  -  CPU setpoints that should not
   534         *        be activated.
   535         *
   536         *    Power_DISALLOWED_PER_SETPOINT_MASK  -  Peripheral setpoints that
   537         *        should not be activated.
   538         *
   539         *  Power_getContraintInfo() returns a value that is the aggregate of all
   540         *  constraints that are currently registered. For example, if one Power
   541         *  client disallowed the sleep state Power_SLEEP, and a different client
   542         *  disallowed the sleep state Power_DEEPSLEEP, the returned value will
   543         *  be (Power_SLEEP | Power_DEEPSLEEP).
   544         *
   545         *  @param(type)  Type of constraint
   546         *
   547         *  @param(value)  Location to be written with aggregate of constraints
   548         *
   549         *  @b(returns)     Power_SOK if the operation succeeded
   550         *
   551         *  @b(returns)     Power_EINVALIDVALUE if the operation failed because
   552         *                  type does not correspond to a supported constraint type
   553         *
   554         *  @b(returns)     Power_EINVALIDPOINTER if the operation failed because
   555         *                  the value parameter was NULL
   556         *
   557         */
   558        Status getConstraintInfo(Constraint type, UArg *value);
   559    
   560        /*!
   561         *  ======== getCurrentSetpoint ========
   562         *  Get the current setpoint in effect.
   563         *
   564         *  Power_getCurrentSetpoint() returns the V/F scaling setpoint currently in
   565         *  use for the specified scaling domain.
   566         *
   567         *  The domain parameter indicates the relevant scaling domain. The
   568         *  domains that can be scaled vary by platform, and are enumerated as
   569         *  Power_Domain.
   570         *
   571         *  The setpoint parameter should point to the location where
   572         *  Power_getCurrentSetpoint() should write the current setpoint.
   573         *
   574         *  @param(domain)  The scaling domain being queried (Power_CPU or
   575         *                  Power_PER)
   576         *
   577         *  @param(setpoint)  Location to write the current setpoint
   578         *
   579         *  @b(returns)     Power_SOK if the operation succeeded
   580         *
   581         *  @b(returns)     Power_EINVALIDPOINTER if the operation failed because
   582         *                  the setpoint parameter was NULL
   583         *
   584         *  @b(returns)     Power_EINVALIDVALUE if the operation failed because the
   585         *                  domain parameter was invalid
   586         *
   587         *  @b(returns)     Power_EINITFAILURE if there was a previous failure when
   588         *                  V/F scaling support was being initialized; V/F scaling
   589         *                  is unavailable
   590         *
   591         *  @b(returns)     Power_ENOTSUPPORTED if the operation failed because
   592         *                  V/F scaling support is not enabled
   593         *
   594         *  @a(constraints)
   595         *  If a call to Power_getCurrentSetpoint() is made during a change to the
   596         *  current setpoint, the value Power_getCurrentSetpoint() returns may
   597         *  be the old setpoint and not the new setpoint
   598         *
   599         */
   600        Status getCurrentSetpoint(Domain domain, UInt * setpoint);
   601    
   602        /*!
   603         *  ======== getDependencyCount ========
   604         *  Get the count of dependencies that are currently declared on a resource.
   605         *
   606         *  Power_getDependencyCount() returns the number of dependencies that
   607         *  are currently declared on a resource. Normally this corresponds to the
   608         *  number of times Power_setDependency() has been called for the
   609         *  resource, minus the number of times Power_releaseDependency() has
   610         *  been called for the same resource.
   611         *
   612         *  On some platforms, early boot code may enable individual resources
   613         *  before Power initializes. To ensure proper state synchronization in
   614         *  this case, Power queries individual resource states as the Power module
   615         *  initializes. So, it is possible for the returned "count" value to be 1,
   616         *  even if Power_setDependency() has not been called by the application.
   617         *
   618         *  Resources are enumerated as Power_Resource.
   619         *
   620         *  @param(resourceID)  The resource identifier
   621         *
   622         *  @param(count)  Location to write the resource's dependency count
   623         *
   624         *  @b(returns)     Power_SOK if the operation succeeded
   625         *
   626         *  @b(returns)     Power_EINVALIDPOINTER if the operation failed because
   627         *                  the count parameter was NULL
   628         *
   629         *  @b(returns)     Power_EINVALIDVALUE if the operation failed because
   630         *                  Power cannot control this resource
   631         *
   632         *  @b(returns)     Power_ENOTSUPPORTED if the operation failed because
   633         *                  resource tracking is not enabled
   634         *
   635         *  @b(returns)     Power_EOUTOFRANGE if the specified resourceID is
   636         *                  outside the range of valid resource IDs
   637         */
   638        Status getDependencyCount(Resource resourceID, UInt * count);
   639    
   640        /*!
   641         *  ======== getNumSetpoints ========
   642         *  Get the number of setpoints supported on the platform.
   643         *
   644         *  Power_getNumSetpoints() returns the number of setpoints supported for
   645         *  a specified domain.
   646         *
   647         *  The domain parameter indicates the relevant scaling domain. The
   648         *  domains that can be scaled vary by platform, and are enumerated as
   649         *  Power_Domain.
   650         *
   651         *  @param(domain)  The scaling domain being queried (Power_CPU or
   652         *                  Power_PER)
   653         *
   654         *  @param(numberSetpoints)  Location to write the number of supported
   655         *                  setpoints
   656         *
   657         *  @b(returns)     Power_SOK if the operation succeeded
   658         *
   659         *  @b(returns)     Power_EINVALIDPOINTER if the operation failed because
   660         *                  the numberSetpoints parameter was NULL
   661         *
   662         *  @b(returns)     Power_EINVALIDVALUE if the operation failed because the
   663         *                  domain parameter was invalid
   664         *
   665         *  @b(returns)     Power_EINITFAILURE if there was a previous failure when
   666         *                  V/F scaling support was being initialized; V/F scaling
   667         *                  is unavailable
   668         *
   669         *  @b(returns)     Power_ENOTSUPPORTED if the operation failed because
   670         *                  V/F scaling support is not enabled
   671         *
   672         */
   673        Status getNumSetpoints(Domain domain, UInt * numberSetpoints);
   674    
   675        /*!
   676         *  ======== getSetpointInfo ========
   677         *  Get the frequency and core voltage for a setpoint.
   678         *
   679         *  Power_getSetpointInfo() returns the frequency and voltage for a given
   680         *  setpoint.
   681         *
   682         *  The domain parameter indicates the relevant scaling domain for which
   683         *  the setpoint information is to be retrieved. The domains that can be
   684         *  scaled vary by platform, and are enumerated as Power_Domain.
   685         *
   686         *  @param(domain)  The scaling domain being queried (Power_CPU or
   687         *                  Power_PER)
   688         *
   689         *  @param(setpoint)  The setpoint to be queried
   690         *
   691         *  @param(frequency)  Location to write the frequency (in kHz) of the
   692         *                  specified setpoint
   693         *
   694         *  @param(voltage)  Location to write the voltage (in millivolts) of the
   695         *                  specified setpoint
   696         *
   697         *  @b(returns)     Power_SOK if the operation succeeded
   698         *
   699         *  @b(returns)     Power_EINVALIDPOINTER if the operation failed because
   700         *                  the frequency or votage parameter was NULL
   701         *
   702         *  @b(returns)     Power_EINVALIDVALUE if the operation failed because the
   703         *                  domain parameter was invalid
   704         *
   705         *  @b(returns)     Power_EINITFAILURE if there was a previous failure when
   706         *                  V/F scaling support was being initialized; V/F scaling
   707         *                  is unavailable
   708         *
   709         *  @b(returns)     Power_ENOTSUPPORTED if the operation failed because
   710         *                  V/F scaling support is not enabled
   711         *
   712         *  @b(returns)     Power_EOUTOFRANGE if the operation failed because
   713         *                  the setpoint parameter is out of range of valid
   714         *                  setpoints for the specified domain
   715         */
   716        Status getSetpointInfo(Domain domain, UInt setpoint, UInt *frequency,
   717            UInt *voltage);
   718    
   719        /*!
   720         *  ======== getTransitionLatency ========
   721         *  Get the latency to scale from one setpoint to another setpoint.
   722         *
   723         *  Power_getTransitionLatency() retrieves the latencies (times required)
   724         *  in microseconds to scale from a specific setpoint to another specific
   725         *  setpoint.
   726         *
   727         *  The domain parameter should indicate the relevant scaling domain.
   728         *  The initialSetpoint parameter should specify the setpoint from which the
   729         *  transition would start. The finalSetpoint parameter should specify the
   730         *  setpoint at which the transition would end.
   731         *
   732         *  The frequencyLatency parameter should point to the location where
   733         *  Power_getTransitionLatency() should write the time required to change
   734         *  the frequency from that of the initialSetpoint to that of the
   735         *  finalSetpoint, in microseconds.
   736         *
   737         *  Similarly, the voltageLatency should point to the location where
   738         *  Power_getTransitionLatency() should write the time required to change
   739         *  the voltage from that of the initialSetpoint to that of the
   740         *  finalSetpoint, in microseconds.
   741         *
   742         *  When frequency and voltage are scaled together, the total latency is the
   743         *  sum of the frequency scaling latency and the voltage scaling latency.
   744         *
   745         *  Note that the time required to change a setpoint may not be
   746         *  deterministic (depending upon the hardware characteristics, the
   747         *  underlying software implementation, and the specific V/F swing), but it
   748         *  is bounded by the value returned by Power_getTransitionLatency().
   749         *
   750         *  @param(domain)  The relevant scaling domain (Power_CPU or Power_PER)
   751         *
   752         *  @param(initialSetpoint)  The setpoint to be scaled from
   753         *
   754         *  @param(finalSetpoint)  The setpoint to be scaled to
   755         *
   756         *  @param(frequencyLatency)  Location to write the frequency transition
   757         *                  latency (in microseconds) from that of the
   758         *                  initialSetpoint to that of the finalSetpoint
   759         *
   760         *  @param(voltageLatency)  Location to write the voltage transition
   761         *                  latency (in microseconds) from that of the
   762         *                  initialSetpoint to that of the finalSetpoint
   763         *
   764         *  @b(returns)     Power_SOK if the operation succeeded
   765         *
   766         *  @b(returns)     Power_EFAIL if a general failure occurred
   767         *
   768         *  @b(returns)     Power_EINVALIDPOINTER if the operation failed because
   769         *                  the frequencyLatency or votageLatency parameter was NULL
   770         *
   771         *  @b(returns)     Power_EINVALIDVALUE if the operation failed because the
   772         *                  domain, initialSetpoint, or finalSetpoint value was
   773         *                  invalid
   774         *
   775         *  @b(returns)     Power_EINITFAILURE if there was a previous failure when
   776         *                  V/F scaling support was being initialized; V/F scaling
   777         *                  is unavailable
   778         *
   779         *  @b(returns)     Power_ENOTIMPLEMENTED if the operation failed because
   780         *                  V/F scaling is not supported
   781         */
   782        Status getTransitionLatency(Domain domain, UInt initialSetpoint,
   783            UInt finalSetpoint, UInt *frequencyLatency, UInt *voltageLatency);
   784    
   785        /*!
   786         *  ======== registerConstraint ========
   787         *  Register an operational constraint with Power.
   788         *
   789         *  Before taking certain actions, Power checks to see if the requested
   790         *  action would conflict with a client-registered constraint. If the
   791         *  action does conflict, Power will not proceed with the request.
   792         *  Power_registerConstraint() is the API that allows clients to register
   793         *  their constraints with Power.
   794         *
   795         *  The type parameter identifies the type of constraint being registered.
   796         *  The constraint types vary by platform, and are enumerated as
   797         *  Power_Constraint.  Currently the following are supported:
   798         *
   799         *    Power_DISALLOWEDSLEEPSTATE_MASK  -   Sleep states that should
   800         *        not be activated.
   801         *
   802         *    Power_DISALLOWED_CPU_SETPOINT_MASK  -  CPU setpoints that should not
   803         *        be activated.
   804         *
   805         *    Power_DISALLOWED_PER_SETPOINT_MASK  -  Peripheral setpoints that
   806         *        should not be activated.
   807         *
   808         *  The Power_DISALLOWEDSLEEPSTATE_MASK is a bitmask of the
   809         *  sleep states that can be activated via Power_sleepDSP(). For the
   810         *  TMS320C6748, the states are identified via a combination of the
   811         *  following bitmask values: Power_STANDBY, Power_SLEEP, and
   812         *  Power_DEEPSLEEP.
   813         *
   814         *  The Power_DISALLOWED_CPU_SETPOINT_MASK is a bitmask of
   815         *  setpoints that the CPU should not be transitioned to. For example, if a
   816         *  driver won't operate properly below a specific CPU performance level, it
   817         *  can register the lower performance levels via the setpoint mask.
   818         *  Setpoint IDs are zero-based, with a lower index representing a lower
   819         *  performance level. They are represented right-justified in the bitmask.
   820         *
   821         *  For example, to disallow setpoint "0", the mask is "0x1". To disallow
   822         *  the lowest five setpoints the mask value is "0x1F".
   823         *
   824         *  The Power_DISALLOWED_PER_SETPOINT_MASK performs the
   825         *  same function as the Power_DISALLOWED_CPU_SETPOINT_MASK,
   826         *  but corresponds to scaling of the peripheral domain. The bitmask follows
   827         *  the same format; setpoints are zero-based and have right-justified bit
   828         *  positions, starting with "0x1".
   829         *
   830         *  It is important that clients call Power_unregisterConstraint() when the
   831         *  operational constraint no longer exists. Otherwise, Power may be left
   832         *  unnecessarily restricted from activating power savings.
   833         *
   834         *  @param(type)  Type of constraint
   835         *
   836         *  @param(value)  A constraint type-specific mask
   837         *
   838         *  @param(handle)  Location to write the resulting constraint handle
   839         *                  (which is used for unregistering the constraint)
   840         *
   841         *  @b(returns)     Power_SOK if the operation succeeded
   842         *
   843         *  @b(returns)     Power_EFAIL if the registration failed due to a memory
   844         *                  allocation failure
   845         *
   846         *  @b(returns)     Power_EINVALIDVALUE if the operation failed because
   847         *                  type does not correspond to a supported constraint type
   848         *
   849         *  @b(returns)     Power_EINVALIDPOINTER if the operation failed because
   850         *                  the handle parameter was NULL
   851         *
   852         *  @a(constraints)
   853         *  Power_registerConstraint() cannot be called from a Swi or Hwi, because
   854         *  it allocates memory, and this may incur a context switch.
   855         *
   856         */
   857        Status registerConstraint(Constraint type, UArg value,
   858            ConstraintHandle *handle);
   859    
   860        /*!
   861         *  ======== registerNotify ========
   862         *  Register a function to be called on a specific power event.
   863         *
   864         *  Power_registerNotify() registers a function to be called when a specific
   865         *  Power event occurs. Registrations and the corresponding notifications
   866         *  are processed in first-in-first-out (FIFO) order. The function
   867         *  registered must behave as described below.
   868         *
   869         *  The eventType parameter identifies the type of power event for which the
   870         *  notify function being registered is to be called. The eventType
   871         *  parameter can vary by platform, and is enumerated as Power_Event. For
   872         *  example, on the TMS320C6748 this parameter may have one of the
   873         *  following values:
   874         *
   875         *    Power_PENDING_CPU_SETPOINTCHANGE  -  The CPU domain V/F setpoint is
   876         *        about to change
   877         *
   878         *    Power_DONE_CPU_SETPOINTCHANGE  -  The pending CPU setpoint change has
   879         *        now completed
   880         *
   881         *    Power_PENDING_PER_SETPOINTCHANGE  -  The peripheral domain V/F
   882         *        setpoint is about to change
   883         *
   884         *    Power_DONE_PER_SETPOINTCHANGE  -  The pending peripheral setpoint
   885         *        change has now completed
   886         *
   887         *    Power_GOINGTOSTANDBY  -   The DSP is going to STANDBY state
   888         *
   889         *    Power_AWAKEFROMSTANDBY  -   The DSP has awoken from STANDBY
   890         *
   891         *    Power_GOINGTOSLEEP  -   The DSP is going to SLEEP state
   892         *
   893         *    Power_AWAKEFROMSLEEP  -   The DSP has awoken from SLEEP
   894         *
   895         *    Power_GOINGTODEEPSLEEP  -   The DSP is going to DEEPSLEEP state
   896         *
   897         *    Power_AWAKEFROMDEEPSLEEP  -   The DSP has awoken from DEEPSLEEP
   898         *
   899         *
   900         *  The eventMask parameter is an event-specific mask. Currently the
   901         *  eventMask is not used by Power.
   902         *
   903         *  The notifyFxn parameter specifies the function to call when the
   904         *  specified Power event occurs. The notifyFxn must implement the
   905         *  following signature:
   906         *
   907         *  status = notifyFxn(eventType, eventArg1, eventArg2, clientArg);
   908         *
   909         *  Where: eventType (of type Power_Event) is the type of Power event of
   910         *  the notification; eventArg1 (of type UArg) is an event-specific
   911         *  argument; eventArg2 (of type UArg) is a second event-specific argument;
   912         *  and clientArg (of type UArg) is an abitrary argument.
   913         *
   914         *  Currently, eventArg1 and eventArg2 are used only for V/F scaling events:
   915         *  for a 'pending' setpoint change, eventArg1 holds the current setpoint,
   916         *  and eventArg2 holds the pending setpoint; for a 'done' sepoint change
   917         *  event, eventArg1 holds the previous setpoint, and eventArg2 holds the
   918         *  new setpoint.
   919         *
   920         *  The notification function must return one of the following constants
   921         *  as a status value of type Power_NotifyResponse: Power_NOTIFYDONE if the
   922         *  the client processed the notification function successfully;
   923         *  Power_NOTIFYNOTDONE if the client must wait for interrupt processing
   924         *  to occur before it can proceed (the client must later call the
   925         *  delayedCompletionFxn specified when this function was registered); or
   926         *  Power_NOTIFYERROR if the notification cannot be processed (either an
   927         *  internal client error occurred or the client was notified of an event
   928         *  it could not process).
   929         *
   930         *  The clientArg parameter is an arbitrary argument to be passed to the
   931         *  client upon notification. This argument may allow one notify function
   932         *  to be used by multiple instances of a driver (that is, the clientArg
   933         *  can be used to identify the instance of the driver that is being
   934         *  notified).
   935         *
   936         *  For Power_regsiterNotify(), notifyHandle should point to the location
   937         *  where Power_registerNotify() should write a notification handle. If the
   938         *  application later needs to unregister the notification function, the
   939         *  application should pass this handle to Power_unregisterNotify().
   940         *
   941         *  The delayedCompletionFxn is a pointer to a function provided by the
   942         *  Power module to the client at registration time. If a client cannot act
   943         *  immediately upon notification, its notify function should return
   944         *  Power_NOTIFYNOTDONE. Later, when the action is complete, the
   945         *  client should call the delayedCompletionFxn to signal Power that it has
   946         *  finished. The delayedCompletionFxn is a void function, taking no
   947         *  arguments, and having no return value. If a client can and does act
   948         *  immediately on the notification, it should return Power_NOTIFYDONE in
   949         *  response to notification, and should not call the delayedCompletionFxn.
   950         *
   951         *  For example, if a DMA driver is to prepare for a setpoint change, it may
   952         *  need to wait for the current DMA transfer to complete. When the driver's
   953         *  DMA completes (for example, on the next hardware interrupt), it calls
   954         *  the delayedCompletionFxn function provided when it registered for
   955         *  notification. This completion function tells the Power module that the
   956         *  driver is finished. Meanwhile, the Power module was able to continue
   957         *  notifying other clients, and was waiting for all clients to signal
   958         *  completion.
   959         *
   960         *  @param(eventType)  The type of Power event to be notified of
   961         *
   962         *  @param(eventMask)  A Power event type-specific mask
   963         *
   964         *  @param(notifyFxn)  The function Power should call to notify the client
   965         *                     of the event
   966         *
   967         *  @param(clientArg)  A client-defined argument to pass with the notifyFxn
   968         *                     call
   969         *
   970         *  @param(notifyHandle)  Location to write the resulting notification
   971         *                  handle (which is used for unregistering for the event)
   972         *
   973         *  @param(delayedCompletionFxn) Location for the pointer to the delayed
   974         *                     completion function the client should call if it
   975         *                     requires more time to process an event (the client
   976         *                     calls this function once its processing is complete)
   977         *
   978         *  @b(returns)     Power_SOK if the registration succeeded
   979         *
   980         *  @b(returns)     Power_EFAIL if the registration failed due to a memory
   981         *                  allocation failure
   982         *
   983         *  @b(returns)     Power_EINVALIDPOINTER if the operation failed because
   984         *                  the notifyFxn, notifyHandle, or delayedCompletionFxn
   985         *                  parameter was NULL
   986         *
   987         *  @b(returns)     Power_EINVALIDEVENT if the operation failed because
   988         *                  eventType is invalid
   989         *
   990         *  @a(constraints)
   991         *  Power_registerNotify() cannot be called from a Swi or Hwi, because
   992         *  it allocates memory, and this may incur a context switch.
   993         */
   994        Status registerNotify(Event eventType, UInt eventMask, Fxn notifyFxn,
   995            UArg clientArg, NotifyHandle * notifyHandle, Fxn *delayedCompletionFxn);
   996    
   997        /*!
   998         *  ======== releaseDependency ========
   999         *  Release a dependency that has been previously declared by
  1000         *  Power_setDependency.
  1001         *
  1002         *  This function is the companion to Power_setDependency().  It releases
  1003         *  a resource dependency that was previously set. Resources are enumerated
  1004         *  by Power_Resource.
  1005         *
  1006         *  Power_ETOOMANYCALLS is returned if you call Power_releaseDependency()
  1007         *  when there are no dependencies currently declared for the specified
  1008         *  resource (either because all have been released or because none were
  1009         *  set).
  1010         *
  1011         *  @param(resourceID)  The resource identifier
  1012         *
  1013         *  @b(returns)     Power_SOK if the operation succeeded and the dependency
  1014         *                  has been released
  1015         *
  1016         *  @b(returns)     Power_EFAIL if the operation failed while attempting
  1017         *                  to release the resource
  1018         *
  1019         *  @b(returns)     Power_EINVALIDVALUE if the operation failed because
  1020         *                  Power cannot control this resource
  1021         *
  1022         *  @b(returns)     Power_ENOTSUPPORTED if the operation failed because
  1023         *                  resource tracking is not enabled
  1024         *
  1025         *  @b(returns)     Power_EOUTOFRANGE if the specified resourceID is
  1026         *                  outside the range of valid resource IDs
  1027         *
  1028         *  @b(returns)     Power_ETOOMANYCALLS if a dependency was not previously
  1029         *                  set for the resource, and was therefore not released
  1030         */
  1031        Status releaseDependency(Resource resourceID);
  1032    
  1033        /*!
  1034         *  ======== setDependency ========
  1035         *  Declare a dependency upon a power-manageable resource.
  1036         *
  1037         *  Power_setDependency() declares a dependency upon a resource.  Resources
  1038         *  are enumerated by Power_Resource.
  1039         *
  1040         *  If the resource had been inactive, it will be activated during this
  1041         *  function call.
  1042         *
  1043         *  This function is the companion to Power_releaseDependency().
  1044         *
  1045         *  @param(resourceID)  The resource identifier
  1046         *
  1047         *  @b(returns)     Power_SOK if the operation succeeded and the dependency
  1048         *                  has been set
  1049         *
  1050         *  @b(returns)     Power_EFAIL if the operation failed while attempting
  1051         *                  to activate the resource
  1052         *
  1053         *  @b(returns)     Power_EINVALIDVALUE if the operation failed because
  1054         *                  Power cannot control this resource
  1055         *
  1056         *  @b(returns)     Power_ENOTSUPPORTED if the operation failed because
  1057         *                  resource tracking is not enabled
  1058         *
  1059         *  @b(returns)     Power_EOUTOFRANGE if the specified resourceID is
  1060         *                  outside the range of valid resource IDs
  1061         */
  1062        Status setDependency(Resource resourceID);
  1063    
  1064        /*!
  1065         *  ======== signalEvent ========
  1066         *  Signal a Power event to registered clients.
  1067         *
  1068         *  Power_signalEvent() provides a mechanism for an application to signal
  1069         *  Power events. Power_signalEvent() only signals the event occurrence; it
  1070         *  does not implement the actual processing associated with the Power
  1071         *  event.
  1072         *
  1073         *  For example, on a platform where V/F scaling is accomplished on a
  1074         *  separate processor, Power_signalEvent() can be called by the DSP
  1075         *  application before the scaling to notify registered clients on this
  1076         *  processor of the pending setpoint change event. Similarly, after the
  1077         *  scaling, Power_signalEvent() can be called to signal the done setpoint
  1078         *  change event. Here Power is not orchestrating the change to the
  1079         *  V/F setpoint, but its registration, notification, and signaling
  1080         *  capabilities allow synchronization between scaling by the other
  1081         *  processor and the affected software on this processor.
  1082         *
  1083         *  The parameters eventArg1 and eventArg2 should correspond to the type
  1084         *  of event being signaled.  For example, for a pending setpoint
  1085         *  change event, the current and pending setpoints should be specified as
  1086         *  eventArg1 and eventArg2.
  1087         *
  1088         *  The notifyTimeout parameter is the maximum amount of time (in system
  1089         *  Clock ticks) to wait for all registered notification functions (set by
  1090         *  Power_registerNotify()) to respond to a delayed completion, before
  1091         *  declaring failure and returning Power_ETIMEOUT.
  1092         *
  1093         *  Power_signalEvent() is intended only for signaling power events that are
  1094         *  outside the full control of the Power implementation on the current
  1095         *  processor. It can be used for V/F scaling notification as described
  1096         *  avove when Power does not implement the actual scaling. For events where
  1097         *  Power does orchestrate the processing, for example, on platforms
  1098         *  where Power performs the actual V/F scaling, or activates a processor
  1099         *  sleep mode, Power handles the notifications automatically, and
  1100         *  Power_signalEvent() must not be used for these events. In other words,
  1101         *  Power_signalEvent() only validates that the indicated eventType is
  1102         *  within the range of valid events for the platform; it does not validate
  1103         *  whether it makes sense for the application to trigger the signaling of
  1104         *  the indicated event, and it does not implement the actual power
  1105         *  transition indicated by the event.
  1106         *
  1107         *  @param(eventType)  The Power event to be signaled
  1108         *
  1109         *  @param(eventArg1)  The event-specific first argument
  1110         *
  1111         *  @param(eventArg2)  The event-specific second argument
  1112         *
  1113         *  @param(notifyTimeout)  The maximum time (in Clock ticks) to wait for
  1114         *                  client notifications to complete
  1115         *
  1116         *  @b(returns)     Power_SOK if the operation succeeded
  1117         *
  1118         *  @b(returns)     Power_EFAIL if a notification failure occurred
  1119         *
  1120         *  @b(returns)     Power_EINVALIDEVENT if the operation failed because
  1121         *                  eventType is invalid
  1122         *
  1123         *  @b(returns)     Power_ETIMEOUT if the operation failed because
  1124         *                  a registered notification client did not complete its
  1125         *                  processing within the specified notifyTimeout
  1126         *
  1127         *  @a(constraints)
  1128         *  Power_signalEvent can be called from a Hwi or Swi only if notifyTimeout
  1129         *  is zero
  1130         */
  1131        Status signalEvent(Event eventType, UArg eventArg1, UArg eventArg2,
  1132            UInt notifyTimeout);
  1133    
  1134        /*!
  1135         *  ======== sleepDSP ========
  1136         *  Put the DSP into a sleep state.
  1137         *
  1138         *  Power_sleepDSP() transitions the DSP to a new sleep state.  A successful
  1139         *  call to Power_sleepDSP() returns when the DSP has awoken from the
  1140         *  specified sleep state.
  1141         *
  1142         *  The sleepCode parameter indicates the new sleep state for the DSP. The
  1143         *  sleep states supported by Power usually vary by device.  For example,
  1144         *  the following constants may be used to activate sleep states on the
  1145         *  TMS320C6748:
  1146         *
  1147         *    Power_STANDBY  -  The GEM is put into a power-saving standby mode,
  1148         *    with its clock turned off at the GEM boundary. This mode has a low
  1149         *    latency for wakeup.
  1150         *
  1151         *    Power_SLEEP  -  In addition to putting the GEM into standby, the core
  1152         *    voltage is reduced, and the PLLs are slowed down or bypassed.
  1153         *
  1154         *    Power_DEEPSLEEP  -  In addition to the actions for Power_SLEEP, the
  1155         *    GEM clock is gated up-stream at the power sleep controller, memories
  1156         *    are put into retention, and PLLs are powered down.
  1157         *
  1158         *  The sleepArg parameter is a sleepCode-specific argument. For example,
  1159         *  for the TMS320C6748, this parameter is not used for Power_STANDBY,
  1160         *  but is used for Power_SLEEP and Power_DEEPSLEEP (see below).
  1161         *
  1162         *  For Power_SLEEP: the sleepArg can be used to override Power's
  1163         *  default behavior. If sleepArg is NULL, then Power reduces the core
  1164         *  voltage to 1.0 volts during sleep, and bypasses both PLLs. If sleepArg
  1165         *  is non-NULL, it is interpreted as a pointer to a {@link #SleepOverride}
  1166         *  structure. In this structure, the sleepVoltage is in millivolts, and
  1167         *  must correspond to a voltage level defined by the scaling configuration
  1168         *  library. The bypassedPLLs value is treated as a bitmask to indicate
  1169         *  which PLLs get bypassed during sleep: Power_PLL0 and/or Power_PLL1.
  1170         *  This override mechanism can be used to ensure operation within the
  1171         *  TMS320C6748 device constraints. For example, if the minimum supported
  1172         *  voltage when DDR2 is used is 1.1 volts, and no DDR2 accesses can be
  1173         *  made when PLL1 is bypassed. These constraints could be violated in some
  1174         *  use cases, for example, when DDR2 memory is used, and there is a
  1175         *  possibility that the wakeup interrupt service routine triggers some
  1176         *  off-chip code or data accesses. The override mechanism allows the sleep
  1177         *  voltage to be increased to 1.1 volts and PLL1 to not be bypassed during
  1178         *  sleep.
  1179         *
  1180         *  For Power_DEEPSLEEP: sleepArg defines the DEEPSLEEP signal source that
  1181         *  Power should configure for wakeup. This must be either Power_RTC_ALARM
  1182         *  or Power_EXTERNAL.
  1183         *
  1184         *  The notifyTimeout parameter is the maximum amount of time (in system
  1185         *  Clock ticks) to wait for registered notification functions (set by
  1186         *  Power_registerNotify()) to respond to a delayed completion, before
  1187         *  declaring failure and returning Power_ETIMEOUT. If the notifyTimeout
  1188         *  parameter is zero, then all notification functions must return
  1189         *  Power_NOTIFYDONE-they cannot request a delayed completion. If a
  1190         *  notification function does not return, the system will hang. The
  1191         *  notifyTimeout is not used to abandon a notification function; rather it
  1192         *  indicates the amount of time Power_sleepDSP waits for all delayed
  1193         *  completion requests to complete. The wait-loop is entered after all
  1194         *  notification functions have been invoked.
  1195         *
  1196         *  The application should treat return values of Power_ETIMEOUT or
  1197         *  Power_EFAIL as critical system failures. These values indicate the
  1198         *  notification client is unresponsive, and the system is in an unknown
  1199         *  state.
  1200         *
  1201         *  Due to the critical system nature of sleep commands, clients that
  1202         *  register for sleep notification should make every effort to respond
  1203         *  immediately to the sleep event.
  1204         *
  1205         *  @param(sleepCode)  The sleep state for the DSP
  1206         *
  1207         *  @param(sleepArg)  A sleepCode-specific argument structure (see below)
  1208         *
  1209         *  @param(notifyTimeout)  The maximum time (in Clock ticks) to wait for
  1210         *                  client notifications to complete
  1211         *
  1212         *  @b(returns)     Power_SOK if the operation succeeded and a successful
  1213         *                  sleep and wake occurred
  1214         *
  1215         *  @b(returns)     Power_EFAIL if a general failure occurred and the DSP
  1216         *                  could not be put to sleep
  1217         *
  1218         *  @b(returns)     Power_ENOTIMPLEMENTED if the requested sleep state
  1219         *                  is not implemented on this platform
  1220         *
  1221         *  @b(returns)     Power_ETIMEOUT if the operation failed because
  1222         *                  a registered notification function did not complete its
  1223         *                  (delayed completion) processing within the specified
  1224         *                  notifyTimeout
  1225         *
  1226         *  @b(returns)     Power_EBUSY if the operation failed because Power
  1227         *                  is still busy processing a previous request
  1228         *
  1229         *  @a(constraints)
  1230         *  Power_sleepDSP() cannot be called from an Hwi
  1231         *
  1232         *  Power_sleepDSP() cannot be called from a program's main() function
  1233         *
  1234         *  Power_sleepDSP() can be called from a Swi only if notifyTimeout is 0
  1235         *
  1236         *  For Power_SLEEP: no DDR memory accesses (code, data, or stack) can
  1237         *  occur while the PLL1 is bypassed, otherwise DDR corruption may occur
  1238         *
  1239         *  For Power_SLEEP: if DDR2 memories are used, then no DDR2 accesses can
  1240         *  occur with a sleep voltage of 1.0 volts, otherwise DDR2 corruption
  1241         *  may occur
  1242         *
  1243         *  For Power_DEEPSLEEP: this state must be invoked from an on-chip
  1244         *  context; no code, data, or stack access can occur during
  1245         *  Power_sleepDSP, otherwise DDR corruption may occur
  1246         */
  1247        Status sleepDSP(UInt sleepCode, UInt sleepArg, UInt notifyTimeout);
  1248    
  1249        /*!
  1250         *  ======== unregisterConstraint ========
  1251         *  Unregister a constraint that was previously registered with Power.
  1252         *
  1253         *  Power_unregisterConstraint() unregisters a constraint that was
  1254         *  registered with Power_registerConstraint(). For example, when a device
  1255         *  driver is closed, any constraints it registered with Power must be
  1256         *  unregistered with this function, otherwise Power may be left
  1257         *  unnecessarily restricted from activating power savings.
  1258         *
  1259         *  The handle parameter is the handle that was provided by
  1260         *  Power_registerConstraint() when the constraint was registered.
  1261         *
  1262         *  @param(handle)  The handle to the previously-registered constraint
  1263         *
  1264         *  @b(returns)     Power_SOK if the operation succeeded
  1265         *
  1266         *  @b(returns)     Power_EINVALIDHANDLE if the operation failed because
  1267         *                  handle is invalid
  1268         *
  1269         *  @a(constraints)
  1270         *  This function cannot be called from a program's main() function.
  1271         */
  1272        Status unregisterConstraint(ConstraintHandle handle);
  1273    
  1274        /*!
  1275         *  ======== unregisterNotify ========
  1276         *  Unregister for a Power event notification.
  1277         *
  1278         *  Power_unregisterNotify() unregisters an event notification that was
  1279         *  registered with Power_registerNotify(). For example, when an audio codec
  1280         *  device is closed, and it no longer needs event notifications, it must
  1281         *  unregister by calling this function.
  1282         *
  1283         *  The notifyHandle parameter is the handle that was provided by
  1284         *  Power_registerNotify() when registering for an event notification.
  1285         *
  1286         *  @param(notifyHandle)  The event notification handle
  1287         *
  1288         *  @b(returns)     Power_SOK if the operation succeeded
  1289         *
  1290         *  @b(returns)     Power_EINVALIDHANDLE if the operation failed because
  1291         *                  notifyHandle is invalid
  1292         *
  1293         *  @a(constraints)
  1294         *  This function cannot be called from a program's main() function.
  1295         */
  1296        Status unregisterNotify(NotifyHandle notifyHandle);
  1297    
  1298        /*! @_nodoc */
  1299        @XmlDtd
  1300        metaonly struct ModuleView {
  1301            UInt      setpointCPU;
  1302            UInt      setpointPER;
  1303            String    maskDisallowedSetpointsCPU;
  1304            String    maskDisallowedSetpointsPER;
  1305            String    maskDisallowedSleepModes;
  1306        };
  1307    
  1308        /*! @_nodoc */
  1309        @Facet
  1310        metaonly config ViewInfo.Instance rovViewInfo =
  1311            ViewInfo.create({
  1312                viewMap: [
  1313                [
  1314                    'Module',
  1315                    {
  1316                        type: ViewInfo.MODULE,
  1317                        viewInitFxn: 'viewInitModule',
  1318                        structName: 'ModuleView'
  1319                    }
  1320                ],
  1321                ]
  1322            });
  1323    
  1324    internal:
  1325    
  1326        config UInt CAPSMASK;
  1327    
  1328        /* Internal constants */
  1329        const UInt CWAITFORV     = 0x20;
  1330        const UInt CSCALEVWITHF  = 0x10;
  1331        const UInt CMOVEINITSPS  = 0x1000;
  1332    
  1333        const UInt RELEASE = 0;
  1334        const UInt SET = 1;
  1335        const UInt QUERY = 2;
  1336    
  1337        enum SigType {
  1338            SigType_INTERNAL = 0,
  1339            SigType_EXTERNAL
  1340        };
  1341    
  1342        /*
  1343         *  ======== delayCompletion0 ========
  1344         */
  1345        Void delayCompletion0();
  1346    
  1347        /*
  1348         *  ======== delayCompletion1 ========
  1349         */
  1350        Void delayCompletion1();
  1351    
  1352        /*
  1353         *  ======== delayCompletion2 ========
  1354         */
  1355        Void delayCompletion2();
  1356    
  1357        /*
  1358         *  ======== delayCompletion3 ========
  1359         */
  1360        Void delayCompletion3();
  1361    
  1362        /*
  1363         *  ======== delayCompletion4 ========
  1364         */
  1365        Void delayCompletion4();
  1366    
  1367        /*
  1368         *  ======== delayCompletion5 ========
  1369         */
  1370        Void delayCompletion5();
  1371    
  1372        /*
  1373         *  ======== delayCompletion6 ========
  1374         */
  1375        Void delayCompletion6();
  1376    
  1377        /*
  1378         *  ======== delayCompletion7 ========
  1379         */
  1380        Void delayCompletion7();
  1381    
  1382        /*
  1383         *  ======== delayCompletion8 ========
  1384         */
  1385        Void delayCompletion8();
  1386    
  1387        /*
  1388         *  ======== delayCompletion9 ========
  1389         */
  1390        Void delayCompletion9();
  1391    
  1392        /*
  1393         *  ======== idleStopClock ========
  1394         */
  1395        Void idleStopClock();
  1396    
  1397        /*
  1398         *  ======== init ========
  1399         */
  1400        Void init();
  1401    
  1402        /*
  1403         *  ======== initRefCounts ========
  1404         */
  1405        Void initRefCounts();
  1406    
  1407        /*
  1408         *  ======== notify ========
  1409         */
  1410        Status notify(Event eventType, UInt timeout, SigType sigType,
  1411            UArg extArg1, UArg extArg2);
  1412    
  1413        /*
  1414         *  ======== rebuildConstraint ========
  1415         */
  1416        Void rebuildConstraint(Constraint type);
  1417    
  1418        /*
  1419         *  ======== updateConstraints ========
  1420         */
  1421        Void updateConstraints(Constraint type, UArg value);
  1422    
  1423        /*
  1424         *  ======== Module_State ========
  1425         */
  1426        struct Module_State {
  1427            UInt32 currentSetpointCPU;        /* current CPU domain setpoint */
  1428            UInt32 currentSetpointPER;        /* current PER domain setpoint */
  1429            UInt32 disallowedSetpointsCPU;    /* disallowed CPU domain setpoints */
  1430            UInt32 disallowedSetpointsPER;    /* disallowed PER domain setpoints */
  1431            UInt32 disallowedSleepModes;      /* disallowed CPU sleep modes */
  1432            Queue.Object constraintsQ;        /* queue for registered constraints */
  1433            Queue.Object notifyQ[];           /* event notification queues */
  1434            UInt32 nextSP;                    /* destination CPU setpoint */
  1435            UInt32 previousSP;                /* previous CPU setpoint */
  1436            UInt32 nextSPPER;                 /* destination PER setpoint */
  1437            UInt32 previousSPPER;             /* previous PER setpoint */
  1438            UInt32 numSPCPU;                  /* number of CPU domain setpoints */
  1439            UInt32 numSPPER;                  /* number of PER domain setpoints */
  1440            Config currentConfig;             /* current configuration flags */
  1441            Bool PSCLinitOK;                  /* PSCL initialized OK? */
  1442            Bool busy;                        /* Power is busy with previous cmd? */
  1443        }
  1444    }
  1445