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
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 /*! Idle the CPU during idle time? Default is false. */
321 metaonly config Bool idleCpu = false;
322
323 /*! Idle function. Default is Power_idleStopClock. */
324 metaonly config FuncPtr idleFunc = Power.idleStopClock;
325
326 /*! Enable resource tracking? Default is false. */
327 config Bool trackResources = false;
328
329 /*! Enable voltage and frequency (V/F) scaling? Default is false. */
330 config Bool enableScaling = false;
331
332 /*! Initial CPU domain setpoint. Default is 2. */
333 config UInt initialSetpointCPU = 2;
334
335 /*! Initial peripheral (PER) domain setpoint. Default is 0. */
336 config UInt initialSetpointPER = 0;
337
338 /*!
339 * Move to initial setpoints during program initialization?
340 * Default is false.
341 */
342 metaonly config Bool moveToSetpoints = false;
343
344 /*! Scale voltage along with frequency? Default is true. */
345 metaonly config Bool scaleVoltage = true;
346
347 /*! Wait while voltage is scaling downward? Default is true. */
348 metaonly config Bool waitVoltage = true;
349
350 /*! Select the PMI control library */
351 metaonly config pmiLib pmiControlLib = pmiLib_evm6748;
352
353 /*! Select the PSCL configuration library */
354 metaonly config psclLib psclConfigLib = psclLib_evm6748;
355
356 /*!
357 * ======== changeSetpoint ========
358 * Initiate a change to the V/F setpoint of the CPU, or the peripheral
359 * domain.
360 *
361 * Power_changeSetpoint() changes the voltage and frequency of a
362 * scalable domain.
363 *
364 * The domain parameter indicates the relevant scaling domain. The
365 * domains that can be scaled vary by platform, and are enumerated as
366 * Power_Domain. For example, for the TMS320C6748, there are two
367 * scalable domains: the CPU domain (Power_CPU) and the peripheral
368 * domain (Power_PER).
369 *
370 * The newSetpoint parameter is a numeric value that indexes into a table
371 * of frequency/voltage pairs, as defined by the underlying scaling
372 * configuration library.
373 *
374 * The notifyTimeout parameter is the maximum amount of time (in system
375 * Clock ticks) to wait for registered notification functions (set by
376 * Power_registerNotify()) to respond to a delayed completion, before
377 * declaring failure and returning Power_ETIMEOUT.
378 *
379 * For example, if notifyTimeout is set to 200, Power_changeSetpoint()
380 * waits up to 200 ticks (typically 200 milliseconds) before declaring
381 * that function has failed to respond. Power uses notifyTimeout for each
382 * type of notification. For example, if notification functions are
383 * registered for both before and after setpoint changes,
384 * Power_changeSetpoint() waits up to notifyTimeout on each type of
385 * notification.
386 *
387 * All registered notification functions are called from the context of
388 * Power_changeSetpoint().
389 *
390 * The application should treat return values of Power_ETIMEOUT or
391 * Power_EFAIL as critical system failures. These values indicate the
392 * notification client is taking too long or is unresponsive, and the
393 * system is in an unknown state.
394 *
395 * Power_changeSetpoint() disables Swi and Task scheduling when it
396 * begins making a change. However, Hwis may run during the notification
397 * process. After the setpoint has been changed, Swi and Task scheduling
398 * are re-enabled, and a context switch occurs only if some other thread
399 * has since been made ready to run.
400 *
401 * @param(domain) The relevant scaling domain (Power_CPU or Power_PER)
402 *
403 * @param(newSetpoint) The new V/F setpoint to be scaled to
404 *
405 * @param(notifyTimeout) The maximum time (in Clock ticks) to wait for
406 * client notifications to complete
407 *
408 * @b(returns) Power_SOK if the operation succeeded and the new
409 * setpoint is in effect
410 *
411 * @b(returns) Power_EFAIL if a general failure occurred; the
412 * requested transition did not occur
413 *
414 * @b(returns) Power_ENOTIMPLEMENTED if V/F scaling is not implemented
415 * on this platform
416 *
417 * @b(returns) Power_ENOTSUPPORTED if the operation failed because
418 * a client registered a constraint with Power indicating
419 * that it cannot support the requested setpoint
420 *
421 * @b(returns) Power_EOUTOFRANGE if the operation failed because
422 * the domain or newSetpoint parameter is not a valid value
423 * for the platform
424 *
425 * @b(returns) Power_ETIMEOUT if the operation failed because
426 * a registered notification function did not complete its
427 * processing within the specified notifyTimeout
428 *
429 * @b(returns) Power_EBUSY if the operation failed because the
430 * operation cannot be performed at this time; Power is
431 * busy processing a previous request
432 *
433 * @b(returns) Power_EINITFAILURE if there was a previous failure when
434 * V/F scaling support was being initialized; V/F scaling
435 * is unavailable
436 *
437 * @a(constraints)
438 * Power_changeSetpoint() cannot be called from a Hwi or main()
439 *
440 * Power_changeSetpoint() can be called from a Swi only if notifyTimeout
441 * is zero
442 */
443 @DirectCall
444 Status changeSetpoint(Domain domain, UInt newSetpoint, UInt notifyTimeout);
445
446 /*!
447 * ======== configure ========
448 * Set new configuration parameters for Power.
449 *
450 * Power_configure() specifies new configuration properties for the Power
451 * module. It overrides those specified in the static configuration.
452 *
453 * Configuration parameters are specified via a Power_Attrs structure.
454 * In this structure, 'scaleVoltage' indicates whether Power should scale
455 * voltages during setpoint changes, and when switching to sleep modes that
456 * support voltage reduction. It corresponds to the {@link #scaleVoltage}
457 * configuration property. If 'scaleVoltage' is TRUE, the voltage is
458 * scaled down if possible when going to a lower frequency or activating
459 * sleep modes. If 'scaleVoltage' is FALSE, the voltage is not scaled
460 * lower. The voltage is always scaled up if the new (destination)
461 * setpoint frequency is higher than that supported at the current voltage.
462 *
463 * In the Power_attrs structure, the 'waitForVoltageScale' flag indicates
464 * whether Power should wait for a down-voltage transition to complete
465 * before returning from Power_changeSetpoint(). It corresponds to the
466 * {@link #waitVoltage} configuration property. (Such transition times can
467 * be long, and they typically depend upon power supply load.) Currently,
468 * it is recommended that this property always be TRUE. Note that the
469 * Power module always waits during up-voltage transitions; this is
470 * required to avoid overclocking the device.
471 *
472 * @param(attrs) An {@link #Attrs} structure defining new
473 * configuration parameters
474 *
475 * @b(returns) Power_SOK if the configuration was changed
476 *
477 * @b(returns) Power_EINVALIDVALUE if the change failed because one of
478 * the attributes is invalid
479 */
480 @DirectCall
481 Status configure(Attrs attrs);
482
483 /*!
484 * ======== getCapabilities ========
485 * Get info on Power's capabilities on the current platform.
486 *
487 * The capsMask parameter should point to the location where
488 * Power_getCapabilities() should write a bitmask that defines the
489 * capabilities.
490 *
491 * You can use the following constants to check for capabilities
492 * in the bitmask:
493 *
494 * Power_CRESOURCETRACKING - Power supports dynamic resource tracking
495 *
496 * Power_CVFSCALING - Power supports voltage and frequency scaling
497 *
498 * @param(capsMask) Location of a bitmask to be written with capabilities
499 * flags
500 *
501 * @b(returns) Power_SOK if the operation succeeded
502 *
503 * @b(returns) Power_EINVALIDPOINTER if the operation failed because
504 * capsMask was NULL
505 */
506 @DirectCall
507 Status getCapabilities(UInt * capsMask);
508
509 /*!
510 * ======== getConstraintInfo ========
511 * Get info on the aggregate of constraints that have been registered with
512 * Power.
513 *
514 * Power_getConstraintInfo() returns information about constraints that are
515 * currently registered with the Power module, via previous calls to
516 * Power_registerConstraint().
517 *
518 * The type parameter identifies the type of constraint being queried. The
519 * constraint types vary by platform, and are enumerated as
520 * Power_Constraint. Currently the following are supported:
521 *
522 * Power_DISALLOWEDSLEEPSTATE_MASK - Sleep states that should
523 * not be activated.
524 *
525 * Power_DISALLOWED_CPU_SETPOINT_MASK - CPU setpoints that should not
526 * be activated.
527 *
528 * Power_DISALLOWED_PER_SETPOINT_MASK - Peripheral setpoints that
529 * should not be activated.
530 *
531 * Power_getContraintInfo() returns a value that is the aggregate of all
532 * constraints that are currently registered. For example, if one Power
533 * client disallowed the sleep state Power_SLEEP, and a different client
534 * disallowed the sleep state Power_DEEPSLEEP, the returned value will
535 * be (Power_SLEEP | Power_DEEPSLEEP).
536 *
537 * @param(type) Type of constraint
538 *
539 * @param(value) Location to be written with aggregate of constraints
540 *
541 * @b(returns) Power_SOK if the operation succeeded
542 *
543 * @b(returns) Power_EINVALIDVALUE if the operation failed because
544 * type does not correspond to a supported constraint type
545 *
546 * @b(returns) Power_EINVALIDPOINTER if the operation failed because
547 * the value parameter was NULL
548 *
549 */
550 @DirectCall
551 Status getConstraintInfo(Constraint type, UArg *value);
552
553 /*!
554 * ======== getCurrentSetpoint ========
555 * Get the current setpoint in effect.
556 *
557 * Power_getCurrentSetpoint() returns the V/F scaling setpoint currently in
558 * use for the specified scaling domain.
559 *
560 * The domain parameter indicates the relevant scaling domain. The
561 * domains that can be scaled vary by platform, and are enumerated as
562 * Power_Domain.
563 *
564 * The setpoint parameter should point to the location where
565 * Power_getCurrentSetpoint() should write the current setpoint.
566 *
567 * @param(domain) The scaling domain being queried (Power_CPU or
568 * Power_PER)
569 *
570 * @param(setpoint) Location to write the current setpoint
571 *
572 * @b(returns) Power_SOK if the operation succeeded
573 *
574 * @b(returns) Power_EINVALIDPOINTER if the operation failed because
575 * the setpoint parameter was NULL
576 *
577 * @b(returns) Power_EINVALIDVALUE if the operation failed because the
578 * domain parameter was invalid
579 *
580 * @b(returns) Power_EINITFAILURE if there was a previous failure when
581 * V/F scaling support was being initialized; V/F scaling
582 * is unavailable
583 *
584 * @b(returns) Power_ENOTSUPPORTED if the operation failed because
585 * V/F scaling support is not enabled
586 *
587 * @a(constraints)
588 * If a call to Power_getCurrentSetpoint() is made during a change to the
589 * current setpoint, the value Power_getCurrentSetpoint() returns may
590 * be the old setpoint and not the new setpoint
591 *
592 */
593 @DirectCall
594 Status getCurrentSetpoint(Domain domain, UInt * setpoint);
595
596 /*!
597 * ======== getDependencyCount ========
598 * Get the count of dependencies that are currently declared on a resource.
599 *
600 * Power_getDependencyCount() returns the number of dependencies that
601 * are currently declared on a resource. Normally this corresponds to the
602 * number of times Power_setDependency() has been called for the
603 * resource, minus the number of times Power_releaseDependency() has
604 * been called for the same resource.
605 *
606 * On some platforms, early boot code may enable individual resources
607 * before Power initializes. To ensure proper state synchronization in
608 * this case, Power queries individual resource states as the Power module
609 * initializes. So, it is possible for the returned "count" value to be 1,
610 * even if Power_setDependency() has not been called by the application.
611 *
612 * Resources are enumerated as Power_Resource.
613 *
614 * @param(resourceID) The resource identifier
615 *
616 * @param(count) Location to write the resource's dependency count
617 *
618 * @b(returns) Power_SOK if the operation succeeded
619 *
620 * @b(returns) Power_EINVALIDPOINTER if the operation failed because
621 * the count parameter was NULL
622 *
623 * @b(returns) Power_EINVALIDVALUE if the operation failed because
624 * Power cannot control this resource
625 *
626 * @b(returns) Power_ENOTSUPPORTED if the operation failed because
627 * resource tracking is not enabled
628 *
629 * @b(returns) Power_EOUTOFRANGE if the specified resourceID is
630 * outside the range of valid resource IDs
631 */
632 @DirectCall
633 Status getDependencyCount(Resource resourceID, UInt * count);
634
635 /*!
636 * ======== getNumSetpoints ========
637 * Get the number of setpoints supported on the platform.
638 *
639 * Power_getNumSetpoints() returns the number of setpoints supported for
640 * a specified domain.
641 *
642 * The domain parameter indicates the relevant scaling domain. The
643 * domains that can be scaled vary by platform, and are enumerated as
644 * Power_Domain.
645 *
646 * @param(domain) The scaling domain being queried (Power_CPU or
647 * Power_PER)
648 *
649 * @param(numberSetpoints) Location to write the number of supported
650 * setpoints
651 *
652 * @b(returns) Power_SOK if the operation succeeded
653 *
654 * @b(returns) Power_EINVALIDPOINTER if the operation failed because
655 * the numberSetpoints parameter was NULL
656 *
657 * @b(returns) Power_EINVALIDVALUE if the operation failed because the
658 * domain parameter was invalid
659 *
660 * @b(returns) Power_EINITFAILURE if there was a previous failure when
661 * V/F scaling support was being initialized; V/F scaling
662 * is unavailable
663 *
664 * @b(returns) Power_ENOTSUPPORTED if the operation failed because
665 * V/F scaling support is not enabled
666 *
667 */
668 @DirectCall
669 Status getNumSetpoints(Domain domain, UInt * numberSetpoints);
670
671 /*!
672 * ======== getSetpointInfo ========
673 * Get the frequency and core voltage for a setpoint.
674 *
675 * Power_getSetpointInfo() returns the frequency and voltage for a given
676 * setpoint.
677 *
678 * The domain parameter indicates the relevant scaling domain for which
679 * the setpoint information is to be retrieved. The domains that can be
680 * scaled vary by platform, and are enumerated as Power_Domain.
681 *
682 * @param(domain) The scaling domain being queried (Power_CPU or
683 * Power_PER)
684 *
685 * @param(setpoint) The setpoint to be queried
686 *
687 * @param(frequency) Location to write the frequency (in kHz) of the
688 * specified setpoint
689 *
690 * @param(voltage) Location to write the voltage (in millivolts) of the
691 * specified setpoint
692 *
693 * @b(returns) Power_SOK if the operation succeeded
694 *
695 * @b(returns) Power_EINVALIDPOINTER if the operation failed because
696 * the frequency or votage parameter was NULL
697 *
698 * @b(returns) Power_EINVALIDVALUE if the operation failed because the
699 * domain parameter was invalid
700 *
701 * @b(returns) Power_EINITFAILURE if there was a previous failure when
702 * V/F scaling support was being initialized; V/F scaling
703 * is unavailable
704 *
705 * @b(returns) Power_ENOTSUPPORTED if the operation failed because
706 * V/F scaling support is not enabled
707 *
708 * @b(returns) Power_EOUTOFRANGE if the operation failed because
709 * the setpoint parameter is out of range of valid
710 * setpoints for the specified domain
711 */
712 @DirectCall
713 Status getSetpointInfo(Domain domain, UInt setpoint, UInt *frequency,
714 UInt *voltage);
715
716 /*!
717 * ======== getTransitionLatency ========
718 * Get the latency to scale from one setpoint to another setpoint.
719 *
720 * Power_getTransitionLatency() retrieves the latencies (times required)
721 * in microseconds to scale from a specific setpoint to another specific
722 * setpoint.
723 *
724 * The domain parameter should indicate the relevant scaling domain.
725 * The initialSetpoint parameter should specify the setpoint from which the
726 * transition would start. The finalSetpoint parameter should specify the
727 * setpoint at which the transition would end.
728 *
729 * The frequencyLatency parameter should point to the location where
730 * Power_getTransitionLatency() should write the time required to change
731 * the frequency from that of the initialSetpoint to that of the
732 * finalSetpoint, in microseconds.
733 *
734 * Similarly, the voltageLatency should point to the location where
735 * Power_getTransitionLatency() should write the time required to change
736 * the voltage from that of the initialSetpoint to that of the
737 * finalSetpoint, in microseconds.
738 *
739 * When frequency and voltage are scaled together, the total latency is the
740 * sum of the frequency scaling latency and the voltage scaling latency.
741 *
742 * Note that the time required to change a setpoint may not be
743 * deterministic (depending upon the hardware characteristics, the
744 * underlying software implementation, and the specific V/F swing), but it
745 * is bounded by the value returned by Power_getTransitionLatency().
746 *
747 * @param(domain) The relevant scaling domain (Power_CPU or Power_PER)
748 *
749 * @param(initialSetpoint) The setpoint to be scaled from
750 *
751 * @param(finalSetpoint) The setpoint to be scaled to
752 *
753 * @param(frequencyLatency) Location to write the frequency transition
754 * latency (in microseconds) from that of the
755 * initialSetpoint to that of the finalSetpoint
756 *
757 * @param(voltageLatency) Location to write the voltage transition
758 * latency (in microseconds) from that of the
759 * initialSetpoint to that of the finalSetpoint
760 *
761 * @b(returns) Power_SOK if the operation succeeded
762 *
763 * @b(returns) Power_EFAIL if a general failure occurred
764 *
765 * @b(returns) Power_EINVALIDPOINTER if the operation failed because
766 * the frequencyLatency or votageLatency parameter was NULL
767 *
768 * @b(returns) Power_EINVALIDVALUE if the operation failed because the
769 * domain, initialSetpoint, or finalSetpoint value was
770 * invalid
771 *
772 * @b(returns) Power_EINITFAILURE if there was a previous failure when
773 * V/F scaling support was being initialized; V/F scaling
774 * is unavailable
775 *
776 * @b(returns) Power_ENOTIMPLEMENTED if the operation failed because
777 * V/F scaling is not supported
778 */
779 @DirectCall
780 Status getTransitionLatency(Domain domain, UInt initialSetpoint,
781 UInt finalSetpoint, UInt *frequencyLatency, UInt *voltageLatency);
782
783 /*!
784 * ======== registerConstraint ========
785 * Register an operational constraint with Power.
786 *
787 * Before taking certain actions, Power checks to see if the requested
788 * action would conflict with a client-registered constraint. If the
789 * action does conflict, Power will not proceed with the request.
790 * Power_registerConstraint() is the API that allows clients to register
791 * their constraints with Power.
792 *
793 * The type parameter identifies the type of constraint being registered.
794 * The constraint types vary by platform, and are enumerated as
795 * Power_Constraint. Currently the following are supported:
796 *
797 * Power_DISALLOWEDSLEEPSTATE_MASK - Sleep states that should
798 * not be activated.
799 *
800 * Power_DISALLOWED_CPU_SETPOINT_MASK - CPU setpoints that should not
801 * be activated.
802 *
803 * Power_DISALLOWED_PER_SETPOINT_MASK - Peripheral setpoints that
804 * should not be activated.
805 *
806 * The Power_DISALLOWEDSLEEPSTATE_MASK is a bitmask of the
807 * sleep states that can be activated via Power_sleepDSP(). For the
808 * TMS320C6748, the states are identified via a combination of the
809 * following bitmask values: Power_STANDBY, Power_SLEEP, and
810 * Power_DEEPSLEEP.
811 *
812 * The Power_DISALLOWED_CPU_SETPOINT_MASK is a bitmask of
813 * setpoints that the CPU should not be transitioned to. For example, if a
814 * driver won't operate properly below a specific CPU performance level, it
815 * can register the lower performance levels via the setpoint mask.
816 * Setpoint IDs are zero-based, with a lower index representing a lower
817 * performance level. They are represented right-justified in the bitmask.
818 *
819 * For example, to disallow setpoint "0", the mask is "0x1". To disallow
820 * the lowest five setpoints the mask value is "0x1F".
821 *
822 * The Power_DISALLOWED_PER_SETPOINT_MASK performs the
823 * same function as the Power_DISALLOWED_CPU_SETPOINT_MASK,
824 * but corresponds to scaling of the peripheral domain. The bitmask follows
825 * the same format; setpoints are zero-based and have right-justified bit
826 * positions, starting with "0x1".
827 *
828 * It is important that clients call Power_unregisterConstraint() when the
829 * operational constraint no longer exists. Otherwise, Power may be left
830 * unnecessarily restricted from activating power savings.
831 *
832 * @param(type) Type of constraint
833 *
834 * @param(value) A constraint type-specific mask
835 *
836 * @param(handle) Location to write the resulting constraint handle
837 * (which is used for unregistering the constraint)
838 *
839 * @b(returns) Power_SOK if the operation succeeded
840 *
841 * @b(returns) Power_EFAIL if the registration failed due to a memory
842 * allocation failure
843 *
844 * @b(returns) Power_EINVALIDVALUE if the operation failed because
845 * type does not correspond to a supported constraint type
846 *
847 * @b(returns) Power_EINVALIDPOINTER if the operation failed because
848 * the handle parameter was NULL
849 *
850 * @a(constraints)
851 * Power_registerConstraint() cannot be called from a Swi or Hwi, because
852 * it allocates memory, and this may incur a context switch.
853 *
854 */
855 @DirectCall
856 Status registerConstraint(Constraint type, UArg value,
857 ConstraintHandle *handle);
858
859 /*!
860 * ======== registerNotify ========
861 * Register a function to be called on a specific power event.
862 *
863 * Power_registerNotify() registers a function to be called when a specific
864 * Power event occurs. Registrations and the corresponding notifications
865 * are processed in first-in-first-out (FIFO) order. The function
866 * registered must behave as described below.
867 *
868 * The eventType parameter identifies the type of power event for which the
869 * notify function being registered is to be called. The eventType
870 * parameter can vary by platform, and is enumerated as Power_Event. For
871 * example, on the TMS320C6748 this parameter may have one of the
872 * following values:
873 *
874 * Power_PENDING_CPU_SETPOINTCHANGE - The CPU domain V/F setpoint is
875 * about to change
876 *
877 * Power_DONE_CPU_SETPOINTCHANGE - The pending CPU setpoint change has
878 * now completed
879 *
880 * Power_PENDING_PER_SETPOINTCHANGE - The peripheral domain V/F
881 * setpoint is about to change
882 *
883 * Power_DONE_PER_SETPOINTCHANGE - The pending peripheral setpoint
884 * change has now completed
885 *
886 * Power_GOINGTOSTANDBY - The DSP is going to STANDBY state
887 *
888 * Power_AWAKEFROMSTANDBY - The DSP has awoken from STANDBY
889 *
890 * Power_GOINGTOSLEEP - The DSP is going to SLEEP state
891 *
892 * Power_AWAKEFROMSLEEP - The DSP has awoken from SLEEP
893 *
894 * Power_GOINGTODEEPSLEEP - The DSP is going to DEEPSLEEP state
895 *
896 * Power_AWAKEFROMDEEPSLEEP - The DSP has awoken from DEEPSLEEP
897 *
898 *
899 * The eventMask parameter is an event-specific mask. Currently the
900 * eventMask is not used by Power.
901 *
902 * The notifyFxn parameter specifies the function to call when the
903 * specified Power event occurs. The notifyFxn must implement the
904 * following signature:
905 *
906 * status = notifyFxn(eventType, eventArg1, eventArg2, clientArg);
907 *
908 * Where: eventType (of type Power_Event) is the type of Power event of
909 * the notification; eventArg1 (of type UArg) is an event-specific
910 * argument; eventArg2 (of type UArg) is a second event-specific argument;
911 * and clientArg (of type UArg) is an abitrary argument.
912 *
913 * Currently, eventArg1 and eventArg2 are used only for V/F scaling events:
914 * for a 'pending' setpoint change, eventArg1 holds the current setpoint,
915 * and eventArg2 holds the pending setpoint; for a 'done' sepoint change
916 * event, eventArg1 holds the previous setpoint, and eventArg2 holds the
917 * new setpoint.
918 *
919 * The notification function must return one of the following constants
920 * as a status value of type Power_NotifyResponse: Power_NOTIFYDONE if the
921 * the client processed the notification function successfully;
922 * Power_NOTIFYNOTDONE if the client must wait for interrupt processing
923 * to occur before it can proceed (the client must later call the
924 * delayedCompletionFxn specified when this function was registered); or
925 * Power_NOTIFYERROR if the notification cannot be processed (either an
926 * internal client error occurred or the client was notified of an event
927 * it could not process).
928 *
929 * The clientArg parameter is an arbitrary argument to be passed to the
930 * client upon notification. This argument may allow one notify function
931 * to be used by multiple instances of a driver (that is, the clientArg
932 * can be used to identify the instance of the driver that is being
933 * notified).
934 *
935 * For Power_regsiterNotify(), notifyHandle should point to the location
936 * where Power_registerNotify() should write a notification handle. If the
937 * application later needs to unregister the notification function, the
938 * application should pass this handle to Power_unregisterNotify().
939 *
940 * The delayedCompletionFxn is a pointer to a function provided by the
941 * Power module to the client at registration time. If a client cannot act
942 * immediately upon notification, its notify function should return
943 * Power_NOTIFYNOTDONE. Later, when the action is complete, the
944 * client should call the delayedCompletionFxn to signal Power that it has
945 * finished. The delayedCompletionFxn is a void function, taking no
946 * arguments, and having no return value. If a client can and does act
947 * immediately on the notification, it should return Power_NOTIFYDONE in
948 * response to notification, and should not call the delayedCompletionFxn.
949 *
950 * For example, if a DMA driver is to prepare for a setpoint change, it may
951 * need to wait for the current DMA transfer to complete. When the driver's
952 * DMA completes (for example, on the next hardware interrupt), it calls
953 * the delayedCompletionFxn function provided when it registered for
954 * notification. This completion function tells the Power module that the
955 * driver is finished. Meanwhile, the Power module was able to continue
956 * notifying other clients, and was waiting for all clients to signal
957 * completion.
958 *
959 * @param(eventType) The type of Power event to be notified of
960 *
961 * @param(eventMask) A Power event type-specific mask
962 *
963 * @param(notifyFxn) The function Power should call to notify the client
964 * of the event
965 *
966 * @param(clientArg) A client-defined argument to pass with the notifyFxn
967 * call
968 *
969 * @param(notifyHandle) Location to write the resulting notification
970 * handle (which is used for unregistering for the event)
971 *
972 * @param(delayedCompletionFxn) Location for the pointer to the delayed
973 * completion function the client should call if it
974 * requires more time to process an event (the client
975 * calls this function once its processing is complete)
976 *
977 * @b(returns) Power_SOK if the registration succeeded
978 *
979 * @b(returns) Power_EFAIL if the registration failed due to a memory
980 * allocation failure
981 *
982 * @b(returns) Power_EINVALIDPOINTER if the operation failed because
983 * the notifyFxn, notifyHandle, or delayedCompletionFxn
984 * parameter was NULL
985 *
986 * @b(returns) Power_EINVALIDEVENT if the operation failed because
987 * eventType is invalid
988 *
989 * @a(constraints)
990 * Power_registerNotify() cannot be called from a Swi or Hwi, because
991 * it allocates memory, and this may incur a context switch.
992 */
993 @DirectCall
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 @DirectCall
1032 Status releaseDependency(Resource resourceID);
1033
1034 /*!
1035 * ======== setDependency ========
1036 * Declare a dependency upon a power-manageable resource.
1037 *
1038 * Power_setDependency() declares a dependency upon a resource. Resources
1039 * are enumerated by Power_Resource.
1040 *
1041 * If the resource had been inactive, it will be activated during this
1042 * function call.
1043 *
1044 * This function is the companion to Power_releaseDependency().
1045 *
1046 * @param(resourceID) The resource identifier
1047 *
1048 * @b(returns) Power_SOK if the operation succeeded and the dependency
1049 * has been set
1050 *
1051 * @b(returns) Power_EFAIL if the operation failed while attempting
1052 * to activate the resource
1053 *
1054 * @b(returns) Power_EINVALIDVALUE if the operation failed because
1055 * Power cannot control this resource
1056 *
1057 * @b(returns) Power_ENOTSUPPORTED if the operation failed because
1058 * resource tracking is not enabled
1059 *
1060 * @b(returns) Power_EOUTOFRANGE if the specified resourceID is
1061 * outside the range of valid resource IDs
1062 */
1063 @DirectCall
1064 Status setDependency(Resource resourceID);
1065
1066 /*!
1067 * ======== signalEvent ========
1068 * Signal a Power event to registered clients.
1069 *
1070 * Power_signalEvent() provides a mechanism for an application to signal
1071 * Power events. Power_signalEvent() only signals the event occurrence; it
1072 * does not implement the actual processing associated with the Power
1073 * event.
1074 *
1075 * For example, on a platform where V/F scaling is accomplished on a
1076 * separate processor, Power_signalEvent() can be called by the DSP
1077 * application before the scaling to notify registered clients on this
1078 * processor of the pending setpoint change event. Similarly, after the
1079 * scaling, Power_signalEvent() can be called to signal the done setpoint
1080 * change event. Here Power is not orchestrating the change to the
1081 * V/F setpoint, but its registration, notification, and signaling
1082 * capabilities allow synchronization between scaling by the other
1083 * processor and the affected software on this processor.
1084 *
1085 * The parameters eventArg1 and eventArg2 should correspond to the type
1086 * of event being signaled. For example, for a pending setpoint
1087 * change event, the current and pending setpoints should be specified as
1088 * eventArg1 and eventArg2.
1089 *
1090 * The notifyTimeout parameter is the maximum amount of time (in system
1091 * Clock ticks) to wait for all registered notification functions (set by
1092 * Power_registerNotify()) to respond to a delayed completion, before
1093 * declaring failure and returning Power_ETIMEOUT.
1094 *
1095 * Power_signalEvent() is intended only for signaling power events that are
1096 * outside the full control of the Power implementation on the current
1097 * processor. It can be used for V/F scaling notification as described
1098 * avove when Power does not implement the actual scaling. For events where
1099 * Power does orchestrate the processing, for example, on platforms
1100 * where Power performs the actual V/F scaling, or activates a processor
1101 * sleep mode, Power handles the notifications automatically, and
1102 * Power_signalEvent() must not be used for these events. In other words,
1103 * Power_signalEvent() only validates that the indicated eventType is
1104 * within the range of valid events for the platform; it does not validate
1105 * whether it makes sense for the application to trigger the signaling of
1106 * the indicated event, and it does not implement the actual power
1107 * transition indicated by the event.
1108 *
1109 * @param(eventType) The Power event to be signaled
1110 *
1111 * @param(eventArg1) The event-specific first argument
1112 *
1113 * @param(eventArg2) The event-specific second argument
1114 *
1115 * @param(notifyTimeout) The maximum time (in Clock ticks) to wait for
1116 * client notifications to complete
1117 *
1118 * @b(returns) Power_SOK if the operation succeeded
1119 *
1120 * @b(returns) Power_EFAIL if a notification failure occurred
1121 *
1122 * @b(returns) Power_EINVALIDEVENT if the operation failed because
1123 * eventType is invalid
1124 *
1125 * @b(returns) Power_ETIMEOUT if the operation failed because
1126 * a registered notification client did not complete its
1127 * processing within the specified notifyTimeout
1128 *
1129 * @a(constraints)
1130 * Power_signalEvent can be called from a Hwi or Swi only if notifyTimeout
1131 * is zero
1132 */
1133 @DirectCall
1134 Status signalEvent(Event eventType, UArg eventArg1, UArg eventArg2,
1135 UInt notifyTimeout);
1136
1137 /*!
1138 * ======== sleepDSP ========
1139 * Put the DSP into a sleep state.
1140 *
1141 * Power_sleepDSP() transitions the DSP to a new sleep state. A successful
1142 * call to Power_sleepDSP() returns when the DSP has awoken from the
1143 * specified sleep state.
1144 *
1145 * The sleepCode parameter indicates the new sleep state for the DSP. The
1146 * sleep states supported by Power usually vary by device. For example,
1147 * the following constants may be used to activate sleep states on the
1148 * TMS320C6748:
1149 *
1150 * Power_STANDBY - The GEM is put into a power-saving standby mode,
1151 * with its clock turned off at the GEM boundary. This mode has a low
1152 * latency for wakeup.
1153 *
1154 * Power_SLEEP - In addition to putting the GEM into standby, the core
1155 * voltage is reduced, and the PLLs are slowed down or bypassed.
1156 *
1157 * Power_DEEPSLEEP - In addition to the actions for Power_SLEEP, the
1158 * GEM clock is gated up-stream at the power sleep controller, memories
1159 * are put into retention, and PLLs are powered down.
1160 *
1161 * The sleepArg parameter is a sleepCode-specific argument. For example,
1162 * for the TMS320C6748, this parameter is not used for Power_STANDBY,
1163 * but is used for Power_SLEEP and Power_DEEPSLEEP (see below).
1164 *
1165 * For Power_SLEEP: the sleepArg can be used to override Power's
1166 * default behavior. If sleepArg is NULL, then Power reduces the core
1167 * voltage to 1.0 volts during sleep, and bypasses both PLLs. If sleepArg
1168 * is non-NULL, it is interpreted as a pointer to a {@link #SleepOverride}
1169 * structure. In this structure, the sleepVoltage is in millivolts, and
1170 * must correspond to a voltage level defined by the scaling configuration
1171 * library. The bypassedPLLs value is treated as a bitmask to indicate
1172 * which PLLs get bypassed during sleep: Power_PLL0 and/or Power_PLL1.
1173 * This override mechanism can be used to ensure operation within the
1174 * TMS320C6748 device constraints. For example, if the minimum supported
1175 * voltage when DDR2 is used is 1.1 volts, and no DDR2 accesses can be
1176 * made when PLL1 is bypassed. These constraints could be violated in some
1177 * use cases, for example, when DDR2 memory is used, and there is a
1178 * possibility that the wakeup interrupt service routine triggers some
1179 * off-chip code or data accesses. The override mechanism allows the sleep
1180 * voltage to be increased to 1.1 volts and PLL1 to not be bypassed during
1181 * sleep.
1182 *
1183 * For Power_DEEPSLEEP: sleepArg defines the DEEPSLEEP signal source that
1184 * Power should configure for wakeup. This must be either Power_RTC_ALARM
1185 * or Power_EXTERNAL.
1186 *
1187 * The notifyTimeout parameter is the maximum amount of time (in system
1188 * Clock ticks) to wait for registered notification functions (set by
1189 * Power_registerNotify()) to respond to a delayed completion, before
1190 * declaring failure and returning Power_ETIMEOUT. If the notifyTimeout
1191 * parameter is zero, then all notification functions must return
1192 * Power_NOTIFYDONE-they cannot request a delayed completion. If a
1193 * notification function does not return, the system will hang. The
1194 * notifyTimeout is not used to abandon a notification function; rather it
1195 * indicates the amount of time Power_sleepDSP waits for all delayed
1196 * completion requests to complete. The wait-loop is entered after all
1197 * notification functions have been invoked.
1198 *
1199 * The application should treat return values of Power_ETIMEOUT or
1200 * Power_EFAIL as critical system failures. These values indicate the
1201 * notification client is unresponsive, and the system is in an unknown
1202 * state.
1203 *
1204 * Due to the critical system nature of sleep commands, clients that
1205 * register for sleep notification should make every effort to respond
1206 * immediately to the sleep event.
1207 *
1208 * @param(sleepCode) The sleep state for the DSP
1209 *
1210 * @param(sleepArg) A sleepCode-specific argument structure (see below)
1211 *
1212 * @param(notifyTimeout) The maximum time (in Clock ticks) to wait for
1213 * client notifications to complete
1214 *
1215 * @b(returns) Power_SOK if the operation succeeded and a successful
1216 * sleep and wake occurred
1217 *
1218 * @b(returns) Power_EFAIL if a general failure occurred and the DSP
1219 * could not be put to sleep
1220 *
1221 * @b(returns) Power_ENOTIMPLEMENTED if the requested sleep state
1222 * is not implemented on this platform
1223 *
1224 * @b(returns) Power_ETIMEOUT if the operation failed because
1225 * a registered notification function did not complete its
1226 * (delayed completion) processing within the specified
1227 * notifyTimeout
1228 *
1229 * @b(returns) Power_EBUSY if the operation failed because Power
1230 * is still busy processing a previous request
1231 *
1232 * @a(constraints)
1233 * Power_sleepDSP() cannot be called from an Hwi
1234 *
1235 * Power_sleepDSP() cannot be called from a program's main() function
1236 *
1237 * Power_sleepDSP() can be called from a Swi only if notifyTimeout is 0
1238 *
1239 * For Power_SLEEP: no DDR memory accesses (code, data, or stack) can
1240 * occur while the PLL1 is bypassed, otherwise DDR corruption may occur
1241 *
1242 * For Power_SLEEP: if DDR2 memories are used, then no DDR2 accesses can
1243 * occur with a sleep voltage of 1.0 volts, otherwise DDR2 corruption
1244 * may occur
1245 *
1246 * For Power_DEEPSLEEP: this state must be invoked from an on-chip
1247 * context; no code, data, or stack access can occur during
1248 * Power_sleepDSP, otherwise DDR corruption may occur
1249 */
1250 @DirectCall
1251 Status sleepDSP(UInt sleepCode, UInt sleepArg, UInt notifyTimeout);
1252
1253 /*!
1254 * ======== unregisterConstraint ========
1255 * Unregister a constraint that was previously registered with Power.
1256 *
1257 * Power_unregisterConstraint() unregisters a constraint that was
1258 * registered with Power_registerConstraint(). For example, when a device
1259 * driver is closed, any constraints it registered with Power must be
1260 * unregistered with this function, otherwise Power may be left
1261 * unnecessarily restricted from activating power savings.
1262 *
1263 * The handle parameter is the handle that was provided by
1264 * Power_registerConstraint() when the constraint was registered.
1265 *
1266 * @param(handle) The handle to the previously-registered constraint
1267 *
1268 * @b(returns) Power_SOK if the operation succeeded
1269 *
1270 * @b(returns) Power_EINVALIDHANDLE if the operation failed because
1271 * handle is invalid
1272 *
1273 * @a(constraints)
1274 * This function cannot be called from a program's main() function.
1275 */
1276 @DirectCall
1277 Status unregisterConstraint(ConstraintHandle handle);
1278
1279 /*!
1280 * ======== unregisterNotify ========
1281 * Unregister for a Power event notification.
1282 *
1283 * Power_unregisterNotify() unregisters an event notification that was
1284 * registered with Power_registerNotify(). For example, when an audio codec
1285 * device is closed, and it no longer needs event notifications, it must
1286 * unregister by calling this function.
1287 *
1288 * The notifyHandle parameter is the handle that was provided by
1289 * Power_registerNotify() when registering for an event notification.
1290 *
1291 * @param(notifyHandle) The event notification handle
1292 *
1293 * @b(returns) Power_SOK if the operation succeeded
1294 *
1295 * @b(returns) Power_EINVALIDHANDLE if the operation failed because
1296 * notifyHandle is invalid
1297 *
1298 * @a(constraints)
1299 * This function cannot be called from a program's main() function.
1300 */
1301 @DirectCall
1302 Status unregisterNotify(NotifyHandle notifyHandle);
1303
1304 /*! @_nodoc */
1305 @XmlDtd
1306 metaonly struct ModuleView {
1307 UInt setpointCPU;
1308 UInt setpointPER;
1309 String maskDisallowedSetpointsCPU;
1310 String maskDisallowedSetpointsPER;
1311 String maskDisallowedSleepModes;
1312 };
1313
1314 /*! @_nodoc */
1315 @Facet
1316 metaonly config ViewInfo.Instance rovViewInfo =
1317 ViewInfo.create({
1318 viewMap: [
1319 [
1320 'Module',
1321 {
1322 type: ViewInfo.MODULE,
1323 viewInitFxn: 'viewInitModule',
1324 structName: 'ModuleView'
1325 }
1326 ],
1327 ]
1328 });
1329
1330 internal:
1331
1332 config UInt CAPSMASK;
1333
1334
1335 const UInt CWAITFORV = 0x20;
1336 const UInt CSCALEVWITHF = 0x10;
1337 const UInt CMOVEINITSPS = 0x1000;
1338
1339 const UInt RELEASE = 0;
1340 const UInt SET = 1;
1341 const UInt QUERY = 2;
1342
1343 enum SigType {
1344 SigType_INTERNAL = 0,
1345 SigType_EXTERNAL
1346 };
1347
1348 1349 1350
1351 @DirectCall
1352 Void delayCompletion0();
1353
1354 1355 1356
1357 @DirectCall
1358 Void delayCompletion1();
1359
1360 1361 1362
1363 @DirectCall
1364 Void delayCompletion2();
1365
1366 1367 1368
1369 @DirectCall
1370 Void delayCompletion3();
1371
1372 1373 1374
1375 @DirectCall
1376 Void delayCompletion4();
1377
1378 1379 1380
1381 @DirectCall
1382 Void delayCompletion5();
1383
1384 1385 1386
1387 @DirectCall
1388 Void delayCompletion6();
1389
1390 1391 1392
1393 @DirectCall
1394 Void delayCompletion7();
1395
1396 1397 1398
1399 @DirectCall
1400 Void delayCompletion8();
1401
1402 1403 1404
1405 @DirectCall
1406 Void delayCompletion9();
1407
1408 1409 1410
1411 @DirectCall
1412 Void idleStopClock();
1413
1414 1415 1416
1417 @DirectCall
1418 Void init();
1419
1420 1421 1422
1423 @DirectCall
1424 Void initRefCounts();
1425
1426 1427 1428
1429 @DirectCall
1430 Status notify(Event eventType, UInt timeout, SigType sigType,
1431 UArg extArg1, UArg extArg2);
1432
1433 1434 1435
1436 @DirectCall
1437 Void rebuildConstraint(Constraint type);
1438
1439 1440 1441
1442 @DirectCall
1443 Void updateConstraints(Constraint type, UArg value);
1444
1445 1446 1447
1448 struct Module_State {
1449 UInt32 currentSetpointCPU;
1450 UInt32 currentSetpointPER;
1451 UInt32 disallowedSetpointsCPU;
1452 UInt32 disallowedSetpointsPER;
1453 UInt32 disallowedSleepModes;
1454 Queue.Object constraintsQ;
1455 Queue.Object notifyQ[];
1456 UInt32 nextSP;
1457 UInt32 previousSP;
1458 UInt32 nextSPPER;
1459 UInt32 previousSPPER;
1460 UInt32 numSPCPU;
1461 UInt32 numSPPER;
1462 Config currentConfig;
1463 Bool PSCLinitOK;
1464 Bool busy;
1465 }
1466 }
1467
1468 1469 1470 1471
1472