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

Subversion Repositories openrisc

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

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 
>Support for Policy Modules</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="Changing Power Modes"
26 
HREF="power-change.html"><LINK
27 
REL="NEXT"
28 
TITLE="Attached and Detached Controllers"
29 
HREF="power-attached.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-change.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-attached.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-POLICY">Support for Policy Modules</H1
83 
><DIV
84 
CLASS="REFNAMEDIV"
85 
><A
86 
NAME="AEN15836"
87 
></A
88 
><H2
89 
>Name</H2
90 
>Support for Policy Modules&nbsp;--&nbsp;closer integration with higher-level code</DIV
91 
><DIV
92 
CLASS="REFSYNOPSISDIV"
93 
><A
94 
NAME="AEN15839"><H2
95 
>Synopsis</H2
96 
><DIV
97 
CLASS="FUNCSYNOPSIS"
98 
><A
99 
NAME="AEN15840"><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;</PRE
110 
></TD
111 
></TR
112 
></TABLE
113 
><P
114 
><CODE
115 
><CODE
116 
CLASS="FUNCDEF"
117 
>    void power_set_policy_callback
118 
  </CODE
119 
>(    void (*)(PowerController*, PowerMode, PowerMode, PowerMode, PowerMode) callback
120 
  );</CODE
121 
></P
122 
><P
123 
><CODE
124 
><CODE
125 
CLASS="FUNCDEF"
126 
>    void (*)(PowerController*, PowerMode, PowerMode, PowerMode, PowerMode) power_get_policy_callback
127 
  </CODE
128 
>(void);</CODE
129 
></P
130 
><P
131 
><CODE
132 
><CODE
133 
CLASS="FUNCDEF"
134 
>    CYG_ADDRWORD power_get_controller_policy_data
135 
  </CODE
136 
>(    PowerController* controller
137 
  );</CODE
138 
></P
139 
><P
140 
><CODE
141 
><CODE
142 
CLASS="FUNCDEF"
143 
>    void power_set_controller_policy_data
144 
  </CODE
145 
>(    PowerController* controller
146 
  ,     CYG_ADDRWORD data
147 
  );</CODE
148 
></P
149 
><P
150 
></P
151 
></DIV
152 
></DIV
153 
><DIV
154 
CLASS="REFSECT1"
155 
><A
156 
NAME="POWER-POLICY-CALLBACK"
157 
></A
158 
><H2
159 
>Policy Callbacks</H2
160 
><P
161 
>The use of a separate thread to perform power mode changes in typical
162 
configurations can cause problems for some policy modules.
163 
Specifically, the policy module can request a mode change for the
164 
system as a whole or for an individual controller, but it does not
165 
know when the power management thread actually gets scheduled to run
166 
again and carry out the request. Although it would be possible for the
167 
policy module to perform some sort of polling, in general that is
168 
undesirable.</P
169 
><P
170 
>To avoid such problems the policy module can install a callback
171 
function using <TT
172 
CLASS="FUNCTION"
173 
>power_set_policy_callback</TT
174 
>. The
175 
current callback function can be retrieved using
176 
<TT
177 
CLASS="FUNCTION"
178 
>power_get_policy_callback</TT
179 
>. If a callback function
180 
has been installed then it will be called by the power management
181 
package whenever a power controller has been invoked to perform a mode
182 
change. The callback will be called in the context of the power
183 
management thread, so usually it will have to make use of thread
184 
synchronisation primitives to interact with the main policy module. It
185 
is passed five arguments:</P
186 
><P
187 
></P
188 
><OL
189 
TYPE="1"
190 
><LI
191 
><P
192 
>The power controller that has just been invoked to perform a mode
193 
change. </P
194 
></LI
195 
><LI
196 
><P
197 
>The mode this controller was running at before the invocation.</P
198 
></LI
199 
><LI
200 
><P
201 
>The current mode this controller is now running at.</P
202 
></LI
203 
><LI
204 
><P
205 
>The desired mode before the power controller was invoked. Usually this
206 
will be the same as the current mode, unless the controller has
207 
decided for some reason that this was inappropriate.</P
208 
></LI
209 
><LI
210 
><P
211 
>The current desired mode. This will differ from the previous argument
212 
only if there has was another call to
213 
<TT
214 
CLASS="FUNCTION"
215 
>power_set_mode</TT
216 
> or
217 
<TT
218 
CLASS="FUNCTION"
219 
>power_set_controller_mode</TT
220 
> while the power
221 
controller was being invoked, probably by the power controller itself.</P
222 
></LI
223 
></OL
224 
><P
225 
>A simple example of a policy callback function would be:</P
226 
><TABLE
227 
BORDER="5"
228 
BGCOLOR="#E0E0F0"
229 
WIDTH="70%"
230 
><TR
231 
><TD
232 
><PRE
233 
CLASS="PROGRAMLISTING"
234 
>static void
235 
power_callback(
236 
    PowerController* controller,
237 
    PowerMode old_mode,
238 
    PowerMode new_mode,
239 
    PowerMode old_desired_mode,
240 
    powerMode new_desired_mode)
241 
{
242 
    printf("Power mode change: %s, %s -&#62; %d\n",
243 
        power_get_controller_id(controller),
244 
        mode_to_string(old_mode),
245 
        mode_to_string(new_mode));
246 
 
247 
    CYG_UNUSED_PARAM(PowerMode, old_desired_mode);
248 
    CYG_UNUSED_PARAM(PowerMode, new_desired_mode);
249 
}
250 
 
