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