OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [ref/] [power-info.html] - Blame information for rev 588

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 28 unneback 
<!-- Copyright (C) 2003 Red Hat, Inc.                                -->
2 
<!-- This material may be distributed only subject to the terms      -->
3 
<!-- and conditions set forth in the Open Publication License, v1.0  -->
4 
<!-- or later (the latest version is presently available at          -->
5 
<!-- http://www.opencontent.org/openpub/).                           -->
6 
<!-- Distribution of the work or derivative of the work in any       -->
7 
<!-- standard (paper) book form is prohibited unless prior           -->
8 
<!-- permission is obtained from the copyright holder.               -->
9 
<HTML
10 
><HEAD
11 
><TITLE
12 
>Power Management Information</TITLE
13 
><meta name="MSSmartTagsPreventParsing" content="TRUE">
14 
<META
15 
NAME="GENERATOR"
16 
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
17 
"><LINK
18 
REL="HOME"
19 
TITLE="eCos Reference Manual"
20 
HREF="ecos-ref.html"><LINK
21 
REL="UP"
22 
TITLE="eCos Power Management Support"
23 
HREF="services-power.html"><LINK
24 
REL="PREVIOUS"
25 
TITLE="Introduction"
26 
HREF="power-intro.html"><LINK
27 
REL="NEXT"
28 
TITLE="Changing Power Modes"
29 
HREF="power-change.html"></HEAD
30 
><BODY
31 
CLASS="REFENTRY"
32 
BGCOLOR="#FFFFFF"
33 
TEXT="#000000"
34 
LINK="#0000FF"
35 
VLINK="#840084"
36 
ALINK="#0000FF"
37 
><DIV
38 
CLASS="NAVHEADER"
39 
><TABLE
40 
SUMMARY="Header navigation table"
41 
WIDTH="100%"
42 
BORDER="0"
43 
CELLPADDING="0"
44 
CELLSPACING="0"
45 
><TR
46 
><TH
47 
COLSPAN="3"
48 
ALIGN="center"
49 
>eCos Reference Manual</TH
50 
></TR
51 
><TR
52 
><TD
53 
WIDTH="10%"
54 
ALIGN="left"
55 
VALIGN="bottom"
56 
><A
57 
HREF="power-intro.html"
58 
ACCESSKEY="P"
59 
>Prev</A
60 
></TD
61 
><TD
62 
WIDTH="80%"
63 
ALIGN="center"
64 
VALIGN="bottom"
65 
></TD
66 
><TD
67 
WIDTH="10%"
68 
ALIGN="right"
69 
VALIGN="bottom"
70 
><A
71 
HREF="power-change.html"
72 
ACCESSKEY="N"
73 
>Next</A
74 
></TD
75 
></TR
76 
></TABLE
77 
><HR
78 
ALIGN="LEFT"
79 
WIDTH="100%"></DIV
80 
><H1
81 
><A
82 
NAME="POWER-INFO">Power Management Information</H1
83 
><DIV
84 
CLASS="REFNAMEDIV"
85 
><A
86 
NAME="AEN15678"
87 
></A
88 
><H2
89 
>Name</H2
90 
>Obtaining Power Management Information&nbsp;--&nbsp;finding out about the various power controllers in the system</DIV
91 
><DIV
92 
CLASS="REFSYNOPSISDIV"
93 
><A
94 
NAME="AEN15681"><H2
95 
>Synopsis</H2
96 
><DIV
97 
CLASS="FUNCSYNOPSIS"
98 
><A
99 
NAME="AEN15682"><P
100 
></P
101 
><TABLE
102 
BORDER="5"
103 
BGCOLOR="#E0E0F0"
104 
WIDTH="70%"
105 
><TR
106 
><TD
107 
><PRE
108 
CLASS="FUNCSYNOPSISINFO"
109 
>#include &lt;cyg/power/power.h&gt;
110 
 
111 
extern PowerController __POWER__[], __POWER_END__;
112 
extern PowerController power_controller_cpu;
113 
extern cyg_handle_t    power_thread_handle;</PRE
114 
></TD
115 
></TR
116 
></TABLE
117 
><P
118 
><CODE
119 
><CODE
120 
CLASS="FUNCDEF"
121 
>    PowerMode power_get_mode
122 
  </CODE
123 
>(void);</CODE
124 
></P
125 
><P
126 
><CODE
127 
><CODE
128 
CLASS="FUNCDEF"
129 
>    PowerMode power_get_desired_mode
130 
  </CODE
131 
>(void);</CODE
132 
></P
133 
><P
134 
><CODE
135 
><CODE
136 
CLASS="FUNCDEF"
137 
>    PowerMode power_get_controller_mode
138 
  </CODE
139 
>(    PowerController* controller
140 
  );</CODE
141 
></P
142 
><P
143 
><CODE
144 
><CODE
145 
CLASS="FUNCDEF"
146 
>    PowerMode power_get_controller_desired_mode
147 
  </CODE
148 
>(    PowerController* controller
149 
  );</CODE
150 
></P
151 
><P
152 
><CODE
153 
><CODE
154 
CLASS="FUNCDEF"
155 
>    const char* power_get_controller_id
156 
  </CODE
157 
>(    PowerController* controller
158 
  );</CODE
159 
></P
160 
><P
161 
></P
162 
></DIV
163 
></DIV
164 
><DIV
165 
CLASS="REFSECT1"
166 
><A
167 
NAME="POWER-INFO-ACCESS"
168 
></A
169 
><H2
170 
>Accessing Power Controllers</H2
171 
><P
172 
>All the power controllers in a system are held in a table, filled in
173 
at link-time. The symbols <TT
174 
CLASS="VARNAME"
175 
>__POWER__</TT
176 
> and
177 
<TT
178 
CLASS="VARNAME"
179 
>__POWER_END</TT
180 
> can be used to iterate through this
181 
table, for example:</P
182 
><TABLE
183 
BORDER="5"
184 
BGCOLOR="#E0E0F0"
185 
WIDTH="70%"
186 
><TR
187 
><TD
188 
><PRE
189 
CLASS="PROGRAMLISTING"
190 
>PowerController* controller;
191 
for (controller  = &amp;(__POWER__[0]);
192 
     controller != &amp;(__POWER_END__);
193 
     controller++) {
194 
 
195 
     &#8230;
196 
}</PRE
197 
></TD
198 
></TR
199 
></TABLE
200 
><P
201 
>Each controller has an associated priority, controlling the order in
202 
which they appear in the table. Typically a software-only component
203 
such as a TCP/IP stack would use a small number for the priority, so
204 
that it appears near the start of the table, whereas a device driver
205 
would be nearer the back of the table. When switching to a
206 
lower-powered mode the power management package will iterate through
207 
this table from front to back, thus ensuring that for example the
208 
TCP/IP stack gets a chance to shut down before the underlying ethernet
209 
or other hardware that the stack depends on. Similarly when switching
210 
to a higher-powered mode the power management package will iterate
211 
through this table from back to front.</P
212 
><P
213 
>In most systems there will be one special controller,
214 
<TT
215 
CLASS="VARNAME"
216 
>power_controller_cpu</TT
217 
>, which should be provided by
218 
one of the architectural, variant or platform HAL packages. This
219 
controller will always be the last entry in the table. It is
220 
responsible for the final power down operation when switching to
221 
<SPAN
222 
CLASS="TYPE"
223 
>off</SPAN
224 
> mode. Other packages such as device drivers may or
225 
may not declare variable identifiers for their power controllers,
226 
allowing those controllers to be accessed by name as well as by their
227 
entries in the global table.</P
228 
></DIV
229 
><DIV
230 
CLASS="REFSECT1"
231 
><A
232 
NAME="POWER-INFO-GLOBAL"
233 
></A
234 
><H2
235 
>Global Power Modes</H2
236 
><P
237 
>The function <TT
238 
CLASS="FUNCTION"
239 
>power_get_mode</TT
240 
> can be called at any
241 
time to determine the current power mode for the system as a whole.
242 
The return value will be one of <TT
243 
CLASS="LITERAL"
244 
>PowerMode_Active</TT
245 
>,
246 
<TT
247 
CLASS="LITERAL"
248 
>PowerMode_Idle</TT
249 
>, <TT
250 
CLASS="LITERAL"
251 
>PowerMode_Sleep</TT
252 
>
253 
or <TT
254 
CLASS="LITERAL"
255 
>PowerMode_Off</TT
256 
>. In normal circumstances it is
257 
unlikely that <TT
258 
CLASS="LITERAL"
259 
>PowerMode_Off</TT
260 
> would be returned since
261 
that mode generally means that the cpu is no longer running.</P
262 
><P
263 
>The function <TT
264 
CLASS="FUNCTION"
265 
>power_get_desired_mode</TT
266 
> returns the
267 
power mode that the system should be running at. Most of the time this
268 
will be the same value as returned by
269 
<TT
270 
CLASS="FUNCTION"
271 
>power_get_mode</TT
272 
>. However a different value may be
273 
returned when in the middle of changing power modes. For example, if
274 
the current thread runs at a higher priority than the power management
275 
thread then the latter may have been pre-empted in the middle of a
276 
mode change: <TT
277 
CLASS="FUNCTION"
278 
>power_get_mode</TT
279 
> will return the mode
280 
the system was running at before the mode change started, and
281 
<TT
282 
CLASS="FUNCTION"
283 
>power_get_desired_mode</TT
284 
> will return the mode the
285 
system should end up in when the mode change completes, barring
286 
further calls to <TT
287 
CLASS="FUNCTION"
288 
>power_set_mode</TT
289 
>.</P
290 
></DIV
291 
><DIV
292 
CLASS="REFSECT1"
293 
><A
294 
NAME="POWER-INFO-INDIVIDUAL"
295 
></A
296 
><H2
297 
>Individual Controller Power Modes</H2
298 
><P
299 
>The power management package keeps track of the current and desired
300 
modes for each power controller, as well as the modes for the system as
301 
a whole. The function <TT
302 
CLASS="FUNCTION"
303 
>power_get_controller_mode</TT
304 
>
305 
takes a single argument, a pointer to a power controller, and returns
306 
the power mode that controller is currently running at. Similarly
307 
<TT
308 
CLASS="FUNCTION"
309 
>power_get_controller_desired_mode</TT
310 
> returns the
311 
power mode that controller should be running at. Most of the time the
312 
current and desired modes for a given controller will be the same, and
313 
will also be the same as the global power mode. However if the power
314 
management thread is preeempted in the middle of a mode change then
315 
some of the controllers will have been updated to the desired global
316 
mode, whereas others will still be at the old mode. The power
317 
management package also provides functionality for manipulating
318 
<A
319 
HREF="power-change.html#POWER-CHANGE-CONTROLLER"
320 
>individual controllers</A
321 
>, and for <A
322 
HREF="power-attached.html"
323 
>detaching</A
324 
> controllers from
325 
global mode changes.</P
326 
></DIV
327 
><DIV
328 
CLASS="REFSECT1"
329 
><A
330 
NAME="POWER-INFO-IDS"
331 
></A
332 
><H2
333 
>Power Controller Identification</H2
334 
><P
335 
>In some scenarios the power management package will run completely
336 
automated, and there is no need to identify individual power
337 
controllers. Any form of identification such as a string
338 
description would serve no purpose, but would still consume memory in
339 
the final system. In other scenarios it may be very desirable to
340 
provide some means of identification. For example, while still
341 
debugging it may be useful to see a simple string when printing the
342 
contents of a power controller structure. Alternatively, if the
343 
application is expected to provide some sort of user interface that
344 
gives control over which parts of the system are enabled or disabled,
345 
a string identifier for each controller would be useful. To cope with
346 
these scenarios the power management package provides a configuration
347 
option <TT
348 
CLASS="VARNAME"
349 
>CYGIMP_POWER_PROVIDE_STRINGS</TT
350 
>. When enabled,
351 
each power controller will contain a pointer to a constant string
352 
which can be accessed via a function
353 
<TT
354 
CLASS="FUNCTION"
355 
>power_get_controller_id</TT
356 
>. When disabled the system
357 
will not contain these strings, and the function will not be provided.
358 
The following code illustrates how to use this function.</P
359 
><TABLE
360 
BORDER="5"
361 
BGCOLOR="#E0E0F0"
362 
WIDTH="70%"
363 
><TR
364 
><TD
365 
><PRE
366 
CLASS="PROGRAMLISTING"
367 
>#include &lt;stdio.h&gt;
368 
#include &lt;pkgconf/system.h&gt;
369 
#ifndef CYGPKG_POWER
370 
# error The power management package is not present.
371 
#endif
372 
#include &lt;pkgconf/power.h&gt;
373 
#ifndef CYGIMP_POWER_PROVIDE_STRINGS
374 
# error Power controller identifiers are not available.
375 
#endif
376 
#include &lt;cyg/power/power.h&gt;
377 
 
378 
static const char*
379 
mode_to_string(PowerMode mode)
380 
{
381 
    const char* result;
382 
    switch(mode) {
383 
      case PowerMode_Active : result = "active"; break;
384 
      case PowerMode_Idle   : result = "idle"; break;
385 
      case PowerMode_Sleep  : result = "sleep"; break;
386 
      case PowerMode_Off    : result = "off"; break;
387 
      default               : result = "&lt;unknown&gt;"; break;
388 
    }
389 
    return result;
390 
}
391 
 
392 
int
393 
main(int argc, char** argv)
394 
{
395 
    PowerController* controller;
396 
 
397 
    for (controller = &amp;(__POWER__[0]);
398 
         controller != &amp;(__POWER_END__);
399 
         controller++) {
400 
        printf("Controller @ %p: %s, %s\n", controller,
401 
               power_get_controller_id(controller),
402 
               mode_to_string(power_get_controller_mode(controller)));
403 
    }
404 
    return 0;
405 
}</PRE
406 
></TD
407 
></TR
408 
></TABLE
409 
></DIV
410 
><DIV
411 
CLASS="REFSECT1"
412 
><A
413 
NAME="POWER-INFO-THREAD"
414 
></A
415 
><H2
416 
>The Power Management Thread</H2
417 
><P
418 
>If the power management package is configured to use a separate thread
419 
then a handle for that thread is made available to higher-level code
420 
via the variable <TT
421 
CLASS="VARNAME"
422 
>power_thread_handle</TT
423 
>. This handle
424 
can be used for a variety of purposes, including manipulating that
425 
thread's priority.</P
426 
></DIV
427 
><DIV
428 
CLASS="NAVFOOTER"
429 
><HR
430 
ALIGN="LEFT"
431 
WIDTH="100%"><TABLE
432 
SUMMARY="Footer navigation table"
433 
WIDTH="100%"
434 
BORDER="0"
435 
CELLPADDING="0"
436 
CELLSPACING="0"
437 
><TR
438 
><TD
439 
WIDTH="33%"
440 
ALIGN="left"
441 
VALIGN="top"
442 
><A
443 
HREF="power-intro.html"
444 
ACCESSKEY="P"
445 
>Prev</A
446 
></TD
447 
><TD
448 
WIDTH="34%"
449 
ALIGN="center"
450 
VALIGN="top"
451 
><A
452 
HREF="ecos-ref.html"
453 
ACCESSKEY="H"
454 
>Home</A
455 
></TD
456 
><TD
457 
WIDTH="33%"
458 
ALIGN="right"
459 
VALIGN="top"
460 
><A
461 
HREF="power-change.html"
462 
ACCESSKEY="N"
463 
>Next</A
464 
></TD
465 
></TR
466 
><TR
467 
><TD
468 
WIDTH="33%"
469 
ALIGN="left"
470 
VALIGN="top"
471 
>Introduction</TD
472 
><TD
473 
WIDTH="34%"
474 
ALIGN="center"
475 
VALIGN="top"
476 
><A
477 
HREF="services-power.html"
478 
ACCESSKEY="U"
479 
>Up</A
480 
></TD
481 
><TD
482 
WIDTH="33%"
483 
ALIGN="right"
484 
VALIGN="top"
485 
>Changing Power Modes</TD
486 
></TR
487 
></TABLE
488 
></DIV
489 
></BODY
490 
></HTML
491 
>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.