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.