1 /*
2 * Copyright (c) 2012-2015, 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.arm.cc26xx;
39
40 import xdc.rov.ViewInfo;
41
42 import xdc.runtime.Assert;
43 import ti.sysbios.knl.Queue;
44 import ti.sysbios.knl.Clock;
45
46 /*!
47 * ======== Power ========
48 * CC26xx Power Manager
49 *
50 * @p(html) 51 * <h3> Calling Context </h3>
52 * <table border="1" cellpadding="3">
53 * <colgroup span="1"></colgroup> <colgroup span="5" align="center"></colgroup>
54 *
55 * <tr><th> Function </th><th> Hwi </th><th> Swi </th><th> Task </th><th> Main </th><th> Startup </th></tr>
56 * <!-- -->
57 * <tr><td> {@link #getConstraintInfo} </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td></tr>
58 * <tr><td> {@link #getDependencyCount} </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td></tr>
59 * <tr><td> {@link #getTicksUntilWakeup} </td><td> N </td><td> N </td><td> Y </td><td> N </td><td> N </td></tr>
60 * <tr><td> {@link #getTransitionLatency} </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td></tr>
61 * <tr><td> {@link #getTransitionState} </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td></tr>
62 * <tr><td> {@link #getXoscStartupTime} </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td></tr>
63 * <tr><td> {@link #registerNotify} </td><td> N </td><td> N </td><td> Y </td><td> Y </td><td> N </td></tr>
64 * <tr><td> {@link #releaseConstraint} </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td></tr>
65 * <tr><td> {@link #releaseDependency} </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td></tr>
66 * <tr><td> {@link #setConstraint} </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td></tr>
67 * <tr><td> {@link #setDependency} </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td><td> Y </td></tr>
68 * <tr><td> {@link #shutdown} </td><td> N </td><td> N </td><td> Y </td><td> Y </td><td> N </td></tr>
69 * <tr><td> {@link #sleep} </td><td> N </td><td> N </td><td> Y </td><td> N </td><td> N </td></tr>
70 * <tr><td> {@link #unregisterNotify} </td><td> N </td><td> N </td><td> Y </td><td> Y </td><td> N </td></tr>
71 * <tr><td colspan="6"> Definitions: <br />
72 * <ul>
73 * <li> <b>Hwi</b>: API is callable from a Hwi thread </li>
74 * <li> <b>Swi</b>: API is callable from a Swi thread </li>
75 * <li> <b>Task</b>: API is callable from a Task thread </li>
76 * <li> <b>Main</b>: API is callable from main() </li>
77 * <li> <b>Startup</b>: API is callable during any module startup </li>
78 * <li> <b>Y</b>: Yes </li>
79 * <li> <b>Y*</b>: Yes, but see API description for restrictions </li>
80 * <li> <b>N</b>: No </li>
81 * </ul>
82 * </td></tr>
83 *
84 * </table>
85 * @p 86 */
87
88 @ModuleStartup /* Initialize Power */
89
90 module Power inherits ti.sysbios.interfaces.IPower
91 {
92 /*! @_nodoc Idle function prototype */
93 typedef Void (*FuncPtr)();
94
95 /*!
96 * ======== Constraint ========
97 * Constraints that can be registered with Power
98 */
99 enum Constraint {
100 SB_VIMS_CACHE_RETAIN = 0x1, /*! disallow loss of cache context during Power_STANDBY (i.e., retain the cache) */
101 SD_DISALLOW = 0x2, /*! disallow transition to SHUTDOWN */
102 SB_DISALLOW = 0x4,/*! disallow transition to Power_STANDBY */
103 IDLE_PD_DISALLOW = 0x8,/*! disallow power down of the CPU domain during idle time (IDLE_PD) */
104 NEED_FLASH_IN_IDLE = 0x10,/*! need to keep Flash powered in IDLE_PD */
105 NUMCONSTRAINTS = 5
106 };
107
108 /*!
109 * ======== LatencyType ========
110 * Type of transition latency to query
111 */
112 enum LatencyType {
113 TOTAL, /*! the total latency, to enter the sleep state, and to wake and resume */
114 RESUME /*! the latency to wake the device and resume execution */
115 };
116
117 /*!
118 * ======== SleepState ========
119 * Sleep states
120 */
121 enum SleepState {
122 STANDBY = 0x1 /*! STANDBY state */
123 };
124
125 /*!
126 * ======== Event ========
127 * Power Event enumerations
128 */
129 enum Event {
130 ENTERING_STANDBY = 0x1, /*! device is transitioning into Power_STANDBY */
131 ENTERING_SHUTDOWN = 0x2, /*! device is transitioning into SHUTDOWN */
132 AWAKE_STANDBY = 0x4, /*! device has awoken from Power_STANDBY, I/O latches are still frozen */
133 AWAKE_STANDBY_LATE = 0x8, /*! device has awoken from Power_STANDBY, I/O latches are open again */
134 XOSC_HF_SWITCHED = 0x10, /*! the high frequency (HF) crystal oscillator has stabilized, and is now the HF clock source */
135 NUMEVENTS = 5
136 };
137
138 /*!
139 * ======== NotifyResponse ========
140 * Return values from a notify function.
141 */
142 enum NotifyResponse {
143 NOTIFYDONE = 0,/*! success, done processing the notification */
144 NOTIFYERROR /*! an error occurred while processing the notification */
145 };
146
147 /*! @_nodoc ResourceRecord structure */
148 struct ResourceRecord {
149 UInt8 flags; /* resource type : first parent */
150 UInt8 flags2; /* second parent */
151 UInt16 driverlibID; /* driverlib ID for the resource */
152 };
153
154 /*!
155 * ======== Status ========
156 * Function return codes
157 */
158 enum Status {
159 SOK = 0, /*! success */
160 SOK_STATE_RESTORED = 1, /*! success, context has been restored */
161 EFAIL = 2, /*! error, the operation failed */
162 EINVALIDPOINTER = 3, /*! error, an invalid pointer was specified */
163 ECHANGE_NOT_ALLOWED = 4,/*! error, the requested change is not allowed */
164 ETIMEOUT = 5, /*! error, a timeout occurred */
165 EBUSY = 6 /*! error, the operation is not allowed; another transition is not completed yet */
166 };
167
168 /*!
169 * ======== TransitionState ========
170 * Sleep transition states
171 */
172 enum TransitionState {
173 ACTIVE = 0x1, /*! device is active; no transition in progress */
174 ENTERING_SLEEP = 0x2,/*! device is entering into a sleep state */
175 EXITING_SLEEP = 0x3, /*! device is exiting a sleep state */
176 SHUTDOWN = 0x4 /*! device is transitioning to the SHUTDOWN state */
177 };
178
179 /*! @_nodoc Notification object structure. */
180 struct NotifyObj {
181 Queue.Elem link;
182 UInt32 eventTypes;
183 Fxn notifyFxn;
184 UArg clientArg;
185 };
186
187 // Asserts
188
189 /*! Assert when Power_releaseConstraint is called too many times */
190 config Assert.Id A_tooManyCallsReleaseConstraint = {
191 msg: "A_tooManyCallsReleaseConstraint: Power_releaseConstraint() called too many times for this constraint."
192 };
193
194 /*! Assert when Power_releaseDependency is called too many times */
195 config Assert.Id A_tooManyCallsReleaseDependency = {
196 msg: "A_tooManyCallsReleaseDependency: Power_releaseDependency() called too many times for this resource."
197 };
198
199 // configs
200
201 /*!
202 * ======== idle ========
203 * Idle the CPU during idle time?
204 *
205 * When this configuration parameter is set to true, the Power module will
206 * insert a power policy function into the list of {@link 207 * ti.sysbios.knl.Idle Idle} loop functions.
208 * When the policy function executes, it will take action to save power
209 * until the next CPU interrupt occurs. The default power policy will
210 * simply invoke a wait for interrupt (WFI) instruction.
211 *
212 * @see #policyFunc
213 * @see #doWFI
214 * @see #standbyPolicy
215 */
216 overrideconfig Bool idle = false;
217
218 /*!
219 * @_nodoc 220 * ======== resumeSTANDBY ========
221 * Latency to resume from STANDBY (in microseconds).
222 * NB: this is a temporary value pending further characterization.
223 */
224 metaonlyconfig UInt resumeSTANDBY = 750;
225
226 /*!
227 * @_nodoc 228 * ======== resumeTicksSTANDBY ========
229 * Latency to resume from STANDBY (in units of Clock ticks).
230 */
231 config UInt resumeTicksSTANDBY;
232
233 /*!
234 * @_nodoc 235 * ======== totalSTANDBY ========
236 * Total latency to enter and resume from STANDBY (in microseconds).
237 * NB: this is a temporary value pending further characterization.
238 */
239 metaonlyconfig UInt totalSTANDBY = 1000;
240
241 /*!
242 * @_nodoc 243 * ======== totalTicksSTANDBY ========
244 * Total latency to enter and resume from STANDBY (in units of Clock
245 * ticks).
246 */
247 config UInt totalTicksSTANDBY;
248
249 /*!
250 * @_nodoc 251 * ======== wakeDelaySTANDBY ========
252 * Device initial wakeup latency from STANDBY (in units of microseconds).
253 */
254 config UInt wakeDelaySTANDBY = 130;
255
256 /*!
257 * @_nodoc 258 * ======== initialWaitXOSC_HF ========
259 * Time (in units of usec) to wait to see if XOSC_HF is stable.
260 */
261 config UInt initialWaitXOSC_HF = 50;
262
263 /*!
264 * @_nodoc 265 * ======== retryWaitXOSC_HF ========
266 * Time (in units of usec) to wait when retrying to see if XOSC_HF is
267 * stable.
268 */
269 config UInt retryWaitXOSC_HF = 50;
270
271 /*!
272 * @_nodoc 273 * ======== calibrateRCOSC ========
274 * Enable RCOSC calibration? Default is true.
275 */
276 config Bool calibrateRCOSC = true;
277
278 /*!
279 * @_nodoc 280 * ======== calibrateRCOSC_LF ========
281 * Enable RCOSC_LF calibration? Default is true;
282 */
283 config Bool calibrateRCOSC_LF = true;
284
285 /*!
286 * @_nodoc 287 * ======== calibrateRCOSC_HF ========
288 * Enable RCOSC_HF calibration? Default is true;
289 */
290 config Bool calibrateRCOSC_HF = true;
291
292 /*!
293 * @_nodoc 294 * Wakeup Clock object's function. Default is Power_defaultClockFunc.
295 */
296 config Clock.FuncPtr clockFunc = Power.defaultClockFunc;
297
298 /*! Policy function. Default is Power_doWFI. */
299 metaonlyconfig FuncPtr policyFunc = Power.doWFI;
300
301 /*!
302 * @_nodoc 303 * Notify trap function. Default is Power.defaultNotifyTrapFunc.
304 */
305 config FuncPtr notifyTrapFunc = Power.defaultNotifyTrapFunc;
306
307 // module functions
308
309 /*!
310 * ======== standbyPolicy ========
311 * A power policy function that will transition the device into the
312 * Power_STANDBY sleep state during CPU idle time.
313 *
314 * This is an agressive power policy function that will consider active
315 * constraints, sleep transition latencies, and the next expected wakeup,
316 * and automatically transition the device into the deepest sleep state
317 * possible.
318 *
319 * The first goal is to enter Power_STANDBY; if that is not appropriate
320 * given current conditions (e.g., the sleep transition latency is
321 * greater than the time until the next scheduled Clock event), then
322 * the secondary goal is the IDLE_PD state; if that is disallowed (e.g.,
323 * if the Power_IDLE_PD_DISALLOW constraint is declared), then the policy
324 * will fallback and simply invoke wait-for-interrupt, to clock
325 * gate the CPU until the next interrupt.
326 *
327 * This policy is enabled and selected via the following application
328 * configuration steps:
329 *
330 * @p(code) 331 * Power.idle = true;
332 * Power.policyFunc = Power.standbyPolicy;
333 * @p 334 */
335 Void standbyPolicy();
336
337 /*!
338 * @_nodoc 339 * ======== defaultClockFunc ========
340 * Function for the Clock object dedicated for scheduling wakeups.
341 */
342 Void defaultClockFunc(UArg arg);
343
344 /*!
345 * @_nodoc 346 * ======== defaultNotifyTrapFunc ========
347 * The default function to be called when a notification client responds
348 * with any value other than Power_NOTIFYDONE.
349 *
350 * The default behavior of this function is to spin in an infinite loop.
351 */
352 Void defaultNotifyTrapFunc();
353
354 /*!
355 * @_nodoc 356 * ======== startFirstMeasurement ========
357 * Start the first RCOSC calibration measurement
358 */
359 Void injectCalibration();
360
361 /*!
362 * @_nodoc 363 * ======== auxISR ========
364 * ISR for AUX combined interrupt for TDC (for RCOSC calibration)
365 */
366 Void auxISR(UArg arg);
367
368 /*!
369 * ======== getClockHandle ========
370 * Get the handle of the Clock object created for scheduling wakeups.
371 */
372 Clock.Handle getClockHandle();
373
374 /*!
375 * ======== doWFI ========
376 * A power policy function that invokes wait-for-interrupt (WFI)
377 * during idle time.
378 *
379 * This is the most basic power policy function, which will invoke
380 * WFI upon entry to the Idle loop. This is the default policy function
381 * that is invoked when CPU idling is enabled with the {@link #idle idle}
382 * configuration parameter:
383 *
384 * @p(code) 385 * Power.idle = true;
386 * @p 387 *
388 */
389 Void doWFI();
390
391 /*!
392 * ======== getConstraintInfo ========
393 * Get a bitmask representing the aggregate of constraints that have been
394 * declared.
395 *
396 * This function returns a bitmask indicating the constraints that are
397 * currently declared to the Power module (via previous calls to
398 * {@link #setConstraint Power_setConstraint()}). For each constraint
399 * (of type {@link #Constraint Power_Constraint}) that is currently
400 * declared, the corresponding bit in the bitmask will be set. For
401 * example, if two clients have declared Power_SB_DISALLOW, and one has
402 * declared Power_SB_VIMS_CACHE_RETAIN, then the returned bitmask
403 * will have the value: Power_SB_DISALLOW | Power_SB_VIMS_CACHE_RETAIN
404 *
405 * @b(returns) A bitmask representing all currently declared
406 * constraints
407 */
408 UInt32 getConstraintInfo();
409
410 /*!
411 * ======== getDependencyCount ========
412 * Get the count of dependencies that are currently declared upon a
413 * resource.
414 *
415 * This function returns the number of dependencies that are currently
416 * declared upon a resource.
417 *
418 * @param(resourceID) The resource identifier, as specified in the
419 * device-specific header file
420 *
421 * @b(returns) The number of dependencies currently declared upon this
422 * resourceID
423 */
424 UInt32 getDependencyCount(UInt8 resourceID);
425
426 /*!
427 * ======== getTransitionState ========
428 * Get the current Power module transition state.
429 *
430 * @b(returns) The current transition state, of type
431 * {@link #TransitionState Power_TransitionState}
432 */
433 TransitionState getTransitionState();
434
435 /*!
436 * ======== getTicksUntilWakeup ========
437 * Get the number of system ticks until the next scheduled wakeup event
438 *
439 * @b(returns) The number of system ticks (i.e.,
440 * {@link ti.sysbios.knl.Clock Clock} module) ticks
441 * until the next scheduled wakeup
442 */
443 UInt32 getTicksUntilWakeup();
444
445 /*!
446 * ======== getTransitionLatency ========
447 * Get the minimal transition latency for a sleep state, in units of
448 * system Clock ticks.
449 *
450 * Note that the reported latency is the device transition latency for
451 * the specified sleep state. This latency value does not include any
452 * additional software induced latency, for example, that due to
453 * notifications of the power transition to drivers.
454 *
455 * @param(sleepState) The {@link #SleepState sleepState} whose transition
456 * latency is to be reported (e.g., Power_STANDBY)
457 *
458 * @param(type) The {@link #LatencyType type} of latency to be
459 * reported
460 *
461 * @b(returns) The transition latency, in units of
462 * {@link ti.sysbios.knl.Clock Clock} ticks.
463 */
464 UInt32 getTransitionLatency(SleepState sleepState, LatencyType type);
465
466 /*!
467 * ======== getXoscStartupTime ========
468 * Get the estimated crystal oscillator startup time, in units of
469 * microseconds.
470 *
471 * @param(timeUntilWakeupInMs) The estimated time until the next wakeup
472 * event, in units of milliseconds
473 *
474 * @b(returns) The estimated crystal oscillator startup latency, in
475 * units of microseconds.
476 *
477 * @a(Note) The estimated time until wakeup is in units of milliseconds,
478 * but the the estimate crystal startup time is in microseconds.
479 */
480 UInt32 getXoscStartupTime(UInt32 timeUntilWakeupInMs);
481
482 /*!
483 * @_nodoc 484 * ======== isStableXOSC_HF ========
485 * Check if XOSC_HF has stabilized.
486 *
487 * @b(returns) TRUE if XOSC_HF has stabilized, FALSE if hasn't
488 * stabilized yet
489 */
490 Bool isStableXOSC_HF();
491
492 /*!
493 * ======== releaseConstraint ========
494 * Release a constraint that was previously declared with {@link 495 * #setConstraint Power_setConstraint()}.
496 *
497 * This function releases a constraint that was previously declared with
498 * {@link #setConstraint Power_setConstraint()}. For example, if a device
499 * driver is starting a transaction and wants to prohibit activation of
500 * the Power_STANDBY sleep mode, it uses {@link #setConstraint
501 * Power_setConstraint} to declare the constraint, before starting
502 * the transaction. When the transaction completes, the driver calls
503 * this function to release the constraint, and allow the power manager
504 * to once again transition into the Power_STANDBY sleep mode, if
505 * appropriate.
506 *
507 * @param(constraint) The constraint being released, of type {@link 508 * #Constraint Power_Constraint}
509 *
510 * @a(constraints) 511 * Power_releaseConstraint() must not be called more than
512 * Power_setConstraint() has been called for the same constraint. If
513 * asserts are enabled, one will be generated in this case.
514 */
515 Void releaseConstraint(Constraint constraint);
516
517 /*!
518 * ======== releaseDependency ========
519 * Release a dependency that had been previously declared with {@link 520 * #setDependency Power_setDependency()}.
521 *
522 * This function is the companion to {@link #setDependency
523 * Power_setDependency()}. If this release is for the last outstanding
524 * dependency upon the resource, the resource will be de-activated as part
525 * of this function call.
526 *
527 * @param(resourceID) The resource identifier, as specified in the
528 * device-specific header file
529 *
530 * @a(constraints) 531 * Power_releaseDependency() must not be called more than
532 * Power_setDependency() has been called for the same resource. If
533 * asserts are enabled, one will be generated in this case.
534 */
535 Void releaseDependency(UInt8 resourceID);
536
537 /*!
538 * ======== registerNotify ========
539 * Register a function to be called upon a specific power event.
540 *
541 * This function registers a function to be called when a
542 * Power event occurs. Registrations and the corresponding notifications
543 * are processed in first-in-first-out (FIFO) order. The function
544 * registered must behave as described below.
545 *
546 * The pNotifyObj parameter is a pointer to a pre-allocated, opaque
547 * object that will be used by Power to support the notification. This
548 * object could be dynamically allocated, or declared as a global object.
549 * Power_registerNotify() will properly initialized the object's fields as
550 * appropriate; the caller just needs to provide a pointer to this
551 * pre-existing object.
552 *
553 * The eventType parameter identifies the type of power event for which
554 * the notify function being registered is to be called. This parameter
555 * is treated as a bitmask, so multiple event types can be registered for
556 * a common function. The event types are enumerated as {@link #Event
557 * Power_Event}. For example, to call the specified function when
558 * both the entering standby and the awake from standby events occur,
559 * eventType should be specified as:
560 * (Power_ENTERING_STANDBY | Power_AWAKE_STANDBY)
561 *
562 * The clientArg parameter is an arbitrary argument to be passed to the
563 * client upon notification. This argument may allow one notify function
564 * to be used by multiple instances of a driver (that is, the clientArg
565 * can be used to identify the instance of the driver that is being
566 * notified).
567 *
568 * The notifyFxn parameter specifies the function to call when the
569 * specified Power event occurs. The notifyFxn must implement
570 * the following signature:
571 *
572 * status = notifyFxn(eventType, clientArg);
573 *
574 * Where: eventType (type of {@link #Event Power_Event}) is the event
575 * being signalled, and clientArg is the abitrary argument specified
576 * by the client at registration. Note that multipe types of events
577 * can be specified when registering the notification callback function,
578 * but when the callback function is actually called by Power, only a
579 * single eventType will be specified for the callback (i.e., the current
580 * event).
581 *
582 * The client notification function being registered must return one of the
583 * following constants as a status value, of type {@link #NotifyResponse
584 * Power_NotifyResponse}: Power_NOTIFYDONE if the client processed the
585 * notification function successfully, or Power_NOTIFYERROR if the
586 * notification cannot be processed (e.g., if an internal client error
587 * occurs).
588 *
589 * @param(pNotifyObj) The notify object to be used for queuing
590 * of the notification callback function
591 *
592 * @param(eventTypes) The type or types of {@link #Event Power_Event} to
593 * be notified of
594 *
595 * @param(notifyFxn) The callback function Power should call to notify
596 * the client of the event
597 *
598 * @param(clientArg) A client-defined argument to pass with the notifyFxn
599 * call
600 *
601 * @param(arg) For future use, should be specified as:
602 * NULL
603 *
604 * @b(returns) Power_SOK if the registration succeeded
605 *
606 * @b(returns) Power_EINVALIDPOINTER if either pNotifyObj or notifyFxn
607 * were NULL
608 *
609 */
610 Status registerNotify(NotifyObj * pNotifyObj, UInt32 eventTypes,
611 Fxn notifyFxn, UArg clientArg, UArg arg);
612
613 /*!
614 * ======== setConstraint ========
615 * Declare an operational constraint.
616 *
617 * Before taking certain actions, Power checks to see if the requested
618 * action would conflict with a client-declared constraint. If the
619 * action does conflict, Power will not proceed with the request.
620 * This is the function that allows clients to declare their constraints
621 * with Power.
622 *
623 * It is critical that clients call {@link #releaseConstraint
624 * Power_releaseConstraint()} when operational constraints no longer
625 * exists. Otherwise, Power may be left unnecessarily restricted from
626 * activating power savings.
627 *
628 * @param(constraint) The constraint being declared, of type {@link 629 * #Constraint Power_Constraint}
630 */
631 Void setConstraint(Constraint constraint);
632
633 /*!
634 * ======== setDependency ========
635 * Declare a dependency upon a power-manageable resource.
636 *
637 * This function declares a dependency upon a resource. If the resource
638 * had been inactive, it will be activated during this function call.
639 *
640 * This function is the companion to {@link #releaseDependency
641 * Power_releaseDependency()}.
642 *
643 * @param(resourceID) The resource identifier, as specified in the
644 * device-specific header file (for example,
645 * PERIPH_UART0, as defined in PowerCC2650.h)
646 * @a(Note) 647 * When a dependency is declared upon a resource for the first time, the
648 * resource will be activated before the call to Power_setDependency()
649 * returns to the caller. There is only one exception to this rule:
650 * the XOSC_HF resource for CC26xx. The latency to startup the crystal
651 * is much longer than that for other resources. To avoid blocking in
652 * Power_setDependency() for this duration, for the XOSC_HF resource
653 * only, Power_setDependency() will return quickly, after initiating the
654 * activation of XOSC_HF. Once the switchover to the XOSC_HF
655 * happens, notifications will be sent to clients registered for the
656 * Power_XOSC_HF_SWITCHED event.
657 *
658 * Power_setDependency() will return a Boolean status to indicate if
659 * the resource is active as the function is initiating a return to the
660 * caller. For all resources other than XOSC_HF, the return status will
661 * always be TRUE, because the resource will be active before the return
662 * to the caller. For XOSC_HF, the return status may be TRUE if the
663 * XOSC_HF is already active. For example, if XOSC_HF was already
664 * activated with an earlier call to Power_setDependency(XOSC_HF).
665 * If the return status is FALSE, this indicates to the caller that
666 * XOSC_HF hadn't been switched by the time the function initiated a
667 * return, and that the caller should wait for the Power_XOSC_HF_SWITCHED
668 * event notification before proceeding to the work that requires XOSC_HF
669 * to be active.
670 *
671 * The recommended sequence for a caller to activate XOSC_HF is:
672 *
673 *
674 * 1) Caller registers for a Power_XOSC_HF_SWITCHED notification.
675 * For example, the specified callback function might set a global
676 * flag, which the caller can check to see if the notification
677 * occurred.
678 *
679 * 2) Caller invokes: status = Power_setDependency(XOSC_HF);
680 *
681 *
682 * 3) Caller checks status to see if XOSC_HF is active yet
683 *
684 *
685 * - If status is TRUE, XOSC_HF is active, caller should proceed,
686 * and NOT wait for a Power_XOSC_HF_SWITCHED notification
687 *
688 * - Else, XOSC_HF wasn't activated yet, caller needs to wait
689 * until the Power_XOSC_HF_SWITCHED event has been signaled.
690 * Note that depending upon timing, the event may have been
691 * signaled between the time the return status was determined
692 * within Power_setDependency() and the time the caller
693 * checks the return status. The key point is that, when
694 * the return status is FALSE, the Power_XOSC_HF_SWITCHED
695 * notification WILL be sent (once the XOSC_HF is switched),
696 * and the caller should wait for this notification before
697 * proceeding with any work that requires XOSC_HF to be active.
698 *
699 * @b(returns) TRUE if resource is active
700 *
701 * @b(returns) FALSE if resource was not yet active when the function
702 * return was initiated
703 *
704 * @a(constraints) 705 * For the XOSC_HF resource (described above), the caller MUST wait for
706 * XOSC_HF activation to complete before calling
707 * Power_releaseDependency(XOSC_HF).
708 */
709 Bool setDependency(UInt8 resourceID);
710
711 /*!
712 * ======== shutdown ========
713 * Put the device into the SHUTDOWN state.
714 *
715 * This function will transition the device into the SHUTDOWN state.
716 * Before the actual device transtion is initiated, notifications will
717 * be sent to any clients who've registered for the
718 * Power_ENTERING_SHUTDOWN event (via {@link #registerNotify
719 * Power_registerNotify()}). Once notifications have been completed, the
720 * device shutdown will commence.
721 *
722 * If the device is successfully transitioned to SHUTDOWN, this function
723 * call will never return. Upon wakeup, the device and application will
724 * be rebooted. If the transition to SHUTDOWN is not successful, one of
725 * the error codes listed above will be returned.
726 *
727 * @param(arg) Reserved for future use; currently unused
728 *
729 * @b(returns) Power_EBUSY if Power is currently busy with another
730 * transition
731 *
732 * @b(returns) Power_ECHANGE_NOT_ALLOWED if SHUTDOWN is disallowed
733 * due to the Power_SD_DISALLOW constraint having been
734 * declared
735 *
736 * @b(returns) Power_EFAIL if a notification error occurred
737 *
738 * @a(Note) 739 * This function will not prepare I/O pins for the device
740 * shutdown state. The application needs to do the appropriate
741 * I/O preparation before calling this API.
742 */
743 Status shutdown(UArg arg);
744
745 /*!
746 * ======== sleep ========
747 * Put the CPU into a sleep state.
748 *
749 * This function transitions the device into and out of a sleep state.
750 * The function returns to the caller when the device is awake again.
751 *
752 * @param(sleepState) The sleep state to be entered, of type
753 * {@link #sleepState Power_sleepState}
754 *
755 * @param(arg0) Reserved for future use; currently unused
756 *
757 * @param(arg1) Reserved for future use; currently unused
758 *
759 * @b(returns) Power_SOK upon success, the device is awake
760 *
761 * @b(returns) Power_EBUSY if Power is currently busy with another
762 * transition
763 *
764 * @b(returns) Power_EFAIL if a general failure occurred and the
765 * device was not transitioned into sleep
766 *
767 * @a(Note) 768 * Power_sleep() is intended to be called from a Power Policy
769 * implementation function. This API is not normally called directly
770 * by an application.
771 *
772 * @a(constraints) 773 * Power_sleep() does not check the constraints that might prohibit a
774 * sleep transition. The caller of Power_sleep() must validate the
775 * transition versus active constraints, prior to calling Power_sleep().
776 */
777 Status sleep(SleepState sleepState, UArg arg0, UArg arg1);
778
779 /*!
780 * @_nodoc 781 * ======== switchXOSC_HF ========
782 * Switch to enable XOSC_HF.
783 */
784 Void switchXOSC_HF();
785
786 /*!
787 * ======== unregisterNotify ========
788 * Unregister for Power event notifications.
789 *
790 * This function unregisters for event notifications that were previously
791 * registered with {@link #registerNotify Power_registerNotify()}.
792 *
793 * @param(pNotifyObj) The notification object that was previously
794 * used with {@link #registerNotify
795 * Power_registerNotify()} to register for
796 * event notifications
797 */
798 Void unregisterNotify(NotifyObj * pNotifyObj);
799
800
801 /*! @_nodoc */
802 @XmlDtd
803 metaonlystruct ModuleView {
804 String ConstraintsMask;
805 };
806
807 /*! @_nodoc */
808 @Facet
809 metaonlyconfig ViewInfo.Instance rovViewInfo =
810 ViewInfo.create({
811 viewMap: [
812 [
813 'Module',
814 {
815 type: ViewInfo.MODULE,
816 viewInitFxn: 'viewInitModule',
817 structName: 'ModuleView'
818 }
819 ],
820 ]
821 });
822
823 /*!
824 * @_nodoc 825 * ======== idleCPU ========
826 * Function used to automatically idle the CPU in the Idle loop.
827 *
828 * When the 'idle' configuration parameter is set, this function will
829 * be added to the list of Idle loop functions. When called from the
830 * Idle loop, it will invoke the wait for interrupt (WFI) instruction,
831 * to idle the CPU until the next interrupt occurs.
832 */
833 Void idleCPU();
834
835 internal:
836
837 /*
838 * ======== abs ========
839 */
840 Int abs(Int i);
841
842 /*
843 * ======== calibrateRcoscHf1 ========
844 */
845 Void calibrateRcoscHf1(Int32 tdcResult);
846
847 /*
848 * ======== calibrateRcoscHf2 ========
849 */
850 Void calibrateRcoscHf2(Int32 tdcResult);
851
852 /*
853 * ======== doCalibrate ========
854 */
855 Void doCalibrate();
856
857 /*
858 * ======== getTdcSemaphore ========
859 */
860 Bool getTdcSemaphore();
861
862 /*
863 * ======== initateCalibration ========
864 */
865 Bool initiateCalibration();
866
867 /*
868 * ======== isDependencyActive ========
869 */
870 Bool isDependencyActive(UInt8 resourceID);
871
872 /*
873 * ======== LF_clockFunc ========
874 */
875 Void LF_clockFunc(UArg arg);
876
877 /*
878 * ======== NOP ========
879 */
880 UInt NOP(UInt action);
881
882 /*
883 * ======== notify ========
884 */
885 Status notify(Event eventType);
886
887 /*
888 * ======== RCOSC_clockFunc ========
889 */
890 Void RCOSC_clockFunc(UArg arg);
891
892 /*
893 * ======== RFCORECLKS ========
894 */
895 UInt RFCORECLKS(UInt action);
896
897 /*
898 * ======== scaleRndInf ========
899 */
900 Int32 scaleRndInf(Int32 x);
901
902 /*
903 * ======== serviceNotifyQ ========
904 */
905 NotifyResponse serviceNotifyQ(Event eventType);
906
907 /*
908 * ======== updateSubSecInc ========
909 */
910 Void updateSubSecInc(UInt32 tdcResult);
911
912 /*
913 * ======== XOSC_HF ========
914 */
915 UInt XOSC_HF(UInt action);
916
917 /*
918 * ======== XOSC_HF_xoscClockFunc ========
919 */
920 Void XOSC_HF_clockFunc(UArg arg);
921
922 /*
923 * ======== Module_State ========
924 */
925 struct Module_State {
926 UInt32 constraintsMask;
927 Queue.Object notifyQ; /* event notification queue */
928 Clock.Object clockObj; /* Clock object for scheduling wakeups */
929 Clock.Object xoscClockObj; /* Clock object for XOSC_HF switching */
930 Clock.Object lfClockObj; /* Clock object for LF clock check */
931 Clock.Handle calClockHandle; /* Clock object for RCOSC calibration */
932 Int32 nDeltaFreqCurr; /* RCOSC calibration variable */
933 Int32 nCtrimCurr; /* RCOSC calibration variable */
934 Int32 nCtrimFractCurr; /* RCOSC calibration variable */
935 Int32 nCtrimNew; /* RCOSC calibration variable */
936 Int32 nCtrimFractNew; /* RCOSC calibration variable */
937 TransitionState state; /* current transition state */
938 Bool xoscPending; /* is XOSC_HF activation in progress? */
939 Bool calLF; /* calibrate RCOSC_LF? */
940 UInt8 hwiState; /* calibration AUX ISR state */
941 Bool busyCal; /* already busy calibrating */
942 UInt8 calStep; /* current calibration step */
943 Bool firstLF; /* is this first LF calibration? */
944 volatile UInt8 * constraintCounts; /* constraint counts array */
945 volatile UInt8 * resourceCounts; /* to resource ref counts array */
946 ResourceRecord * resourceDB;/* resource database */
947 Fxn * resourceHandlers; /* resource special handler functions */
948 }
949 }