doc/html/ref/cpuload-functions.html

   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.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >CPU Load Measurements</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="CPU load measurements"
  23 HREF="services-cpuload.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="CPU load measurements"
  26 HREF="services-cpuload.html"><LINK
  27 REL="NEXT"
  28 TITLE="Application profiling"
  29 HREF="services-profile-gprof.html"></HEAD
  30 ><BODY
  31 CLASS="CHAPTER"
  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="services-cpuload.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="services-profile-gprof.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="CHAPTER"
  82 ><H1
  83 ><A
  84 NAME="CPULOAD-FUNCTIONS">Chapter 51. CPU Load Measurements</H1
  85 ><DIV
  86 CLASS="SECT1"
  87 ><H1
  88 CLASS="SECT1"
  89 ><A
  90 NAME="SERVICES-CPULOAD-API">CPU Load API</H1
  91 ><P
  92 >The package allows the CPU load to be estimated. The measurement code
  93 must first be calibrated to the target it is running on. Once this
  94 has been performed the measurement process can be started. This is a
  95 continuous process, so always providing the most up to data
  96 measurements. The process can be stopped at any time if required. Once
  97 the process is active, the results can be retrieved.</P
  98 ><P
  99 >Note that if the target/processor performs any power saving actions,
 100 such as reducing the clock speed, or halting until the next interrupt
 101 etc, these will interfere with the CPU load measurement. Under these
 102 conditions the measurement results are undefined. The synthetic target
 103 is one such system. See the implementation details at the foot of this
 104 page for further information.  </P
 105 ><P
 106 >SMP systems are not supported, only uniprocessor system.</P
 107 ><P
 108 > The API for load measuring functions can be
 109 found in the file <TT
 110 CLASS="FILENAME"
 111 >cyg/cpuload/cpuload.h</TT
 112 >.</P
 113 ><DIV
 114 CLASS="SECT2"
 115 ><H2
 116 CLASS="SECT2"
 117 ><A
 118 NAME="SERVICES-CPULOAD-API-CYG-CPULOAD-CALIBRATE">cyg_cpuload_calibrate</H2
 119 ><P
 120 >This function is used to calibrate the cpu load measurement code. It
 121 makes a measurement to determine the CPU properties while idle.</P
 122 ><TABLE
 123 BORDER="5"
 124 BGCOLOR="#E0E0F0"
 125 WIDTH="70%"
 126 ><TR
 127 ><TD
 128 ><PRE
 129 CLASS="PROGRAMLISTING"
 130 >void cyg_cpuload_calibrate(cyg_uint32  *calibration);</PRE
 131 ></TD
 132 ></TR
 133 ></TABLE
 134 ><P
 135 >The function returns the calibration value at the location pointed to
 136 by <TT
 137 CLASS="PARAMETER"
 138 ><I
 139 >calibration</I
 140 ></TT
 141 >.</P
 142 ><P
 143 >This function is quite unusual. For it to work correctly a few
 144 conditions must be met. The function makes use of the two highest
 145 thread priorities. No other threads must be using these priorities
 146 while the function is being used. The kernel scheduler must be started
 147 and not disabled. The function takes 100ms to complete during which
 148 time no other threads will be run.</P
 149 ></DIV
 150 ><DIV
 151 CLASS="SECT2"
 152 ><H2
 153 CLASS="SECT2"
 154 ><A
 155 NAME="SERVICES-CPULOAD-API-CYG-CPULOAD-CREATE">cyg_cpuload_create</H2
 156 ><P
 157 >This function starts the CPU load measurments.</P
 158 ><TABLE
 159 BORDER="5"
 160 BGCOLOR="#E0E0F0"
 161 WIDTH="70%"
 162 ><TR
 163 ><TD
 164 ><PRE
 165 CLASS="PROGRAMLISTING"
 166 >void cyg_cpuload_create(cyg_cpuload_t *cpuload,
 167                         cyg_uint32 calibrate,
 168                         cyg_handle_t *handle);</PRE
 169 ></TD
 170 ></TR
 171 ></TABLE
 172 ><P
 173 >The measurement process is started and a handle to it is returned in
 174 <TT
 175 CLASS="PARAMETER"
 176 ><I
 177 >*handle</I
 178 ></TT
 179 >. This handle is used to access the
 180 results and the stop the measurement process. </P
 181 ></DIV
 182 ><DIV
 183 CLASS="SECT2"
 184 ><H2
 185 CLASS="SECT2"
 186 ><A
 187 NAME="SERVICES-CPULOAD-API-CYG-CPULOAD-DELETE">cyg_cpuload_delete</H2
 188 ><P
 189 >This function stops the measurement process. </P
 190 ><TABLE
 191 BORDER="5"
 192 BGCOLOR="#E0E0F0"
 193 WIDTH="70%"
 194 ><TR
 195 ><TD
 196 ><PRE
 197 CLASS="PROGRAMLISTING"
 198 >void cyg_cpuload_delete(cyg_handle_t handle);</PRE
 199 ></TD
 200 ></TR
 201 ></TABLE
 202 ><P
 203 ><TT
 204 CLASS="PARAMETER"
 205 ><I
 206 >handle</I
 207 ></TT
 208 > should be the value returned by the create function.</P
 209 ></DIV
 210 ><DIV
 211 CLASS="SECT2"
 212 ><H2
 213 CLASS="SECT2"
 214 ><A
 215 NAME="SERVICES-CPULOAD-API-CYG-CPULOAD-GET">cyg_cpuload_get</H2
 216 ><P
 217 >This function returns the latest measurements.</P
 218 ><TABLE
 219 BORDER="5"
 220 BGCOLOR="#E0E0F0"
 221 WIDTH="70%"
 222 ><TR
 223 ><TD
 224 ><PRE
 225 CLASS="PROGRAMLISTING"
 226 >void cyg_cpuload_get(cyg_handle_t handle,
 227                  cyg_uint32 *average_point1s,
 228                  cyg_uint32 *average_1s,
 229                  cyg_uint32 *average_10s);</PRE
 230 ></TD
 231 ></TR
 232 ></TABLE
 233 ><P
 234 ><TT
 235 CLASS="PARAMETER"
 236 ><I
 237 >handle</I
 238 ></TT
 239 > should be the value returned by the
 240 create function. The load measurements for the last 100ms, 1s and 10s
 241 are returned in
 242 <TT
 243 CLASS="PARAMETER"
 244 ><I
 245 >*average_point1s</I
 246 ></TT
 247 >,<TT
 248 CLASS="PARAMETER"
 249 ><I
 250 >*average_1s</I
 251 ></TT
 252 >
 253 and <TT
 254 CLASS="PARAMETER"
 255 ><I
 256 >*average_10s</I
 257 ></TT
 258 > respectively.</P
 259 ></DIV
 260 ><DIV
 261 CLASS="SECT2"
 262 ><H2
 263 CLASS="SECT2"
 264 ><A
 265 NAME="SERVICES-CPULOAD-API-IMPLEMENTATION">Implementation details</H2
 266 ><P
 267 >This section gives a few details of how the measurements are
 268 made. This should help to understand what the results mean.</P
 269 ><P
 270 >When there are no other threads runnable, eCos will execute the idle
 271 thread. This thread is always runnable and uses the lowest thread
 272 priority. The idle thread does little. It is an endless loop which
 273 increments the variable, <TT
 274 CLASS="LITERAL"
 275 >idle_thread_loops</TT
 276 > and
 277 executes the macro <TT
 278 CLASS="LITERAL"
 279 >HAL_IDLE_THREAD_ACTION</TT
 280 >. The cpu
 281 load measurement code makes use of the variable. It periodically
 282 examines the value of the variable and sees how much it has
 283 changed. The idler the system, the more it will have incremented. From
 284 this it is simple to determine the load of the system.</P
 285 ><P
 286 >The function <TT
 287 CLASS="LITERAL"
 288 >cyg_cpuload_calibrate</TT
 289 > executes the
 290 idle thread for 100ms to determine how much
 291 <TT
 292 CLASS="LITERAL"
 293 >idle_thread_loops</TT
 294 > is incremented on a system idle
 295 for 100ms. <TT
 296 CLASS="LITERAL"
 297 >cyg_cpuload_create</TT
 298 > starts an alarm which
 299 every 100ms calls an alarm function. This function looks at the
 300 difference in <TT
 301 CLASS="LITERAL"
 302 >idle_thread_loops</TT
 303 > since the last
 304 invocation of the alarm function and so calculated how idle or busy
 305 the system has been. The structure <TT
 306 CLASS="LITERAL"
 307 >cyg_cpuload</TT
 308 > is
 309 updated during the alarm functions with the new results.  The 100ms
 310 result is simply the result from the last measurement period. A simple
 311 filter is used to average the load over a period of time, namely 1s
 312 and 10s. Due to rounding errors, the 1s and 10s value will probably
 313 never reach 100% on a fully loaded system, but 99% is often seen.</P
 314 ><P
 315 >As stated above, clever power management code will interfere with
 316 these measurements. The basic assumption is that the idle thread will
 317 be executed un-hindered and under the same conditions as when the
 318 calibration function was executed. If the CPU clock rate is reduced,
 319 the idle thread counter will be incremented less and so the CPU load
 320 measurements will give values too high. If the CPU is halted entirely,
 321 100% cpu load will be measured.</P
 322 ></DIV
 323 ></DIV
 324 ></DIV
 325 ><DIV
 326 CLASS="NAVFOOTER"
 327 ><HR
 328 ALIGN="LEFT"
 329 WIDTH="100%"><TABLE
 330 SUMMARY="Footer navigation table"
 331 WIDTH="100%"
 332 BORDER="0"
 333 CELLPADDING="0"
 334 CELLSPACING="0"
 335 ><TR
 336 ><TD
 337 WIDTH="33%"
 338 ALIGN="left"
 339 VALIGN="top"
 340 ><A
 341 HREF="services-cpuload.html"
 342 ACCESSKEY="P"
 343 >Prev</A
 344 ></TD
 345 ><TD
 346 WIDTH="34%"
 347 ALIGN="center"
 348 VALIGN="top"
 349 ><A
 350 HREF="ecos-ref.html"
 351 ACCESSKEY="H"
 352 >Home</A
 353 ></TD
 354 ><TD
 355 WIDTH="33%"
 356 ALIGN="right"
 357 VALIGN="top"
 358 ><A
 359 HREF="services-profile-gprof.html"
 360 ACCESSKEY="N"
 361 >Next</A
 362 ></TD
 363 ></TR
 364 ><TR
 365 ><TD
 366 WIDTH="33%"
 367 ALIGN="left"
 368 VALIGN="top"
 369 >CPU load measurements</TD
 370 ><TD
 371 WIDTH="34%"
 372 ALIGN="center"
 373 VALIGN="top"
 374 ><A
 375 HREF="services-cpuload.html"
 376 ACCESSKEY="U"
 377 >Up</A
 378 ></TD
 379 ><TD
 380 WIDTH="33%"
 381 ALIGN="right"
 382 VALIGN="top"
 383 >Application profiling</TD
 384 ></TR
 385 ></TABLE
 386 ></DIV
 387 ></BODY
 388 ></HTML
 389 >