1 <!-- 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. -->
12 >Power Management Information</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="eCos Reference Manual"
20 HREF="ecos-ref.html"><LINK
22 TITLE="eCos Power Management Support"
23 HREF="services-power.html"><LINK
26 HREF="power-intro.html"><LINK
28 TITLE="Changing Power Modes"
29 HREF="power-change.html"></HEAD
40 SUMMARY="Header navigation table"
49 >eCos Reference Manual</TH
57 HREF="power-intro.html"
71 HREF="power-change.html"
82 NAME="POWER-INFO">Power Management Information</H1
90 >Obtaining Power Management Information -- finding out about the various power controllers in the system</DIV
92 CLASS="REFSYNOPSISDIV"
108 CLASS="FUNCSYNOPSISINFO"
109 >#include <cyg/power/power.h>
111 extern PowerController __POWER__[], __POWER_END__;
112 extern PowerController power_controller_cpu;
113 extern cyg_handle_t power_thread_handle;</PRE
121 > PowerMode power_get_mode
129 > PowerMode power_get_desired_mode
137 > PowerMode power_get_controller_mode
139 >( PowerController* controller
146 > PowerMode power_get_controller_desired_mode
148 >( PowerController* controller
155 > const char* power_get_controller_id
157 >( PowerController* controller
167 NAME="POWER-INFO-ACCESS"
170 >Accessing Power Controllers</H2
172 >All the power controllers in a system are held in a table, filled in
173 at link-time. The symbols <TT
180 > can be used to iterate through this
181 table, for example:</P
189 CLASS="PROGRAMLISTING"
190 >PowerController* controller;
191 for (controller = &(__POWER__[0]);
192 controller != &(__POWER_END__);
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
213 >In most systems there will be one special controller,
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
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
232 NAME="POWER-INFO-GLOBAL"
235 >Global Power Modes</H2
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
244 >PowerMode_Active</TT
256 >. In normal circumstances it is
260 > would be returned since
261 that mode generally means that the cpu is no longer running.</P
265 >power_get_desired_mode</TT
267 power mode that the system should be running at. Most of the time this
268 will be the same value as returned by
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
279 > will return the mode
280 the system was running at before the mode change started, and
283 >power_get_desired_mode</TT
284 > will return the mode the
285 system should end up in when the mode change completes, barring
294 NAME="POWER-INFO-INDIVIDUAL"
297 >Individual Controller Power Modes</H2
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
303 >power_get_controller_mode</TT
305 takes a single argument, a pointer to a power controller, and returns
306 the power mode that controller is currently running at. Similarly
309 >power_get_controller_desired_mode</TT
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
319 HREF="power-change.html#POWER-CHANGE-CONTROLLER"
320 >individual controllers</A
322 HREF="power-attached.html"
325 global mode changes.</P
330 NAME="POWER-INFO-IDS"
333 >Power Controller Identification</H2
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
349 >CYGIMP_POWER_PROVIDE_STRINGS</TT
351 each power controller will contain a pointer to a constant string
352 which can be accessed via a 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
366 CLASS="PROGRAMLISTING"
367 >#include <stdio.h>
368 #include <pkgconf/system.h>
370 # error The power management package is not present.
372 #include <pkgconf/power.h>
373 #ifndef CYGIMP_POWER_PROVIDE_STRINGS
374 # error Power controller identifiers are not available.
376 #include <cyg/power/power.h>
379 mode_to_string(PowerMode 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 = "<unknown>"; break;
393 main(int argc, char** argv)
395 PowerController* controller;
397 for (controller = &(__POWER__[0]);
398 controller != &(__POWER_END__);
400 printf("Controller @ %p: %s, %s\n", controller,
401 power_get_controller_id(controller),
402 mode_to_string(power_get_controller_mode(controller)));
413 NAME="POWER-INFO-THREAD"
416 >The Power Management Thread</H2
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
422 >power_thread_handle</TT
424 can be used for a variety of purposes, including manipulating that
425 thread's priority.</P
432 SUMMARY="Footer navigation table"
443 HREF="power-intro.html"
461 HREF="power-change.html"
477 HREF="services-power.html"
485 >Changing Power Modes</TD