1 /* 2 * Copyright (c) 2015-2024, 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 * } 326 * 327 * // Get the Power_TOTAL and Power_RESUME transition latency for a 328 * // device specific sleepState. Latency is in microseconds. 329 * totalLatency = Power_getTransitionLatency(sleepState, Power_TOTAL); 330 * resumeLatency = Power_getTransitionLatency(sleepState, Power_RESUME); 331 * @endcode 332 * 333 * 334 * <hr> 335 * @anchor ti_drivers_Power_Configuration 336 * # Configuration 337 * 338 * @note The Power Manager APIs and configuration parameters are described here. 339 * For a detailed description of terms and concepts, and usage by different 340 * types of software components (peripheral drivers, power policies, 341 * and applications) please see the 342 * <a href='../../Power_Management.pdf'>SimpleLink SDK Power Management User's Guide</a>. 343 * <hr> 344 ****************************************************************************** 345 */ 346 347 #ifndef ti_drivers_Power__include 348 #define ti_drivers_Power__include 349 350 /* @cond */ 351 #include <stdbool.h> 352 #include <stdint.h> 353 /* @endcond */ 354 355 #include <ti/drivers/utils/List.h> 356 #include <ti/devices/DeviceFamily.h> 357 358 /* Note: Device specific Power include files are included in the bottom of this file. */ 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 /*! @}*/ 397 398 /*! 399 * @brief Power policy initialization function pointer 400 */ 401 typedef void (*Power_PolicyInitFxn)(void); 402 403 /*! 404 * @brief Power policy function pointer 405 */ 406 typedef void (*Power_PolicyFxn)(void); 407 408 /*! 409 * @brief Power notify callback function used with the 410 * Power_registerNotify() 411 * 412 * @param[in] eventType The eventTypes parameter identifies the type of 413 * power event for which the notify callback function was called. 414 * 415 * @param[in] eventArg An optional @p eventType specific argument. 416 * 417 * @param[in] clientArg Pointer to a custom argument. 418 * 419 * @retval #Power_NOTIFYDONE if the client processed the notification 420 * successfully 421 * 422 * @retval #Power_NOTIFYERROR if an error occurred during notification. 423 * 424 * @sa Power_registerNotify() 425 * @sa Power_unregisterNotify() 426 * @sa Power_NotifyObj 427 * @sa @ref ti_drivers_Power_Examples_notify "Using power notify" 428 */ 429 typedef int_fast16_t (*Power_NotifyFxn)(uint_fast16_t eventType, uintptr_t eventArg, uintptr_t clientArg); 430 431 /*! 432 * @brief Power notify object structure. 433 * 434 * This structure specification is for internal use. Notification clients must 435 * pre-allocate a notify object when registering for a notification; 436 * Power_registerNotify() will take care initializing the internal elements 437 * appropriately. 438 * 439 * @sa @ref ti_drivers_Power_Examples_notify "Using power notify" 440 */ 441 typedef struct 442 { 443 List_Elem link; /*!< for placing on the notify list */ 444 uint_fast16_t eventTypes; /*!< the event type */ 445 Power_NotifyFxn notifyFxn; /*!< notification function */ 446 uintptr_t clientArg; /*!< argument provided by client */ 447 } Power_NotifyObj; 448 449 /*! 450 * @brief Power resource identifier 451 */ 452 typedef uint32_t Power_Resource; 453 454 /*! 455 * @brief Disable the configured power policy from running when the CPU is 456 * idle 457 * 458 * Calling this function clears the flag that controls whether the configured 459 * power policy function is invoked on each pass through the Idle loop. 460 * This function call will override both a 'true' setting of the 461 * "enablePolicy" setting in the Power Manager configuration object, as well 462 * as a previous runtime call to the Power_enablePolicy() function. 463 * 464 * @return The old value of "enablePolicy". 465 * 466 * @sa Power_enablePolicy() 467 * @sa @ref ti_drivers_Power_Examples_enable "Enabling power policy" 468 * @sa @ref ti_drivers_Power_Examples_disable "Disabling power policy" 469 */ 470 bool Power_disablePolicy(void); 471 472 /*! 473 * @brief Enable the configured power policy to run when the CPU is idle 474 * 475 * Calling this function sets a flag that will cause the configured power 476 * policy function to be invoked on each pass through the Idle loop. This 477 * function call will override both a 'false' setting of the "enablePolicy" 478 * setting in the Power Manager configuration object, as well as a previous 479 * runtime call to the Power_disablePolicy() function. 480 * 481 * For some processor families, automatic power transitions can make initial 482 * application development more difficult, as well as being at odds with 483 * basic debugger operation. This convenience function allows an application 484 * to be initially configured, built, and debugged, without automatic power 485 * transitions during idle time. When the application is found to be working, 486 * this function can be called (typically in main()) to enable the policy 487 * to run, without having to change the application configuration. 488 * 489 * @sa Power_disablePolicy() 490 * @sa @ref ti_drivers_Power_Examples_enable "Enabling power policy" 491 * @sa @ref ti_drivers_Power_Examples_disable "Disabling power policy" 492 */ 493 void Power_enablePolicy(void); 494 495 /*! 496 * @brief Get the constraints that have been declared with Power 497 * 498 * This function returns a bitmask indicating the constraints that are 499 * currently declared to the Power Manager (via previous calls to 500 * Power_setConstraint()). For each constraint that is currently declared, 501 * the corresponding bit in the bitmask will be set. For example, if two 502 * clients have independently declared two different constraints, the returned 503 * bitmask will have two bits set. 504 * 505 * Constraint identifiers are device specific, and defined in the 506 * device-specific Power include file. For example, the constraints for 507 * CC26XX are defined in PowerCC26XX.h. The corresponding bit in the 508 * bitmask returned by this function can be derived by a left-shift using 509 * the constraint identifier. For example, for CC26XX, for the corresponding 510 * bit for the PowerCC26XX_DISALLOW_STANDBY constraint, the bit position is 511 * determined by the operation: (1 << PowerCC26XX_DISALLOW_STANDBY) 512 * 513 * @return A bitmask of the currently declared constraints. 514 * 515 * @sa Power_setConstraint() 516 * @sa @ref ti_drivers_Power_Examples_constraint "Using power constraints" 517 */ 518 uint_fast32_t Power_getConstraintMask(void); 519 520 /*! 521 * @brief Get the current dependency count for a resource 522 * 523 * This function returns the number of dependencies that are currently 524 * declared upon a resource. 525 * 526 * Resource identifiers are device specific, and defined in the 527 * device-specific Power include file. 528 * 529 * @param[in] resourceId resource id 530 * 531 * @return The number of dependencies declared for the resource. 532 * 533 * @retval #Power_EINVALIDINPUT if the @p resourceId is invalid or this 534 * function is not supported by the device specific implementation. 535 * 536 * @sa Power_setDependency() 537 * @sa @ref ti_drivers_Power_Examples_dependency "Using power dependency" 538 */ 539 int_fast16_t Power_getDependencyCount(Power_Resource resourceId); 540 541 /*! 542 * @brief Get the current constraint count for an operational transition 543 * 544 * This function returns the current number of constraints that is set on the 545 * given operational transition. 546 * 547 * Constraint identifiers are device specific, and defined in the 548 * device-specific Power include file. For example, the constraints for 549 * CC26XX are defined in PowerCC26XX.h, and to see how many constraints there 550 * currently are on entering standby, call this function with argument 551 * PowerCC26XX_DISALLOW_STANDBY 552 * 553 * @param[in] constraintId constraint identifier 554 * 555 * @return The count for the given power constraint identifier 556 * 557 * @retval #Power_EINVALIDINPUT if the @p constraintId is invalid or this 558 * function is not supported by the device specific implementation. 559 * 560 * @sa Power_setConstraint() 561 */ 562 int_fast16_t Power_getConstraintCount(uint_fast16_t constraintId); 563 564 /*! 565 * @brief Get the hardware transition latency for a sleep state 566 * 567 * This function reports the minimal hardware transition latency for a specific 568 * sleep state. The reported latency is that for a direct transition, and does 569 * not include any additional latency that might occur due to software-based 570 * notifications. 571 * 572 * Sleep states are device specific, and defined in the device-specific Power 573 * include file. 574 * 575 * This function is typically called by the power policy function. The latency 576 * is reported in units of microseconds. 577 * 578 * @param[in] sleepState the sleep state 579 * 580 * @param[in] type @ref Power_Latency_Type (#Power_TOTAL or #Power_RESUME) 581 * 582 * @return The latency value, in units of microseconds. 583 * 584 * @sa @ref ti_drivers_Power_Examples_transistion "Power transitions" 585 */ 586 uint_fast32_t Power_getTransitionLatency(uint_fast16_t sleepState, uint_fast16_t type); 587 588 /*! 589 * @brief Get the current transition state of the Power Manager 590 * 591 * @return The current @ref Power_Transition_State. 592 * 593 * @retval #Power_ACTIVE returned when no transitions are in progress. 594 * 595 * @retval #Power_ENTERING_SLEEP returned during the transition to 596 * sleep, before sleep has occurred. 597 * 598 * @retval #Power_EXITING_SLEEP returned after wakeup, as the device is 599 * being transitioned back to #Power_ACTIVE. 600 * 601 * @sa @ref ti_drivers_Power_Examples_transistion "Power transitions" 602 */ 603 uint_fast16_t Power_getTransitionState(void); 604 605 /*! 606 * @brief Power function to be added to the application idle loop 607 * 608 * This function should be added to the application idle loop. (The method to 609 * do this depends upon the operating system being used.) This function 610 * will invoke the configured power policy function when appropriate. The 611 * specific policy function to be invoked is configured as the 'policyFxn' 612 * in the application-defined Power configuration object. 613 * 614 */ 615 void Power_idleFunc(void); 616 617 /*! 618 * @brief Power initialization function 619 * 620 * This function initializes Power Manager internal state. 621 * 622 * @warning The application is responsible for ensuring this function is 623 * called prior to any other Power API. Additionally, this function must be 624 * be called prior to any other TI-Driver's APIs. This function is normally 625 * called prior to any operating system initialization. 626 * 627 * @return #Power_SOK 628 */ 629 int_fast16_t Power_init(void); 630 631 /*! 632 * @brief Register a function to be called upon a specific power event 633 * 634 * This function registers a function to be called when a Power event occurs. 635 * Registrations and the corresponding notifications are processed in 636 * first-in-first-out (FIFO) order. The function registered must behave as 637 * described later, below. 638 * 639 * The pNotifyObj parameter is a pointer to a pre-allocated, opaque object 640 * that will be used by Power to support the notification. This object could 641 * be dynamically allocated, or declared as a global object. This function 642 * will properly initialized the object's fields as appropriate; the caller 643 * just needs to provide a pointer to this pre-existing object. 644 * 645 * The eventTypes parameter identifies the type of power event(s) for which 646 * the notify function being registered is to be called. (Event identifiers are 647 * device specific, and defined in the device-specific Power include file. 648 * For example, the events for CC26XX are defined in PowerCC26XX.h.) The 649 * eventTypes parameter for this function call is treated as a bitmask, so 650 * multiple event types can be registered at once, using a common callback 651 * function. For example, to call the specified notifyFxn when both 652 * the entering deepsleep and awake from deepsleep events occur, eventTypes 653 * should be specified as: PowerCC26XX_ENTERING_STANDBY | 654 * PowerCC26XX_AWAKE_STANDBY 655 * 656 * The notifyFxn parameter specifies a callback function to be called when the 657 * specified Power event occurs. The notifyFxn must implement the following 658 * signature: 659 * status = notifyFxn(eventType, eventArg, clientArg); 660 * 661 * Where: eventType identifies the event being signaled, eventArg is an 662 * optional event-specific argument, and clientArg is an arbitrary argument 663 * specified by the client at registration. Note that multiple types of events 664 * can be specified when registering the notification callback function, 665 * but when the callback function is actually called by Power, only a 666 * single eventType will be specified for the callback (i.e., the current 667 * event). The status returned by the client notification function must 668 * be one of the following constants: Power_NOTIFYDONE if the client processed 669 * the notification successfully, or Power_NOTIFYERROR if an error occurred 670 * during notification. 671 * 672 * The clientArg parameter is an arbitrary, client-defined argument to be 673 * passed back to the client upon notification. This argument may allow one 674 * notify function to be used by multiple instances of a driver (that is, the 675 * clientArg can be used to identify the instance of the driver that is being 676 * notified). 677 * 678 * @param[in] pNotifyObj #Power_NotifyObj preallocated by caller 679 * 680 * @param[in] eventTypes event type or types 681 * 682 * @param[in] notifyFxn client's #Power_NotifyFxn function 683 * 684 * @param[in] clientArg client-specified argument to pass with 685 * notification 686 * 687 * @retval #Power_SOK on success. 688 * 689 * @retval #Power_EINVALIDPOINTER if either @p pNotifyObj or @p notifyFxn 690 * are NULL. 691 * 692 * @sa Power_unregisterNotify() 693 * @sa @ref ti_drivers_Power_Examples_notify "Using power notify" 694 */ 695 int_fast16_t Power_registerNotify(Power_NotifyObj *pNotifyObj, 696 uint_fast16_t eventTypes, 697 Power_NotifyFxn notifyFxn, 698 uintptr_t clientArg); 699 700 /*! 701 * @brief Release a previously declared constraint 702 * 703 * This function releases a constraint that was previously declared with 704 * Power_setConstraint(). For example, if a device driver is starting an I/O 705 * transaction and wants to prohibit activation of a sleep state during the 706 * transaction, it uses Power_setConstraint() to declare the constraint, 707 * before starting the transaction. When the transaction completes, the 708 * driver calls this function to release the constraint, to allow the Power 709 * manager to once again allow transitions to sleep. 710 * 711 * Constraint identifiers are device specific, and defined in the 712 * device-specific Power include file. For example, the constraints for 713 * CC26XX are defined in PowerCC26XX.h. 714 * 715 * Only one constraint can be specified with each call to this function; to 716 * release multiple constraints this function must be called multiple times. 717 * 718 * It is critical that clients call Power_releaseConstraint() when operational 719 * constraints no longer exists. Otherwise, Power may be left unnecessarily 720 * restricted from activating power savings. 721 * 722 * @pre Power_setConstraint() must have been called first. 723 * 724 * @param[in] constraintId constraint id 725 * 726 * @return <b>CC26XX/CC13XX only</b>: #Power_SOK. To minimize code size 727 * asserts are used internally to check that the constraintId is 728 * valid,valid, and that the constraint count is not already zero; 729 * the function always returns #Power_SOK. 730 * 731 * @return <b>All other devices</b>: #Power_SOK on success, 732 * #Power_EINVALIDINPUT if the constraintId is invalid, and 733 * #Power_EFAIL if the constraint count is already zero. 734 * 735 * @sa Power_setConstraint() 736 * @sa @ref ti_drivers_Power_Examples_constraint "Using power constraints" 737 */ 738 int_fast16_t Power_releaseConstraint(uint_fast16_t constraintId); 739 740 /*! 741 * @brief Release a previously declared dependency 742 * 743 * This function releases a dependency that had been previously declared upon 744 * a resource (by a call to Power_setDependency()). 745 * 746 * Resource identifiers are device specific, and defined in the 747 * device-specific Power include file. 748 * 749 * @param[in] resourceId resource id 750 * 751 * @return <b>CC26XX/CC13XX only</b>: #Power_SOK. To minimize code size 752 * asserts are used internally to check that the resourceId is valid, 753 * and that the resource reference count is not already zero; 754 * the function always returns #Power_SOK. 755 * 756 * @return <b>All other devices</b>: #Power_SOK on success, 757 * #Power_EINVALIDINPUT if the resourceId is invalid, and #Power_EFAIL 758 * if the resource reference count is already zero. 759 * 760 * @sa Power_setDependency() 761 * @sa @ref ti_drivers_Power_Examples_dependency "Using power dependency" 762 */ 763 int_fast16_t Power_releaseDependency(Power_Resource resourceId); 764 765 /*! 766 * @brief Resets the system and causes it to reboot 767 * 768 * This function causes the system to reset and then boot up again. The impact 769 * this has on the existing system state such as what memory is retained is 770 * device-specific. Unless otherwise specified in the device-specific 771 * documentation, this function will trigger the most comprehensive reset of 772 * the system triggerable from software. 773 */ 774 void Power_reset(void); 775 776 /*! 777 * @brief Declare an operational constraint 778 * 779 * Before taking certain actions, the Power Manager checks to see if the 780 * requested action would conflict with a client-declared constraint. If the 781 * action does conflict, Power will not proceed with the request. This is the 782 * function that allows clients to declare their constraints with Power. 783 * 784 * Constraint identifiers are device specific, and defined in the 785 * device-specific Power include file. For example, the constraints for 786 * CC26XX are defined in PowerCC26XX.h. 787 * 788 * Only one constraint can be specified with each call to this function; to 789 * declare multiple constraints this function must be called multiple times. 790 * 791 * @param[in] constraintId constraint id 792 * 793 * @return <b>CC26XX/CC13XX only</b>: #Power_SOK. To minimize code size an 794 * assert is used internally to check that the constraintId is valid; 795 * the function always returns #Power_SOK. 796 * 797 * @return <b>All other devices</b>: #Power_SOK on success, 798 * #Power_EINVALIDINPUT if the constraintId is invalid. 799 * 800 * @sa Power_releaseConstraint() 801 * @sa @ref ti_drivers_Power_Examples_constraint "Using power constraints" 802 */ 803 int_fast16_t Power_setConstraint(uint_fast16_t constraintId); 804 805 /*! 806 * @brief Declare a dependency upon a resource 807 * 808 * This function declares a dependency upon a resource. For example, if a 809 * UART driver needs a specific UART peripheral, it uses this function to 810 * declare this to the Power Manager. If the resource had been inactive, 811 * then Power will activate the peripheral during this function call. 812 * 813 * What is needed to make a peripheral resource 'active' will vary by device 814 * family. For some devices this may be a simple enable of a clock to the 815 * specified peripheral. For others it may also require a power on of a 816 * power domain. In either case, the Power Manager will take care of these 817 * details, and will also implement reference counting for resources and their 818 * interdependencies. For example, if multiple UART peripherals reside in 819 * a shared serial power domain, the Power Manager will power up the serial 820 * domain when it is first needed, and then automatically power the domain off 821 * later, when all related dependencies for the relevant peripherals are 822 * released. 823 * 824 * Resource identifiers are device specific, and defined in the 825 * device-specific Power include file. 826 * 827 * @param[in] resourceId resource id 828 * 829 * @return <b>CC26XX/CC13XX only</b>: #Power_SOK. To minimize code size an 830 * assert is used internally to check that the resourceId is valid; 831 * the function always returns #Power_SOK. 832 * 833 * @return <b>All other devices</b>: #Power_SOK on success, 834 * #Power_EINVALIDINPUT if the reseourceId is invalid. 835 * 836 * @sa Power_releaseDependency() 837 * @sa @ref ti_drivers_Power_Examples_dependency "Using power dependency" 838 */ 839 int_fast16_t Power_setDependency(Power_Resource resourceId); 840 841 /*! 842 * @brief Set a new Power policy 843 * 844 * This function allows a new #Power_PolicyFxn function to be selected at 845 * runtime. 846 * 847 * @param[in] policy the new #Power_PolicyFxn function 848 */ 849 void Power_setPolicy(Power_PolicyFxn policy); 850 851 /*! 852 * @brief Put the device into a shutdown state 853 * 854 * This function will transition the device into a shutdown state. Before the 855 * actual transition is initiated, notifications will be sent to any clients 856 * who've registered (with Power_registerNotify()) for an 'entering shutdown' 857 * event. The event name is device specific, and defined in the 858 * device-specific Power include file. Once notifications have been completed, 859 * the device shutdown will commence. 860 * 861 * If the device is successfully transitioned to shutdown, this function 862 * call will never return. Upon wakeup, the device and application will 863 * be rebooted (through a device reset). If the transition is not 864 * successful, one of the error codes listed below will be returned. 865 * 866 * On some devices a timed wakeup from shutdown can be specified, using 867 * the shutdownTime parameter. This enables an autonomous application reboot 868 * at a future time. For example, an application can go to shutdown, and then 869 * automatically reboot at a future time to do some work. And once that work 870 * is done, the application can shutdown again, for another timed interval. 871 * The time interval is specified via the shutdownTime parameter. (On devices 872 * that do not support this feature, any value specified for shutdownTime will 873 * be ignored.) If the specified shutdownTime is zero, or otherwise less than 874 * the total shutdown latency for the device, the shutdownTime parameter will 875 * be ignored. The shutdown latency for the device can be found in the 876 * device-specific Power include file. 877 * 878 * @param[in] shutdownState the device-specific shutdown state 879 * 880 * @param[in] shutdownTime the amount of time (in milliseconds) to keep 881 * the the device in the shutdown state; this parameter is not supported on 882 * all device families. 883 * 884 * @retval #Power_ECHANGE_NOT_ALLOWED if a constraint is prohibiting 885 * shutdown. 886 * 887 * @retval #Power_EFAIL if an error occurred during client notifications. 888 * 889 * @retval #Power_EINVALIDINPUT if the shutdownState is invalid. 890 * 891 * @retval #Power_EBUSY if another transition is already in progress. 892 */ 893 int_fast16_t Power_shutdown(uint_fast16_t shutdownState, uint_fast32_t shutdownTime); 894 895 /*! 896 * @brief Transition the device into a sleep state 897 * 898 * This function is called from the power policy when it has made a decision 899 * to put the device in a specific sleep state. This function returns to the 900 * caller (the policy function) once the device has awoken from sleep. 901 * 902 * @warning This function must be called with interrupts disabled, and 903 * should not be called directly by the application, or by any drivers. 904 * This function does not check declared constraints; the policy function 905 * must check constraints before calling this function to initiate sleep. 906 * 907 * @param[in] sleepState the sleep state 908 * 909 * @retval #Power_SOK on success, the device has slept and is awake again. 910 * 911 * @retval #Power_EFAIL if an error occurred during client notifications, or 912 * if a general failure occurred. 913 * 914 * @retval #Power_EINVALIDINPUT if the @p sleepState is invalid. 915 * 916 * @retval #Power_EBUSY if another transition is already in progress. 917 */ 918 int_fast16_t Power_sleep(uint_fast16_t sleepState); 919 920 /*! 921 * @brief Unregister previously registered notifications 922 * 923 * This function unregisters for event notifications that were previously 924 * registered with Power_registerNotify(). The caller must specify a pointer 925 * to the same notification object used during registration. 926 * 927 * @param[in] pNotifyObj The #Power_NotifyObj used with the original 928 * call to Power_registerNotify() 929 * 930 * @sa Power_registerNotify() 931 * @sa @ref ti_drivers_Power_Examples_notify "Using power notify" 932 */ 933 void Power_unregisterNotify(Power_NotifyObj *pNotifyObj); 934 935 #ifdef __cplusplus 936 } 937 #endif 938 939 #if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC13X0_CC26X0 || \ 940 DeviceFamily_PARENT == DeviceFamily_PARENT_CC13X1_CC26X1 || \ 941 DeviceFamily_PARENT == DeviceFamily_PARENT_CC13X2_CC26X2 || \ 942 DeviceFamily_PARENT == DeviceFamily_PARENT_CC13X4_CC26X3_CC26X4) 943 #include <ti/drivers/power/PowerCC26XX.h> 944 #elif (DeviceFamily_PARENT == DeviceFamily_PARENT_CC23X0) 945 #include <ti/drivers/power/PowerCC23X0.h> 946 #elif (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX) 947 #include <ti/drivers/power/PowerCC27XX.h> 948 #elif (DeviceFamily_PARENT == DeviceFamily_PARENT_CC35XX) 949 #include <ti/drivers/power/PowerWFF3.h> 950 #endif 951 952 #endif /* ti_drivers_Power__include */ 953
