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 * ======== initialWaitRCOSC_LF ========
259 * Time (in units of usec) to wait to see if RCOSC_LF is stable.
260 */
261 config UInt initialWaitRCOSC_LF = 1000;
262
263 /*!
264 * @_nodoc 265 * ======== retryWaitRCOSC_LF ========
266 * Time (in units of usec) to wait when retrying to see if RCOSC_LF is
267 * stable.
268 */
269 config UInt retryWaitRCOSC_LF = 1000;
270
271 /*!
272 * @_nodoc 273 * ======== initialWaitXOSC_HF ========
274 * Time (in units of usec) to wait to see if XOSC_HF is stable.
275 */
276 config UInt initialWaitXOSC_HF = 50;
277
278 /*!
279 * @_nodoc 280 * ======== retryWaitXOSC_HF ========
281 * Time (in units of usec) to wait when retrying to see if XOSC_HF is
282 * stable.
283 */
284 config UInt retryWaitXOSC_HF = 50;
285
286 /*!
287 * @_nodoc 288 * ======== initialWaitXOSC_LF ========
289 * Time (in units of usec) to wait to see if XOSC_LF is stable.
290 */
291 config UInt initialWaitXOSC_LF = 10000;
292
293 /*!
294 * @_nodoc 295 * ======== retryWaitXOSC_LF ========
296 * Time (in units of usec) to wait when retrying to see if XOSC_LF is
297 * stable.
298 */
299 config UInt retryWaitXOSC_LF = 5000;
300
301 /*!
302 * @_nodoc 303 * ======== calibrateRCOSC ========
304 * Enable RCOSC calibration? Default is true.
305 */
306 config Bool calibrateRCOSC = true;
307
308 /*!
309 * @_nodoc 310 * ======== calibrateRCOSC_LF ========
311 * Enable RCOSC_LF calibration? Default is true;
312 */
313 config Bool calibrateRCOSC_LF = true;
314
315 /*!
316 * @_nodoc 317 * ======== calibrateRCOSC_HF ========
318 * Enable RCOSC_HF calibration? Default is true;
319 */
320 config Bool calibrateRCOSC_HF = true;
321
322 /*!
323 * @_nodoc 324 * Wakeup Clock object's function. Default is Power_defaultClockFunc.
325 */
326 config Clock.FuncPtr clockFunc = Power.defaultClockFunc;
327
328 /*! Policy function. Default is Power_doWFI. */
329 metaonlyconfig FuncPtr policyFunc = Power.doWFI;
330
331 /*!
332 * @_nodoc 333 * Notify trap function. Default is Power.defaultNotifyTrapFunc.
334 */
335 config FuncPtr notifyTrapFunc = Power.defaultNotifyTrapFunc;
336
337 // module functions
338
339 /*!
340 * ======== standbyPolicy ========
341 * A power policy function that will transition the device into the
342 * Power_STANDBY sleep state during CPU idle time.
343 *
344 * This is an agressive power policy function that will consider active
345 * constraints, sleep transition latencies, and the next expected wakeup,
346 * and automatically transition the device into the deepest sleep state
347 * possible.
348 *
349 * The first goal is to enter Power_STANDBY; if that is not appropriate
350 * given current conditions (e.g., the sleep transition latency is
351 * greater than the time until the next scheduled Clock event), then
352 * the secondary goal is the IDLE_PD state; if that is disallowed (e.g.,
353 * if the Power_IDLE_PD_DISALLOW constraint is declared), then the policy
354 * will fallback and simply invoke wait-for-interrupt, to clock
355 * gate the CPU until the next interrupt.
356 *
357 * This policy is enabled and selected via the following application
358 * configuration steps:
359 *
360 * @p(code) 361 * Power.idle = true;
362 * Power.policyFunc = Power.standbyPolicy;
363 * @p 364 */
365 Void standbyPolicy();
366
367 /*!
368 * @_nodoc 369 * ======== defaultClockFunc ========
370 * Function for the Clock object dedicated for scheduling wakeups.
371 */
372 Void defaultClockFunc(UArg arg);
373
374 /*!
375 * @_nodoc 376 * ======== defaultNotifyTrapFunc ========
377 * The default function to be called when a notification client responds
378 * with any value other than Power_NOTIFYDONE.
379 *
380 * The default behavior of this function is to spin in an infinite loop.
381 */
382 Void defaultNotifyTrapFunc();
383
384 /*!
385 * @_nodoc 386 * ======== startFirstMeasurement ========
387 * Start the first RCOSC calibration measurement
388 */
389 Bool injectCalibration();
390
391 /*!
392 * @_nodoc 393 * ======== auxISR ========
394 * ISR for AUX combined interrupt for TDC (for RCOSC calibration)
395 */
396 Void auxISR(UArg arg);
397
398 /*!
399 * ======== getClockHandle ========
400 * Get the handle of the Clock object created for scheduling wakeups.
401 */
402 Clock.Handle getClockHandle();
403
404 /*!
405 * ======== doWFI ========
406 * A power policy function that invokes wait-for-interrupt (WFI)
407 * during idle time.
408 *
409 * This is the most basic power policy function, which will invoke
410 * WFI upon entry to the Idle loop. This is the default policy function
411 * that is invoked when CPU idling is enabled with the {@link #idle idle}
412 * configuration parameter:
413 *
414 * @p(code) 415 * Power.idle = true;
416 * @p 417 *
418 */
419 Void doWFI();
420
421 /*!
422 * ======== getConstraintInfo ========
423 * Get a bitmask representing the aggregate of constraints that have been
424 * declared.
425 *
426 * This function returns a bitmask indicating the constraints that are
427 * currently declared to the Power module (via previous calls to
428 * {@link #setConstraint Power_setConstraint()}). For each constraint
429 * (of type {@link #Constraint Power_Constraint}) that is currently
430 * declared, the corresponding bit in the bitmask will be set. For
431 * example, if two clients have declared Power_SB_DISALLOW, and one has
432 * declared Power_SB_VIMS_CACHE_RETAIN, then the returned bitmask
433 * will have the value: Power_SB_DISALLOW | Power_SB_VIMS_CACHE_RETAIN
434 *
435 * @b(returns) A bitmask representing all currently declared
436 * constraints
437 */
438 UInt32 getConstraintInfo();
439
440 /*!
441 * ======== getDependencyCount ========
442 * Get the count of dependencies that are currently declared upon a
443 * resource.
444 *
445 * This function returns the number of dependencies that are currently
446 * declared upon a resource.
447 *
448 * @param(resourceID) The resource identifier, as specified in the
449 * device-specific header file
450 *
451 * @b(returns) The number of dependencies currently declared upon this
452 * resourceID
453 */
454 UInt32 getDependencyCount(UInt8 resourceID);
455
456 /*!
457 * ======== getTransitionState ========
458 * Get the current Power module transition state.
459 *
460 * @b(returns) The current transition state, of type
461 * {@link #TransitionState Power_TransitionState}
462 */
463 TransitionState getTransitionState();
464
465 /*!
466 * ======== getTicksUntilWakeup ========
467 * Get the number of system ticks until the next scheduled wakeup event
468 *
469 * @b(returns) The number of system ticks (i.e.,
470 * {@link ti.sysbios.knl.Clock Clock} module) ticks
471 * until the next scheduled wakeup
472 */
473 UInt32 getTicksUntilWakeup();
474
475 /*!
476 * ======== getTransitionLatency ========
477 * Get the minimal transition latency for a sleep state, in units of
478 * system Clock ticks.
479 *
480 * Note that the reported latency is the device transition latency for
481 * the specified sleep state. This latency value does not include any
482 * additional software induced latency, for example, that due to
483 * notifications of the power transition to drivers.
484 *
485 * @param(sleepState) The {@link #SleepState sleepState} whose transition
486 * latency is to be reported (e.g., Power_STANDBY)
487 *
488 * @param(type) The {@link #LatencyType type} of latency to be
489 * reported
490 *
491 * @b(returns) The transition latency, in units of
492 * {@link ti.sysbios.knl.Clock Clock} ticks.
493 */
494 UInt32 getTransitionLatency(SleepState sleepState, LatencyType type);
495
496 /*!
497 * ======== getXoscStartupTime ========
498 * Get the estimated crystal oscillator startup time, in units of
499 * microseconds.
500 *
501 * @param(timeUntilWakeupInMs) The estimated time until the next wakeup
502 * event, in units of milliseconds
503 *
504 * @b(returns) The estimated crystal oscillator startup latency, in
505 * units of microseconds.
506 *
507 * @a(Note) The estimated time until wakeup is in units of milliseconds,
508 * but the the estimate crystal startup time is in microseconds.
509 */
510 UInt32 getXoscStartupTime(UInt32 timeUntilWakeupInMs);
511
512 /*!
513 * @_nodoc 514 * ======== isStableXOSC_HF ========
515 * Check if XOSC_HF has stabilized.
516 *
517 * @b(returns) TRUE if XOSC_HF has stabilized, FALSE if hasn't
518 * stabilized yet
519 */
520 Bool isStableXOSC_HF();
521
522 /*!
523 * ======== releaseConstraint ========
524 * Release a constraint that was previously declared with {@link 525 * #setConstraint Power_setConstraint()}.
526 *
527 * This function releases a constraint that was previously declared with
528 * {@link #setConstraint Power_setConstraint()}. For example, if a device
529 * driver is starting a transaction and wants to prohibit activation of
530 * the Power_STANDBY sleep mode, it uses {@link #setConstraint
531 * Power_setConstraint} to declare the constraint, before starting
532 * the transaction. When the transaction completes, the driver calls
533 * this function to release the constraint, and allow the power manager
534 * to once again transition into the Power_STANDBY sleep mode, if
535 * appropriate.
536 *
537 * @param(constraint) The constraint being released, of type {@link 538 * #Constraint Power_Constraint}
539 *
540 * @a(constraints) 541 * Power_releaseConstraint() must not be called more than
542 * Power_setConstraint() has been called for the same constraint. If
543 * asserts are enabled, one will be generated in this case.
544 */
545 Void releaseConstraint(Constraint constraint);
546
547 /*!
548 * ======== releaseDependency ========
549 * Release a dependency that had been previously declared with {@link 550 * #setDependency Power_setDependency()}.
551 *
552 * This function is the companion to {@link #setDependency
553 * Power_setDependency()}. If this release is for the last outstanding
554 * dependency upon the resource, the resource will be de-activated as part
555 * of this function call.
556 *
557 * @param(resourceID) The resource identifier, as specified in the
558 * device-specific header file
559 *
560 * @a(constraints) 561 * Power_releaseDependency() must not be called more than
562 * Power_setDependency() has been called for the same resource. If
563 * asserts are enabled, one will be generated in this case.
564 */
565 Void releaseDependency(UInt8 resourceID);
566
567 /*!
568 * ======== registerNotify ========
569 * Register a function to be called upon a specific power event.
570 *
571 * This function registers a function to be called when a
572 * Power event occurs. Registrations and the corresponding notifications
573 * are processed in first-in-first-out (FIFO) order. The function
574 * registered must behave as described below.
575 *
576 * The pNotifyObj parameter is a pointer to a pre-allocated, opaque
577 * object that will be used by Power to support the notification. This
578 * object could be dynamically allocated, or declared as a global object.
579 * Power_registerNotify() will properly initialized the object's fields as
580 * appropriate; the caller just needs to provide a pointer to this
581 * pre-existing object.
582 *
583 * The eventType parameter identifies the type of power event for which
584 * the notify function being registered is to be called. This parameter
585 * is treated as a bitmask, so multiple event types can be registered for
586 * a common function. The event types are enumerated as {@link #Event
587 * Power_Event}. For example, to call the specified function when
588 * both the entering standby and the awake from standby events occur,
589 * eventType should be specified as:
590 * (Power_ENTERING_STANDBY | Power_AWAKE_STANDBY)
591 *
592 * The clientArg parameter is an arbitrary argument to be passed to the
593 * client upon notification. This argument may allow one notify function
594 * to be used by multiple instances of a driver (that is, the clientArg
595 * can be used to identify the instance of the driver that is being
596 * notified).
597 *
598 * The notifyFxn parameter specifies the function to call when the
599 * specified Power event occurs. The notifyFxn must implement
600 * the following signature:
601 *
602 * status = notifyFxn(eventType, clientArg);
603 *
604 * Where: eventType (type of {@link #Event Power_Event}) is the event
605 * being signalled, and clientArg is the abitrary argument specified
606 * by the client at registration. Note that multipe types of events
607 * can be specified when registering the notification callback function,
608 * but when the callback function is actually called by Power, only a
609 * single eventType will be specified for the callback (i.e., the current
610 * event).
611 *
612 * The client notification function being registered must return one of the
613 * following constants as a status value, of type {@link #NotifyResponse
614 * Power_NotifyResponse}: Power_NOTIFYDONE if the client processed the
615 * notification function successfully, or Power_NOTIFYERROR if the
616 * notification cannot be processed (e.g., if an internal client error
617 * occurs).
618 *
619 * @param(pNotifyObj) The notify object to be used for queuing
620 * of the notification callback function
621 *
622 * @param(eventTypes) The type or types of {@link #Event Power_Event} to
623 * be notified of
624 *
625 * @param(notifyFxn) The callback function Power should call to notify
626 * the client of the event
627 *
628 * @param(clientArg) A client-defined argument to pass with the notifyFxn
629 * call
630 *
631 * @param(arg) For future use, should be specified as:
632 * NULL
633 *
634 * @b(returns) Power_SOK if the registration succeeded
635 *
636 * @b(returns) Power_EINVALIDPOINTER if either pNotifyObj or notifyFxn
637 * were NULL
638 *
639 */
640 Status registerNotify(NotifyObj * pNotifyObj, UInt32 eventTypes,
641 Fxn notifyFxn, UArg clientArg, UArg arg);
642
643 /*!
644 * ======== setConstraint ========
645 * Declare an operational constraint.
646 *
647 * Before taking certain actions, Power checks to see if the requested
648 * action would conflict with a client-declared constraint. If the
649 * action does conflict, Power will not proceed with the request.
650 * This is the function that allows clients to declare their constraints
651 * with Power.
652 *
653 * It is critical that clients call {@link #releaseConstraint
654 * Power_releaseConstraint()} when operational constraints no longer
655 * exists. Otherwise, Power may be left unnecessarily restricted from
656 * activating power savings.
657 *
658 * @param(constraint) The constraint being declared, of type {@link 659 * #Constraint Power_Constraint}
660 */
661 Void setConstraint(Constraint constraint);
662
663 /*!
664 * ======== setDependency ========
665 * Declare a dependency upon a power-manageable resource.
666 *
667 * This function declares a dependency upon a resource. If the resource
668 * had been inactive, it will be activated during this function call.
669 *
670 * This function is the companion to {@link #releaseDependency
671 * Power_releaseDependency()}.
672 *
673 * @param(resourceID) The resource identifier, as specified in the
674 * device-specific header file (for example,
675 * PERIPH_UART0, as defined in PowerCC2650.h)
676 * @a(Note) 677 * When a dependency is declared upon a resource for the first time, the
678 * resource will be activated before the call to Power_setDependency()
679 * returns to the caller. There is only one exception to this rule:
680 * the XOSC_HF resource for CC26xx. The latency to startup the crystal
681 * is much longer than that for other resources. To avoid blocking in
682 * Power_setDependency() for this duration, for the XOSC_HF resource
683 * only, Power_setDependency() will return quickly, after initiating the
684 * activation of XOSC_HF. Once the switchover to the XOSC_HF
685 * happens, notifications will be sent to clients registered for the
686 * Power_XOSC_HF_SWITCHED event.
687 *
688 * Power_setDependency() will return a Boolean status to indicate if
689 * the resource is active as the function is initiating a return to the
690 * caller. For all resources other than XOSC_HF, the return status will
691 * always be TRUE, because the resource will be active before the return
692 * to the caller. For XOSC_HF, the return status may be TRUE if the
693 * XOSC_HF is already active. For example, if XOSC_HF was already
694 * activated with an earlier call to Power_setDependency(XOSC_HF).
695 * If the return status is FALSE, this indicates to the caller that
696 * XOSC_HF hadn't been switched by the time the function initiated a
697 * return, and that the caller should wait for the Power_XOSC_HF_SWITCHED
698 * event notification before proceeding to the work that requires XOSC_HF
699 * to be active.
700 *
701 * The recommended sequence for a caller to activate XOSC_HF is:
702 *
703 *
704 * 1) Caller registers for a Power_XOSC_HF_SWITCHED notification.
705 * For example, the specified callback function might set a global
706 * flag, which the caller can check to see if the notification
707 * occurred.
708 *
709 * 2) Caller invokes: status = Power_setDependency(XOSC_HF);
710 *
711 *
712 * 3) Caller checks status to see if XOSC_HF is active yet
713 *
714 *
715 * - If status is TRUE, XOSC_HF is active, caller should proceed,
716 * and NOT wait for a Power_XOSC_HF_SWITCHED notification
717 *
718 * - Else, XOSC_HF wasn't activated yet, caller needs to wait
719 * until the Power_XOSC_HF_SWITCHED event has been signaled.
720 * Note that depending upon timing, the event may have been
721 * signaled between the time the return status was determined
722 * within Power_setDependency() and the time the caller
723 * checks the return status. The key point is that, when
724 * the return status is FALSE, the Power_XOSC_HF_SWITCHED
725 * notification WILL be sent (once the XOSC_HF is switched),
726 * and the caller should wait for this notification before
727 * proceeding with any work that requires XOSC_HF to be active.
728 *
729 * @b(returns) TRUE if resource is active
730 *
731 * @b(returns) FALSE if resource was not yet active when the function
732 * return was initiated
733 *
734 * @a(constraints) 735 * For the XOSC_HF resource (described above), the caller MUST wait for
736 * XOSC_HF activation to complete before calling
737 * Power_releaseDependency(XOSC_HF).
738 */
739 Bool setDependency(UInt8 resourceID);
740
741 /*!
742 * ======== shutdown ========
743 * Put the device into the SHUTDOWN state.
744 *
745 * This function will transition the device into the SHUTDOWN state.
746 * Before the actual device transtion is initiated, notifications will
747 * be sent to any clients who've registered for the
748 * Power_ENTERING_SHUTDOWN event (via {@link #registerNotify
749 * Power_registerNotify()}). Once notifications have been completed, the
750 * device shutdown will commence.
751 *
752 * If the device is successfully transitioned to SHUTDOWN, this function
753 * call will never return. Upon wakeup, the device and application will
754 * be rebooted. If the transition to SHUTDOWN is not successful, one of
755 * the error codes listed above will be returned.
756 *
757 * @param(arg) Reserved for future use; currently unused
758 *
759 * @b(returns) Power_EBUSY if Power is currently busy with another
760 * transition
761 *
762 * @b(returns) Power_ECHANGE_NOT_ALLOWED if SHUTDOWN is disallowed
763 * due to the Power_SD_DISALLOW constraint having been
764 * declared
765 *
766 * @b(returns) Power_EFAIL if a notification error occurred
767 *
768 * @a(Note) 769 * This function will not prepare I/O pins for the device
770 * shutdown state. The application needs to do the appropriate
771 * I/O preparation before calling this API.
772 */
773 Status shutdown(UArg arg);
774
775 /*!
776 * ======== sleep ========
777 * Put the CPU into a sleep state.
778 *
779 * This function transitions the device into and out of a sleep state.
780 * The function returns to the caller when the device is awake again.
781 *
782 * @param(sleepState) The sleep state to be entered, of type
783 * {@link #sleepState Power_sleepState}
784 *
785 * @param(arg0) Reserved for future use; currently unused
786 *
787 * @param(arg1) Reserved for future use; currently unused
788 *
789 * @b(returns) Power_SOK upon success, the device is awake
790 *
791 * @b(returns) Power_EBUSY if Power is currently busy with another
792 * transition
793 *
794 * @b(returns) Power_EFAIL if a general failure occurred and the
795 * device was not transitioned into sleep
796 *
797 * @a(Note) 798 * Power_sleep() is intended to be called from a Power Policy
799 * implementation function. This API is not normally called directly
800 * by an application.
801 *
802 * @a(constraints) 803 * Power_sleep() does not check the constraints that might prohibit a
804 * sleep transition. The caller of Power_sleep() must validate the
805 * transition versus active constraints, prior to calling Power_sleep().
806 */
807 Status sleep(SleepState sleepState, UArg arg0, UArg arg1);
808
809 /*!
810 * @_nodoc 811 * ======== switchXOSC_HF ========
812 * Switch to enable XOSC_HF.
813 */
814 Void switchXOSC_HF();
815
816 /*!
817 * ======== unregisterNotify ========
818 * Unregister for Power event notifications.
819 *
820 * This function unregisters for event notifications that were previously
821 * registered with {@link #registerNotify Power_registerNotify()}.
822 *
823 * @param(pNotifyObj) The notification object that was previously
824 * used with {@link #registerNotify
825 * Power_registerNotify()} to register for
826 * event notifications
827 */
828 Void unregisterNotify(NotifyObj * pNotifyObj);
829
830
831 /*! @_nodoc */
832 @XmlDtd
833 metaonlystruct ModuleView {
834 String ConstraintsMask;
835 };
836
837 /*! @_nodoc */
838 @Facet
839 metaonlyconfig ViewInfo.Instance rovViewInfo =
840 ViewInfo.create({
841 viewMap: [
842 [
843 'Module',
844 {
845 type: ViewInfo.MODULE,
846 viewInitFxn: 'viewInitModule',
847 structName: 'ModuleView'
848 }
849 ],
850 ]
851 });
852
853 /*!
854 * @_nodoc 855 * ======== idleCPU ========
856 * Function used to automatically idle the CPU in the Idle loop.
857 *
858 * When the 'idle' configuration parameter is set, this function will
859 * be added to the list of Idle loop functions. When called from the
860 * Idle loop, it will invoke the wait for interrupt (WFI) instruction,
861 * to idle the CPU until the next interrupt occurs.
862 */
863 Void idleCPU();
864
865 internal:
866
867 /*
868 * ======== abs ========
869 */
870 Int abs(Int i);
871
872 /*
873 * ======== calibrateRcoscHf1 ========
874 */
875 Void calibrateRcoscHf1(Int32 tdcResult);
876
877 /*
878 * ======== calibrateRcoscHf2 ========
879 */
880 Void calibrateRcoscHf2(Int32 tdcResult);
881
882 /*
883 * ======== doCalibrate ========
884 */
885 Void doCalibrate();
886
887 /*
888 * ======== getTdcSemaphore ========
889 */
890 Bool getTdcSemaphore();
891
892 /*
893 * ======== initateCalibration ========
894 */
895 Bool initiateCalibration();
896
897 /*
898 * ======== isDependencyActive ========
899 */
900 Bool isDependencyActive(UInt8 resourceID);
901
902 /*
903 * ======== LF_clockFunc ========
904 */
905 Void LF_clockFunc(UArg arg);
906
907 /*
908 * ======== NOP ========
909 */
910 UInt NOP(UInt action);
911
912 /*
913 * ======== notify ========
914 */
915 Status notify(Event eventType);
916
917 /*
918 * ======== RCOSC_clockFunc ========
919 */
920 Void RCOSC_clockFunc(UArg arg);
921
922 /*
923 * ======== RFCORECLKS ========
924 */
925 UInt RFCORECLKS(UInt action);
926
927 /*
928 * ======== scaleRndInf ========
929 */
930 Int32 scaleRndInf(Int32 x);
931
932 /*
933 * ======== serviceNotifyQ ========
934 */
935 NotifyResponse serviceNotifyQ(Event eventType);
936
937 /*
938 * ======== updateSubSecInc ========
939 */
940 Void updateSubSecInc(UInt32 tdcResult);
941
942 /*
943 * ======== XOSC_HF ========
944 */
945 UInt XOSC_HF(UInt action);
946
947 /*
948 * ======== XOSC_HF_xoscClockFunc ========
949 */
950 Void XOSC_HF_clockFunc(UArg arg);
951
952 /*
953 * ======== Module_State ========
954 */
955 struct Module_State {
956 UInt32 constraintsMask;
957 Queue.Object notifyQ; /* event notification queue */
958 Clock.Object clockObj; /* Clock object for scheduling wakeups */
959 Clock.Object xoscClockObj; /* Clock object for XOSC_HF switching */
960 Clock.Object lfClockObj; /* Clock object for LF clock check */
961 Clock.Handle calClockHandle; /* Clock object for RCOSC calibration */
962 Int32 nDeltaFreqCurr; /* RCOSC calibration variable */
963 Int32 nCtrimCurr; /* RCOSC calibration variable */
964 Int32 nCtrimFractCurr; /* RCOSC calibration variable */
965 Int32 nCtrimNew; /* RCOSC calibration variable */
966 Int32 nCtrimFractNew; /* RCOSC calibration variable */
967 TransitionState state; /* current transition state */
968 Bool xoscPending; /* is XOSC_HF activation in progress? */
969 Bool calLF; /* calibrate RCOSC_LF? */
970 UInt8 hwiState; /* calibration AUX ISR state */
971 Bool busyCal; /* already busy calibrating */
972 UInt8 calStep; /* current calibration step */
973 Bool firstLF; /* is this first LF calibration? */
974 volatile UInt8 * constraintCounts; /* constraint counts array */
975 volatile UInt8 * resourceCounts; /* to resource ref counts array */
976 ResourceRecord * resourceDB;/* resource database */
977 Fxn * resourceHandlers; /* resource special handler functions */
978 }
979 }