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

Subversion Repositories openrisc

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

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

powered by: WebSVN 2.1.0

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