251 
int
252 
main(int argc, char** argv)
253 
{
254 
    &#8230;
255 
    power_set_policy_callback(&amp;power_callback);
256 
    &#8230;
257 
}</PRE
258 
></TD
259 
></TR
260 
></TABLE
261 
><P
262 
>If <TT
263 
CLASS="FUNCTION"
264 
>power_set_controller_mode_now</TT
265 
> is used to
266 
manipulate an individual controller the policy callback will not be
267 
invoked. This function may get called from any context including DSRs,
268 
and even if there is already a call to the policy callback happening
269 
in some other context, so invoking the callback would usually be
270 
unsafe.</P
271 
><P
272 
>If the power management package has not been configured to use a
273 
separate thread then <TT
274 
CLASS="FUNCTION"
275 
>power_set_mode</TT
276 
> and
277 
<TT
278 
CLASS="FUNCTION"
279 
>power_set_controller_mode</TT
280 
> will manipulate the
281 
power controllers immediately and invoke the policy callback
282 
afterwards. Therefore the policy callback will typically run in the
283 
same context as the main policy module.</P
284 
></DIV
285 
><DIV
286 
CLASS="REFSECT1"
287 
><A
288 
NAME="POWER-POLICY-DATA"
289 
></A
290 
><H2
291 
>Policy-specific Controller Data</H2
292 
><P
293 
>Some policy modules may want to associate some additional data with
294 
each power controller. This could be achieved by for example
295 
maintaining a hash table or similar data structure, but for
296 
convenience the power management package allows higher-level code,
297 
typically the policy module, to store and retrieve one word of data in
298 
each power controller. The function
299 
<TT
300 
CLASS="FUNCTION"
301 
>power_set_controller_policy_data</TT
302 
> takes two
303 
arguments, a pointer to a power controller and a
304 
<SPAN
305 
CLASS="TYPE"
306 
>CYG_ADDRWORD</SPAN
307 
> of data: by appropriate use of casts this
308 
word could be an integer or a pointer to some data structure. The
309 
matching function
310 
<TT
311 
CLASS="FUNCTION"
312 
>power_get_controller_policy_data</TT
313 
> retrieves the
314 
word previously installed, and can be cast back to an integer or
315 
pointer. The default value for the policy data is 0.</P
316 
><P
317 
>For example the following code fragment stores a simple index value in
318 
each power controller. This could then be retrieved by the policy
319 
callback.</P
320 
><TABLE
321 
BORDER="5"
322 
BGCOLOR="#E0E0F0"
323 
WIDTH="70%"
324 
><TR
325 
><TD
326 
><PRE
327 
CLASS="PROGRAMLISTING"
328 
>    unsigned int     i = 0;
329 
    PowerController* controller;
330 
 
331 
    for (controller = &amp;(__POWER__[0]);
332 
         controller != &amp;(__POWER_END__);
333 
         controller++) {
334 
        power_set_controller_policy_data(controller, (CYG_ADDRWORD) i++);
335 
    }</PRE
336 
></TD
337 
></TR
338 
></TABLE
339 
><P
340 
>Not all policy modules will require per-controller data. The
341 
configuration option
342 
<TT
343 
CLASS="VARNAME"
344 
>CYGIMP_POWER_PROVIDE_POLICY_DATA</TT
345 
> can be used to
346 
control this functionality, thus avoiding wasting a small amount of
347 
memory inside each power controller structure.</P
348 
></DIV
349 
><DIV
350 
CLASS="NAVFOOTER"
351 
><HR
352 
ALIGN="LEFT"
353 
WIDTH="100%"><TABLE
354 
SUMMARY="Footer navigation table"
355 
WIDTH="100%"
356 
BORDER="0"
357 
CELLPADDING="0"
358 
CELLSPACING="0"
359 
><TR
360 
><TD
361 
WIDTH="33%"
362 
ALIGN="left"
363 
VALIGN="top"
364 
><A
365 
HREF="power-change.html"
366 
ACCESSKEY="P"
367 
>Prev</A
368 
></TD
369 
><TD
370 
WIDTH="34%"
371 
ALIGN="center"
372 
VALIGN="top"
373 
><A
374 
HREF="ecos-ref.html"
375 
ACCESSKEY="H"
376 
>Home</A
377 
></TD
378 
><TD
379 
WIDTH="33%"
380 
ALIGN="right"
381 
VALIGN="top"
382 
><A
383 
HREF="power-attached.html"
384 
ACCESSKEY="N"
385 
>Next</A
386 
></TD
387 
></TR
388 
><TR
389 
><TD
390 
WIDTH="33%"
391 
ALIGN="left"
392 
VALIGN="top"
393 
>Changing Power Modes</TD
394 
><TD
395 
WIDTH="34%"
396 
ALIGN="center"
397 
VALIGN="top"
398 
><A
399 
HREF="services-power.html"
400 
ACCESSKEY="U"
401 
>Up</A
402 
></TD
403 
><TD
404 
WIDTH="33%"
405 
ALIGN="right"
406 
VALIGN="top"
407 
>Attached and Detached Controllers</TD
408 
></TR
409 
></TABLE
410 
></DIV
411 
></BODY
412 
></HTML
413 
>

powered by: WebSVN 2.1.0

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