1 /* 2 * Copyright (c) 2015-2019, 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 * @file Power.h 34 * @brief Power Manager 35 * 36 * @anchor ti_drivers_Power_Overview 37 * # Overview 38 * 39 * The Power Manager facilitates the transition of the MCU from active states 40 * to sleep states and vice versa. It provides other drivers the 41 * ability to set and release dependencies on hardware resources, and keeps 42 * reference counts on each resource to know when to enable or disable the 43 * resource. It provides drivers the ability to register callback functions 44 * to be invoked upon specific power events. In addition, drivers and 45 * applications can set or release constraints to prevent the MCU from 46 * transitioning into specific active or sleep states. Refer to the device 47 * specific power driver header file device specific information. 48 * 49 * <hr> 50 * @anchor ti_drivers_Power_Usage 51 * # Usage 52 * 53 * This documentation provides a basic @ref ti_drivers_Power_Synopsis 54 * "usage summary" and a set of @ref ti_drivers_Power_Examples "examples" 55 * in the form of commented code fragments. Detailed descriptions of the 56 * APIs are provided in subsequent sections. 57 * @anchor ti_drivers_Power_Synopsis 58 * ## Synopsis 59 * @anchor ti_drivers_Power_Synopsis_Code 60 * 61 * @note <b> The following example demonstrates usage of some of the Power 62 * driver APIs.This example is intended for reference only and is not intended 63 * for application use. You should refer to the device specific Power driver 64 * header for valid API usage and arguments. </b> 65 * 66 * 67 * @code 68 * // Import Power Driver definitions 69 * #include <ti/drivers/Power.h> 70 * 71 * // One-time initialization of Power manager 72 * Power_init(); 73 * 74 * // Set power dependency on a resource 75 * status = Power_setDependency(resourceId); 76 * if (status != Power_SOK) { 77 * // Error occurred 78 * } 79 * 80 * // Set a power constraint 81 * status = Power_setConstraint(constraintId); 82 * if (status != Power_SOK) { 83 * // Error occurred 84 * } 85 * 86 * // Other application code 87 * 88 * // Release a previously set power constraint 89 * status = Power_releaseConstraint(constraintId); 90 * if (status != Power_SOK) { 91 * // Error occurred 92 * } 93 * 94 * status = Power_releaseDependency(resourceId); 95 * if (status != Power_SOK) { 96 * // Error occurred 97 * } 98 * @endcode 99 * 100 * 101 * <hr> 102 * @anchor ti_drivers_Power_Examples 103 * # Examples 104 * 105 * @note 106 * <b>The following examples are intended for reference only and are not 107 * intended for application use. You should refer to the device specific 108 * Power driver header file for more usage information.</b> 109 * 110 * @li @ref ti_drivers_Power_Examples_enable "Enabling power policy" 111 * @li @ref ti_drivers_Power_Examples_disable "Disabling power policy" 112 * @li @ref ti_drivers_Power_Examples_constraint "Using power constraints" 113 * @li @ref ti_drivers_Power_Examples_dependency "Using power dependency" 114 * @li @ref ti_drivers_Power_Examples_notify "Using power notify" 115 * @li @ref ti_drivers_Power_Examples_transistion "Power transitions" 116 * 117 * 118 * @anchor ti_drivers_Power_Examples_enable 119 * ## Enabling Power Policy 120 * 121 * @code 122 * // Import Power Driver definitions 123 * #include <ti/drivers/Power.h> 124 * 125 * // One-time initialization of Power manager 126 * Power_init(); 127 * 128 * // Enable power policy 129 * Power_enablePolicy(); 130 * @endcode 131 * 132 * 133 * @anchor ti_drivers_Power_Examples_disable 134 * ## Disabling Power Policy 135 * 136 * @code 137 * // Import Power Driver definitions 138 * #include <ti/drivers/Power.h> 139 * 140 * bool flag; 141 * 142 * // One-time initialization of Power manager 143 * Power_init(); 144 * 145 * // Disable power policy 146 * flag = Power_disablePolicy(); 147 * if (flag == false) { 148 * // Power policy was already disabled 149 * } 150 * @endcode 151 * 152 * 153 * @anchor ti_drivers_Power_Examples_constraint 154 * ## Using Power Constraints 155 * 156 * @code 157 * // Import Power Driver definitions 158 * #include <ti/drivers/Power.h> 159 * 160 * uint32_t mask; 161 * int16_t status; 162 * 163 * // One-time initialization of Power manager 164 * Power_init(); 165 * 166 * // Set a power constraint 167 * status = Power_setConstraint(constraintId); 168 * if (status != Power_SOK) { 169 * // Error occurred setting constraint 170 * } 171 * 172 * // Read mask of currently set power constraints 173 * mask = Power_getConstraintMask(); 174 * 175 * // Release previously set constraint 176 * status = Power_releaseConstraint(constraintId); 177 * if (status != Power_SOK) { 178 * // Error occurred releasing constraint 179 * } 180 * @endcode 181 * 182 * 183 * @anchor ti_drivers_Power_Examples_dependency 184 * ## Using Power Dependency 185 * 186 * @code 187 * // Import Power Driver definitions 188 * #include <ti/drivers/Power.h> 189 * 190 * int16_t count; 191 * int16_t status; 192 * 193 * // One-time initialization of Power manager 194 * Power_init(); 195 * 196 * // Set a power dependency 197 * status = Power_setDependency(resourceId); 198 * if (status != Power_SOK) { 199 * // Error occurred setting dependency 200 * } 201 * 202 * // Get the dependency count of the resource 203 * count = Power_getDependencyCount(resourceId); 204 * if (count == Power_EINVALIDINPUT) { 205 * // Invalid resourceId used 206 * } 207 * 208 * if (count > 0) { 209 * // At least 1 dependency exists for the resource. 210 * // Regardless, we may safely release the dependency when we 211 * // no longer need the resource. 212 * } 213 * 214 * // Release a power dependency 215 * status = Power_releaseDependency(resourceId); 216 * if (status != Power_SOK) { 217 * // Error occurred releasing dependency 218 * } 219 * @endcode 220 * 221 * 222 * @anchor ti_drivers_Power_Examples_notify 223 * ## Using Power Notify 224 * 225 * The application must define a #Power_NotifyFxn function and 226 * allocate memory for the #Power_NotifyObj object. 227 * 228 * @code 229 * // Import Power Driver definitions 230 * #include <ti/drivers/Power.h> 231 * 232 * // Application Power_NotifyObj object 233 * Power_NotifyObj powerNotifyObj; 234 * 235 * // Application Power_NotifyFxn function prototype 236 * static int postNotifyFxn(unsigned int eventType, uintptr_t eventArg, 237 * uintptr_t clientArg); 238 * @endcode 239 * 240 * The application must register for the event. Here, we use pseudo event 241 * names. You should refer to the device specific power driver header file 242 * for eventTypes. Inside the infinite loop, we wait for a semaphore to be 243 * post from our notification callback. 244 * 245 * @code 246 * // Application thread 247 * void thread(void) 248 * { 249 * int16_t status; 250 * unsigned int eventTypes = LOW_POWER_EXIT | LOW_POWER_ENTER; 251 * uintptr_t clientArg = semaphoreHandle; 252 * 253 * status = Power_registerNotify(&powerNotifyObj, eventTypes, 254 * postNotifyFxn, clientArg); 255 * 256 * while (1) 257 * { 258 * sem_wait(semaphoreHandle); 259 * // Do something 260 * 261 * // Unregister for the notification. After this call, 262 * // our postNotifyFxn() will never be called again unless 263 * // we use Power_registerNotify() again. 264 * Power_unregisterNotify(&powerNotifyObj); 265 * 266 * break; 267 * } 268 * } 269 * @endcode 270 * 271 * The application may implement the power notify function to fit their 272 * needs. The #Power_NotifyFxn should always return #Power_NOTIFYDONE or 273 * #Power_NOTIFYERROR. 274 * 275 * @code 276 * // Application Power_NotifyFxn function implementation 277 * static int postNotifyFxn(unsigned int eventType, uintptr_t eventArg, 278 * uintptr_t clientArg) 279 * { 280 * sem_t semaphoreHandle = (sem_t) clientArg; 281 * 282 * if (eventType == LOW_POWER_EXIT) { 283 * sem_post(semaphoreHandle); 284 * return (Power_NOTIFYDONE); 285 * } 286 * 287 * if (eventType == LOW_POWER_ENTER) { 288 * // Store something in RAM 289 * return (Power_NOTIFYDONE); 290 * } 291 * 292 * // We received an unexpected event type 293 * return (Power_NOTIFYERROR); 294 * } 295 * @endcode 296 * 297 * 298 * @anchor ti_drivers_Power_Examples_transistion 299 * ## Power transitions 300 * 301 * @code 302 * // Import Power Driver definitions 303 * #include <ti/drivers/Power.h> 304 * 305 * uint32_t totalLatency, resumeLatency; 306 * int16_t status; 307 * 308 * // One-time initialization of Power manager 309 * Power_init(); 310 * 311 * // Get the current power transition state 312 * status = Power_getTransitionState(); 313 * 314 * switch (status) 315 * { 316 * case Power_ACTIVE: 317 * // No transitions in progress 318 * break; 319 * case Power_ENTERING_SLEEP: 320 * // Transition to sleep in progress 321 * break; 322 * case Power_EXITING_SLEEP: 323 * // Transition from sleep in progress 324 * break; 325 * case Power_CHANGING_PERF_LEVEL: 326 * // Performance level change in progress 327 * break; 328 * } 329 * 330 * // Get the Power_TOTAL and Power_RESUME transition latency for a 331 * // device specific sleepState. Latency is in microseconds. 332 * totalLatency = Power_getTransitionLatency(sleepState, Power_TOTAL); 333 * resumeLatency = Power_getTransitionLatency(sleepState, Power_RESUME); 334 * @endcode 335 * 336 * 337 * <hr> 338 * @anchor ti_drivers_Power_Configuration 339 * # Configuration 340 * 341 * @note The Power Manager APIs and configuration parameters are described here. 342 * For a detailed description of terms and concepts, and usage by different 343 * types of software components (peripheral drivers, power policies, 344 * and applications) please see the 345 * <a href='../../Power_Management.pdf'>SimpleLink SDK Power Management User's Guide</a>. 346 * <hr> 347 ****************************************************************************** 348 */ 349 350 #ifndef ti_drivers_Power__include 351 #define ti_drivers_Power__include 352 353 /* @cond */ 354 #include <stdbool.h> 355 #include <stdint.h> 356 /* @endcond */ 357 358 #include <ti/drivers/utils/List.h> 359 360 #ifdef __cplusplus 361 extern "C" { 362 #endif 363 364 /*! @addtogroup Power_Latency_Type 365 * @{ 366 */ 367 #define Power_TOTAL (1U) /*!< total latency */ 368 #define Power_RESUME (2U) /*!< resume latency */ 369 /*! @}*/ 370 371 /*! @addtogroup Power_Notify_Response 372 * @{ 373 */ 374 #define Power_NOTIFYDONE (0) /*!< OK, notify completed */ 375 #define Power_NOTIFYERROR (-1) /*!< an error occurred during notify */ 376 /*! @}*/ 377 378 /*! @addtogroup Power_Status 379 * @{ 380 */ 381 #define Power_SOK (0) /*!< OK, operation succeeded */ 382 #define Power_EFAIL (-1) /*!< general failure */ 383 #define Power_EINVALIDINPUT (-2) /*!< invalid data value */ 384 #define Power_EINVALIDPOINTER (-3) /*!< invalid pointer */ 385 #define Power_ECHANGE_NOT_ALLOWED (-4) /*!< change is not allowed */ 386 #define Power_EBUSY (-5) /*!< busy with another transition */ 387 /*! @}*/ 388 389 /*! @addtogroup Power_Transition_State 390 * @{ 391 */ 392 #define Power_ACTIVE (1U) /*!< normal active state */ 393 #define Power_ENTERING_SLEEP (2U) /*!< entering a sleep state */ 394 #define Power_EXITING_SLEEP (3U) /*!< exiting a sleep state */ 395 #define Power_ENTERING_SHUTDOWN (4U) /*!< entering a shutdown state */ 396 #define Power_CHANGING_PERF_LEVEL (5U) /*!< moving to new performance level */ 397 /*! @}*/ 398 399 /*! 400 * @brief Power policy initialization function pointer 401 */ 402 typedef void (*Power_PolicyInitFxn)(void); 403 404 /*! 405 * @brief Power policy function pointer 406 */ 407 typedef void (*Power_PolicyFxn)(void); 408 409 /*! 410 * @brief Power notify callback function used with the 411 * Power_registerNotify() 412 * 413 * @param[in] eventType The eventTypes parameter identifies the type of 414 * power event for which the notify callback function was called. 415 * 416 * @param[in] eventArg An optional @p eventType specific argument. 417 * 418 * @param[in] clientArg Pointer to a custom argument. 419 * 420 * @retval #Power_NOTIFYDONE if the client processed the notification 421 * successfully 422 * 423 * @retval #Power_NOTIFYERROR if an error occurred during notification. 424 * 425 * @sa Power_registerNotify() 426 * @sa Power_unregisterNotify() 427 * @sa Power_NotifyObj 428 * @sa @ref ti_drivers_Power_Examples_notify "Using power notify" 429 */ 430 typedef int_fast16_t (*Power_NotifyFxn)(uint_fast16_t eventType, 431 uintptr_t eventArg, uintptr_t clientArg); 432 433 /*! 434 * @brief Power notify object structure. 435 * 436 * This structure specification is for internal use. Notification clients must 437 * pre-allocate a notify object when registering for a notification; 438 * Power_registerNotify() will take care initializing the internal elements 439 * appropriately. 440 * 441 * @sa @ref ti_drivers_Power_Examples_notify "Using power notify" 442 */ 443 typedef struct { 444 List_Elem link; /*!< for placing on the notify list */ 445 uint_fast16_t eventTypes; /*!< the event type */ 446 Power_NotifyFxn notifyFxn; /*!< notification function */ 447 uintptr_t clientArg; /*!< argument provided by client */ 448 } Power_NotifyObj; 449 450 /*! 451 * @brief Disable the configured power policy from running when the CPU is 452 * idle 453 * 454 * Calling this function clears the flag that controls whether the configured 455 * power policy function is invoked on each pass through the Idle loop. 456 * This function call will override both a 'true' setting of the 457 * "enablePolicy" setting in the Power Manager configuration object, as well 458 * as a previous runtime call to the Power_enablePolicy() function. 459 * 460 * @return The old value of "enablePolicy". 461 * 462 * @sa Power_enablePolicy() 463 * @sa @ref ti_drivers_Power_Examples_enable "Enabling power policy" 464 * @sa @ref ti_drivers_Power_Examples_disable "Disabling power policy" 465 */ 466 bool Power_disablePolicy(void); 467 468 /*! 469 * @brief Enable the configured power policy to run when the CPU is idle 470 * 471 * Calling this function sets a flag that will cause the configured power 472 * policy function to be invoked on each pass through the Idle loop. This 473 * function call will override both a 'false' setting of the "enablePolicy" 474 * setting in the Power Manager configuration object, as well as a previous 475 * runtime call to the Power_disablePolicy() function. 476 * 477 * For some processor families, automatic power transitions can make initial 478 * application development more difficult, as well as being at odds with 479 * basic debugger operation. This convenience function allows an application 480 * to be initially configured, built, and debugged, without automatic power 481 * transitions during idle time. When the application is found to be working, 482 * this function can be called (typically in main()) to enable the policy 483 * to run, without having to change the application configuration. 484 * 485 * @sa Power_disablePolicy() 486 * @sa @ref ti_drivers_Power_Examples_enable "Enabling power policy" 487 * @sa @ref ti_drivers_Power_Examples_disable "Disabling power policy" 488 */ 489 void Power_enablePolicy(void); 490 491 /*! 492 * @brief Get the constraints that have been declared with Power 493 * 494 * This function returns a bitmask indicating the constraints that are 495 * currently declared to the Power Manager (via previous calls to 496 * Power_setConstraint()). For each constraint that is currently declared, 497 * the corresponding bit in the bitmask will be set. For example, if two 498 * clients have independently declared two different constraints, the returned 499 * bitmask will have two bits set. 500 * 501 * Constraint identifiers are device specific, and defined in the 502 * device-specific Power include file. For example, the constraints for 503 * MSP432 are defined in PowerMSP432.h. The corresponding bit in the 504 * bitmask returned by this function can be derived by a left-shift using 505 * the constraint identifier. For example, for MSP432, for the corresponding 506 * bit for the PowerMSP432_DISALLOW_SLEEP constraint, the bit position is 507 * determined by the operation: (1 << PowerMSP432_DISALLOW_SLEEP) 508 * 509 * @return A bitmask of the currently declared constraints. 510 * 511 * @sa Power_setConstraint() 512 * @sa @ref ti_drivers_Power_Examples_constraint "Using power constraints" 513 */ 514 uint_fast32_t Power_getConstraintMask(void); 515 516 /*! 517 * @brief Get the current dependency count for a resource 518 * 519 * This function returns the number of dependencies that are currently 520 * declared upon a resource. 521 * 522 * Resource identifiers are device specific, and defined in the 523 * device-specific Power include file. For example, the resources for 524 * CC32XX are defined in PowerCC32XX.h. 525 * 526 * @param[in] resourceId resource id 527 * 528 * @return The number of dependencies declared for the resource. 529 * 530 * @retval #Power_EINVALIDINPUT if the @p resourceId is invalid or this 531 * function is not supported by the device specific implementation. 532 * 533 * @sa Power_setDependency() 534 * @sa @ref ti_drivers_Power_Examples_dependency "Using power dependency" 535 */ 536 int_fast16_t Power_getDependencyCount(uint_fast16_t resourceId); 537 538 /*! 539 * @brief Get the current performance level 540 * 541 * This function returns the current device performance level in effect. 542 * 543 * If performance scaling is not supported for the device, this function 544 * will always indicate a performance level of zero. 545 * 546 * @return The current performance level. 547 * 548 * @sa Power_setPerformanceLevel() 549 */ 550 uint_fast16_t Power_getPerformanceLevel(void); 551 552 /*! 553 * @brief Get the hardware transition latency for a sleep state 554 * 555 * This function reports the minimal hardware transition latency for a specific 556 * sleep state. The reported latency is that for a direct transition, and does 557 * not include any additional latency that might occur due to software-based 558 * notifications. 559 * 560 * Sleep states are device specific, and defined in the device-specific Power 561 * include file. For example, the sleep states for CC32XX are defined in 562 * PowerCC32XX.h. 563 * 564 * This function is typically called by the power policy function. The latency 565 * is reported in units of microseconds. 566 * 567 * @param[in] sleepState the sleep state 568 * 569 * @param[in] type @ref Power_Latency_Type (#Power_TOTAL or #Power_RESUME) 570 * 571 * @return The latency value, in units of microseconds. 572 * 573 * @sa @ref ti_drivers_Power_Examples_transistion "Power transitions" 574 */ 575 uint_fast32_t Power_getTransitionLatency(uint_fast16_t sleepState, 576 uint_fast16_t type); 577 578 /*! 579 * @brief Get the current transition state of the Power Manager 580 * 581 * @return The current @ref Power_Transition_State. 582 * 583 * @retval #Power_ACTIVE returned when no transitions are in progress. 584 * 585 * @retval #Power_ENTERING_SLEEP returned during the transition to 586 * sleep, before sleep has occurred. 587 * 588 * @retval #Power_EXITING_SLEEP returned after wakeup, as the device is 589 * being transitioned back to #Power_ACTIVE. 590 * 591 * @retval #Power_CHANGING_PERF_LEVEL returned when a change is being made 592 * to the performance level. 593 * 594 * @sa @ref ti_drivers_Power_Examples_transistion "Power transitions" 595 */ 596 uint_fast16_t Power_getTransitionState(void); 597 598 /*! 599 * @brief Power function to be added to the application idle loop 600 * 601 * This function should be added to the application idle loop. (The method to 602 * do this depends upon the operating system being used.) This function 603 * will invoke the configured power policy function when appropriate. The 604 * specific policy function to be invoked is configured as the 'policyFxn' 605 * in the application-defined Power configuration object. 606 * 607 */ 608 void Power_idleFunc(void); 609 610 /*! 611 * @brief Power initialization function 612 * 613 * This function initializes Power Manager internal state. 614 * 615 * @warning The application is responsible for ensuring this function is 616 * called prior to any other Power API. Additionally, this function must be 617 * be called prior to any other TI-Driver's APIs. This function is normally 618 * called prior to any operating system initialization. 619 * 620 * @return #Power_SOK 621 */ 622 int_fast16_t Power_init(void); 623 624 /*! 625 * @brief Register a function to be called upon a specific power event 626 * 627 * This function registers a function to be called when a Power event occurs. 628 * Registrations and the corresponding notifications are processed in 629 * first-in-first-out (FIFO) order. The function registered must behave as 630 * described later, below. 631 * 632 * The pNotifyObj parameter is a pointer to a pre-allocated, opaque object 633 * that will be used by Power to support the notification. This object could 634 * be dynamically allocated, or declared as a global object. This function 635 * will properly initialized the object's fields as appropriate; the caller 636 * just needs to provide a pointer to this pre-existing object. 637 * 638 * The eventTypes parameter identifies the type of power event(s) for which 639 * the notify function being registered is to be called. (Event identifiers are 640 * device specific, and defined in the device-specific Power include file. 641 * For example, the events for MSP432 are defined in PowerMSP432.h.) The 642 * eventTypes parameter for this function call is treated as a bitmask, so 643 * multiple event types can be registered at once, using a common callback 644 * function. For example, to call the specified notifyFxn when both 645 * the entering deepsleep and awake from deepsleep events occur, eventTypes 646 * should be specified as: PowerMSP432_ENTERING_DEEPSLEEP | 647 * PowerMSP432_AWAKE_DEEPSLEEP 648 * 649 * The notifyFxn parameter specifies a callback function to be called when the 650 * specified Power event occurs. The notifyFxn must implement the following 651 * signature: 652 * status = notifyFxn(eventType, eventArg, clientArg); 653 * 654 * Where: eventType identifies the event being signaled, eventArg is an 655 * optional event-specific argument, and clientArg is an arbitrary argument 656 * specified by the client at registration. Note that multiple types of events 657 * can be specified when registering the notification callback function, 658 * but when the callback function is actually called by Power, only a 659 * single eventType will be specified for the callback (i.e., the current 660 * event). The status returned by the client notification function must 661 * be one of the following constants: Power_NOTIFYDONE if the client processed 662 * the notification successfully, or Power_NOTIFYERROR if an error occurred 663 * during notification. 664 * 665 * The clientArg parameter is an arbitrary, client-defined argument to be 666 * passed back to the client upon notification. This argument may allow one 667 * notify function to be used by multiple instances of a driver (that is, the 668 * clientArg can be used to identify the instance of the driver that is being 669 * notified). 670 * 671 * @param[in] pNotifyObj #Power_NotifyObj preallocated by caller 672 * 673 * @param[in] eventTypes event type or types 674 * 675 * @param[in] notifyFxn client's #Power_NotifyFxn function 676 * 677 * @param[in] clientArg client-specified argument to pass with 678 * notification 679 * 680 * @retval #Power_SOK on success. 681 * 682 * @retval #Power_EINVALIDPOINTER if either @p pNotifyObj or @p notifyFxn 683 * are NULL. 684 * 685 * @sa Power_unregisterNotify() 686 * @sa @ref ti_drivers_Power_Examples_notify "Using power notify" 687 */ 688 int_fast16_t Power_registerNotify(Power_NotifyObj *pNotifyObj, 689 uint_fast16_t eventTypes, 690 Power_NotifyFxn notifyFxn, 691 uintptr_t clientArg); 692 693 /*! 694 * @brief Release a previously declared constraint 695 * 696 * This function releases a constraint that was previously declared with 697 * Power_setConstraint(). For example, if a device driver is starting an I/O 698 * transaction and wants to prohibit activation of a sleep state during the 699 * transaction, it uses Power_setConstraint() to declare the constraint, 700 * before starting the transaction. When the transaction completes, the 701 * driver calls this function to release the constraint, to allow the Power 702 * manager to once again allow transitions to sleep. 703 * 704 * Constraint identifiers are device specific, and defined in the 705 * device-specific Power include file. For example, the constraints for 706 * MSP432 are defined in PowerMSP432.h. 707 * 708 * Only one constraint can be specified with each call to this function; to 709 * release multiple constraints this function must be called multiple times. 710 * 711 * It is critical that clients call Power_releaseConstraint() when operational 712 * constraints no longer exists. Otherwise, Power may be left unnecessarily 713 * restricted from activating power savings. 714 * 715 * @pre Power_setConstraint() must have been called first. 716 * 717 * @param[in] constraintId constraint id 718 * 719 * @return <b>CC26XX/CC13XX only</b>: #Power_SOK. To minimize code size 720 * asserts are used internally to check that the constraintId is 721 * valid,valid, and that the constraint count is not already zero; 722 * the function always returns #Power_SOK. 723 * 724 * @return <b>All other devices</b>: #Power_SOK on success, 725 * #Power_EINVALIDINPUT if the constraintId is invalid, and 726 * #Power_EFAIL if the constraint count is already zero. 727 * 728 * @sa Power_setConstraint() 729 * @sa @ref ti_drivers_Power_Examples_constraint "Using power constraints" 730 */ 731 int_fast16_t Power_releaseConstraint(uint_fast16_t constraintId); 732 733 /*! 734 * @brief Release a previously declared dependency 735 * 736 * This function releases a dependency that had been previously declared upon 737 * a resource (by a call to Power_setDependency()). 738 * 739 * Resource identifiers are device specific, and defined in the 740 * device-specific Power include file. For example, the resources for 741 * CC32XX are defined in PowerCC32XX.h. 742 * 743 * @param[in] resourceId resource id 744 * 745 * @return <b>CC26XX/CC13XX only</b>: #Power_SOK. To minimize code size 746 * asserts are used internally to check that the resourceId is valid, 747 * and that the resource reference count is not already zero; 748 * the function always returns #Power_SOK. 749 * 750 * @return <b>All other devices</b>: #Power_SOK on success, 751 * #Power_EINVALIDINPUT if the resourceId is invalid, and #Power_EFAIL 752 * if the resource reference count is already zero. 753 * 754 * @sa Power_setDependency() 755 * @sa @ref ti_drivers_Power_Examples_dependency "Using power dependency" 756 */ 757 int_fast16_t Power_releaseDependency(uint_fast16_t resourceId); 758 759 /*! 760 * @brief Declare an operational constraint 761 * 762 * Before taking certain actions, the Power Manager checks to see if the 763 * requested action would conflict with a client-declared constraint. If the 764 * action does conflict, Power will not proceed with the request. This is the 765 * function that allows clients to declare their constraints with Power. 766 * 767 * Constraint identifiers are device specific, and defined in the 768 * device-specific Power include file. For example, the constraints for 769 * MSP432 are defined in PowerMSP432.h. 770 * 771 * Only one constraint can be specified with each call to this function; to 772 * declare multiple constraints this function must be called multiple times. 773 * 774 * @param[in] constraintId constraint id 775 * 776 * @return <b>CC26XX/CC13XX only</b>: #Power_SOK. To minimize code size an 777 * assert is used internally to check that the constraintId is valid; 778 * the function always returns #Power_SOK. 779 * 780 * @return <b>All other devices</b>: #Power_SOK on success, 781 * #Power_EINVALIDINPUT if the constraintId is invalid. 782 * 783 * @sa Power_releaseConstraint() 784 * @sa @ref ti_drivers_Power_Examples_constraint "Using power constraints" 785 */ 786 int_fast16_t Power_setConstraint(uint_fast16_t constraintId); 787 788 /*! 789 * @brief Declare a dependency upon a resource 790 * 791 * This function declares a dependency upon a resource. For example, if a 792 * UART driver needs a specific UART peripheral, it uses this function to 793 * declare this to the Power Manager. If the resource had been inactive, 794 * then Power will activate the peripheral during this function call. 795 * 796 * What is needed to make a peripheral resource 'active' will vary by device 797 * family. For some devices this may be a simple enable of a clock to the 798 * specified peripheral. For others it may also require a power on of a 799 * power domain. In either case, the Power Manager will take care of these 800 * details, and will also implement reference counting for resources and their 801 * interdependencies. For example, if multiple UART peripherals reside in 802 * a shared serial power domain, the Power Manager will power up the serial 803 * domain when it is first needed, and then automatically power the domain off 804 * later, when all related dependencies for the relevant peripherals are 805 * released. 806 * 807 * Resource identifiers are device specific, and defined in the 808 * device-specific Power include file. For example, the resources for 809 * CC32XX are defined in PowerCC32XX.h. 810 * 811 * @param[in] resourceId resource id 812 * 813 * @return <b>CC26XX/CC13XX only</b>: #Power_SOK. To minimize code size an 814 * assert is used internally to check that the resourceId is valid; 815 * the function always returns #Power_SOK. 816 * 817 * @return <b>All other devices</b>: #Power_SOK on success, 818 * #Power_EINVALIDINPUT if the reseourceId is invalid. 819 * 820 * @sa Power_releaseDependency() 821 * @sa @ref ti_drivers_Power_Examples_dependency "Using power dependency" 822 */ 823 int_fast16_t Power_setDependency(uint_fast16_t resourceId); 824 825 /*! 826 * @brief Set the MCU performance level 827 * 828 * This function manages a transition to a new device performance level. 829 * Before the actual transition is initiated, notifications will be sent to 830 * any clients who've registered with Power_registerNotify() for a 831 * 'start change performance level' notification. The event name is device 832 * specific, and defined in the device-specific Power include file. For 833 * example, for MSP432, the event is "PowerMSP432_START_CHANGE_PERF_LEVEL", 834 * which is defined in PowerMSP432.h. Once notifications have been completed, 835 * the change to the performance level is initiated. After the level change 836 * is completed, there is a comparable event that can be used to signal a 837 * client that the change has completed. For example, on MSP432 the 838 * "PowerMSP432_DONE_CHANGE_PERF_LEVEL" event can be used to signal 839 * completion. 840 * 841 * This function will not return until the new performance level is in effect. 842 * If performance scaling is not supported for the device, or is prohibited 843 * by an active constraint, or if the specified level is invalid, then an 844 * error status will be returned. 845 * 846 * @param[in] level the new performance level 847 * 848 * @retval #Power_SOK on success. 849 * 850 * @retval #Power_EINVALIDINPUT if the specified performance level is out of 851 * range of valid levels. 852 * 853 * @retval #Power_EBUSY if another transition is already in progress, or if 854 * a single constraint is set to prohibit any change to the 855 * performance level. 856 * 857 * @retval #Power_ECHANGE_NOT_ALLOWED if a level-specific constraint prohibits 858 * a change to the requested level. 859 * 860 * @retval #Power_EFAIL if performance scaling is not supported, if an 861 * error occurred during initialization, or if an error occurred 862 * during client notifications. 863 * 864 * @sa Power_getPerformanceLevel() 865 */ 866 int_fast16_t Power_setPerformanceLevel(uint_fast16_t level); 867 868 /*! 869 * @brief Set a new Power policy 870 * 871 * This function allows a new #Power_PolicyFxn function to be selected at 872 * runtime. 873 * 874 * @param[in] policy the new #Power_PolicyFxn function 875 */ 876 void Power_setPolicy(Power_PolicyFxn policy); 877 878 /*! 879 * @brief Put the device into a shutdown state 880 * 881 * This function will transition the device into a shutdown state. 882 * Before the actual transition is initiated, notifications will be sent to 883 * any clients who've registered (with Power_registerNotify()) for an 884 * 'entering shutdown' event. The event name is device specific, and defined 885 * in the device-specific Power include file. For example, for CC32XX, the 886 * event is "PowerCC32XX_ENTERING_SHUTDOWN", which is defined in 887 * PowerCC32XX.h. Once notifications have been completed, the device shutdown 888 * will commence. 889 * 890 * If the device is successfully transitioned to shutdown, this function 891 * call will never return. Upon wakeup, the device and application will 892 * be rebooted (through a device reset). If the transition is not 893 * successful, one of the error codes listed below will be returned. 894 * 895 * On some devices a timed wakeup from shutdown can be specified, using 896 * the shutdownTime parameter. This enables an autonomous application reboot 897 * at a future time. For example, an application can go to shutdown, and then 898 * automatically reboot at a future time to do some work. And once that work 899 * is done, the application can shutdown again, for another timed interval. 900 * The time interval is specified via the shutdownTime parameter. (On devices 901 * that do not support this feature, any value specified for shutdownTime will 902 * be ignored.) If the specified shutdownTime is zero, or otherwise less than 903 * the total shutdown latency for the device, the shutdownTime parameter will 904 * be ignored. The shutdown latency for the device can be found in the 905 * device-specific Power include file. For example, for the CC32XX, this 906 * latency is defined in PowerCC32XX.h, as "PowerCC32XX_TOTALTIMESHUTDOWN".) 907 * 908 * @param[in] shutdownState the device-specific shutdown state 909 * 910 * @param[in] shutdownTime the amount of time (in milliseconds) to keep 911 * the the device in the shutdown state; this parameter is not supported on 912 * all device families. 913 * 914 * @retval #Power_ECHANGE_NOT_ALLOWED if a constraint is prohibiting 915 * shutdown. 916 * 917 * @retval #Power_EFAIL if an error occurred during client notifications. 918 * 919 * @retval #Power_EINVALIDINPUT if the shutdownState is invalid. 920 * 921 * @retval #Power_EBUSY if another transition is already in progress. 922 */ 923 int_fast16_t Power_shutdown(uint_fast16_t shutdownState, 924 uint_fast32_t shutdownTime); 925 926 /*! 927 * @brief Transition the device into a sleep state 928 * 929 * This function is called from the power policy when it has made a decision 930 * to put the device in a specific sleep state. This function returns to the 931 * caller (the policy function) once the device has awoken from sleep. 932 * 933 * @warning This function must be called with interrupts disabled, and 934 * should not be called directly by the application, or by any drivers. 935 * This function does not check declared constraints; the policy function 936 * must check constraints before calling this function to initiate sleep. 937 * 938 * @param[in] sleepState the sleep state 939 * 940 * @retval #Power_SOK on success, the device has slept and is awake again. 941 * 942 * @retval #Power_EFAIL if an error occurred during client notifications, or 943 * if a general failure occurred. 944 * 945 * @retval #Power_EINVALIDINPUT if the @p sleepState is invalid. 946 * 947 * @retval #Power_EBUSY if another transition is already in progress. 948 */ 949 int_fast16_t Power_sleep(uint_fast16_t sleepState); 950 951 /*! 952 * @brief Unregister previously registered notifications 953 * 954 * This function unregisters for event notifications that were previously 955 * registered with Power_registerNotify(). The caller must specify a pointer 956 * to the same notification object used during registration. 957 * 958 * @param[in] pNotifyObj The #Power_NotifyObj used with the original 959 * call to Power_registerNotify() 960 * 961 * @sa Power_registerNotify() 962 * @sa @ref ti_drivers_Power_Examples_notify "Using power notify" 963 */ 964 void Power_unregisterNotify(Power_NotifyObj *pNotifyObj); 965 966 #ifdef __cplusplus 967 } 968 #endif 969 970 #endif /* ti_drivers_Power__include */ 971
