OpenCores
URL https://opencores.org/ocsvn/openrisc_2011-10-31/openrisc_2011-10-31/trunk

Subversion Repositories openrisc_2011-10-31

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [packages/] [services/] [power/] [common/] [v2_0/] [doc/] [power-info.html] - Blame information for rev 174

Details | Compare with Previous | View Log

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

powered by: WebSVN 2.1.0

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