doc/html/ref/kernel-characterization.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 >Kernel Real-time Characterization</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="The eCos Kernel"
  23 HREF="kernel.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Interrupt Handling"
  26 HREF="kernel-interrupts.html"><LINK
  27 REL="NEXT"
  28 TITLE="RedBoot&#8482; User's Guide"
  29 HREF="redboot.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="kernel-interrupts.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="redboot.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="KERNEL-CHARACTERIZATION">Kernel Real-time Characterization</H1
  83 ><DIV
  84 CLASS="REFNAMEDIV"
  85 ><A
  86 NAME="AEN2068"
  87 ></A
  88 ><H2
  89 >Name</H2
  90 >tm_basic&nbsp;--&nbsp;Measure the performance of the eCos kernel</DIV
  91 ><DIV
  92 CLASS="REFSECT1"
  93 ><A
  94 NAME="KERNEL-CHARACTERIZATION-DESCRIPTION"
  95 ></A
  96 ><H2
  97 >Description</H2
  98 ><P
  99 >When building a real-time system, care must be taken to ensure that
 100 the system will be able to perform properly within the constraints of
 101 that system. One of these constraints may be how fast certain
 102 operations can be performed. Another might be how deterministic the
 103 overall behavior of the system is. Lastly the memory footprint (size)
 104 and unit cost may be important.
 105         </P
 106 ><P
 107 >One of the major problems encountered while evaluating a system will
 108 be how to compare it with possible alternatives. Most manufacturers of
 109 real-time systems publish performance numbers, ostensibly so that
 110 users can compare the different offerings. However, what these numbers
 111 mean and how they were gathered is often not clear. The values are
 112 typically measured on a particular piece of hardware, so in order to
 113 truly compare, one must obtain measurements for exactly the same set
 114 of hardware that were gathered in a similar fashion.
 115         </P
 116 ><P
 117 >Two major items need to be present in any given set of measurements.
 118 First, the raw values for the various operations; these are typically
 119 quite easy to measure and will be available for most systems. Second,
 120 the determinacy of the numbers; in other words how much the value
 121 might change depending on other factors within the system. This value
 122 is affected by a number of factors: how long interrupts might be
 123 masked, whether or not the function can be interrupted, even very
 124 hardware-specific effects such as cache locality and pipeline usage.
 125 It is very difficult to measure the determinacy of any given
 126 operation, but that determinacy is fundamentally important to proper
 127 overall characterization of a system.
 128         </P
 129 ><P
 130 >In the discussion and numbers that follow, three key measurements are
 131 provided. The first measurement is an estimate of the interrupt
 132 latency: this is the length of time from when a hardware interrupt
 133 occurs until its Interrupt Service Routine (ISR) is called. The second
 134 measurement is an estimate of overall interrupt overhead: this is the
 135 length of time average interrupt processing takes, as measured by the
 136 real-time clock interrupt (other interrupt sources will certainly take
 137 a different amount of time, but this data cannot be easily gathered).
 138 The third measurement consists of the timings for the various kernel
 139 primitives.
 140           </P
 141 ></DIV
 142 ><DIV
 143 CLASS="REFSECT1"
 144 ><A
 145 NAME="KERNEL-CHARACTERIZATION-METHODOLOGY"
 146 ></A
 147 ><H2
 148 >Methodology</H2
 149 ><P
 150 >Key operations in the kernel were measured by using a simple test
 151 program which exercises the various kernel primitive operations. A
 152 hardware timer, normally the one used to drive the real-time clock,
 153 was used for these measurements. In most cases this timer can be read
 154 with quite high resolution, typically in the range of a few
 155 microseconds. For each measurement, the operation was repeated a
 156 number of times. Time stamps were obtained directly before and after
 157 the operation was performed. The data gathered for the entire set of
 158 operations was then analyzed, generating average (mean), maximum and
 159 minimum values. The sample variance (a measure of how close most
 160 samples are to the mean) was also calculated. The cost of obtaining
 161 the real-time clock timer values was also measured, and was subtracted
 162 from all other times.
 163           </P
 164 ><P
 165 >Most kernel functions can be measured separately. In each case, a
 166 reasonable number of iterations are performed. Where the test case
 167 involves a kernel object, for example creating a task, each iteration
 168 is performed on a different object. There is also a set of tests which
 169 measures the interactions between multiple tasks and certain kernel
 170 primitives. Most functions are tested in such a way as to determine
 171 the variations introduced by varying numbers of objects in the system.
 172 For example, the mailbox tests measure the cost of a 'peek' operation
 173 when the mailbox is empty, has a single item, and has multiple items
 174 present. In this way, any effects of the state of the object or how
 175 many items it contains can be determined.
 176           </P
 177 ><P
 178 >There are a few things to consider about these measurements. Firstly,
 179 they are quite micro in scale and only measure the operation in
 180 question. These measurements do not adequately describe how the
 181 timings would be perturbed in a real system with multiple interrupting
 182 sources. Secondly, the possible aberration incurred by the real-time
 183 clock (system heartbeat tick) is explicitly avoided. Virtually all
 184 kernel functions have been designed to be interruptible. Thus the
 185 times presented are typical, but best case, since any particular
 186 function may be interrupted by the clock tick processing. This number
 187 is explicitly calculated so that the value may be included in any
 188 deadline calculations required by the end user. Lastly, the reported
 189 measurements were obtained from a system built with all options at
 190 their default values. Kernel instrumentation and asserts are also
 191 disabled for these measurements. Any number of configuration options
 192 can change the measured results, sometimes quite dramatically. For
 193 example, mutexes are using priority inheritance in these measurements.
 194 The numbers will change if the system is built with priority
 195 inheritance on mutex variables turned off.
 196           </P
 197 ><P
 198 >The final value that is measured is an estimate of interrupt latency.
 199 This particular value is not explicitly calculated in the test program
 200 used, but rather by instrumenting the kernel itself. The raw number of
 201 timer ticks that elapse between the time the timer generates an
 202 interrupt and the start of the timer ISR is kept in the kernel. These
 203 values are printed by the test program after all other operations have
 204 been tested. Thus this should be a reasonable estimate of the
 205 interrupt latency over time.
 206           </P
 207 ></DIV
 208 ><DIV
 209 CLASS="REFSECT1"
 210 ><A
 211 NAME="KERNEL-CHARACTERIZATION-USING-MEASUREMENTS"
 212 ></A
 213 ><H2
 214 >Using these Measurements</H2
 215 ><P
 216 >These measurements can be used in a number of ways. The most typical
 217 use will be to compare different real-time kernel offerings on similar
 218 hardware, another will be to estimate the cost of implementing a task
 219 using eCos (applications can be examined to see what effect the kernel
 220 operations will have on the total execution time). Another use would
 221 be to observe how the tuning of the kernel affects overall operation.
 222           </P
 223 ></DIV
 224 ><DIV
 225 CLASS="REFSECT1"
 226 ><A
 227 NAME="KERNEL-CHARACTERIZATION-INFLUENCES"
 228 ></A
 229 ><H2
 230 >Influences on Performance</H2
 231 ><P
 232 >A number of factors can affect real-time performance in a system. One
 233 of the most common factors, yet most difficult to characterize, is the
 234 effect of device drivers and interrupts on system timings. Different
 235 device drivers will have differing requirements as to how long
 236 interrupts are suppressed, for example. The eCos system has been
 237 designed with this in mind, by separating the management of interrupts
 238 (ISR handlers) and the processing required by the interrupt
 239 (DSR&#8212;Deferred Service Routine&#8212; handlers). However, since
 240 there is so much variability here, and indeed most device drivers will
 241 come from the end users themselves, these effects cannot be reliably
 242 measured. Attempts have been made to measure the overhead of the
 243 single interrupt that eCos relies on, the real-time clock timer. This
 244 should give you a reasonable idea of the cost of executing interrupt
 245 handling for devices.
 246           </P
 247 ></DIV
 248 ><DIV
 249 CLASS="REFSECT1"
 250 ><A
 251 NAME="KERNEL-CHARACTERIZATION-MEASURED-ITEMS"
 252 ></A
 253 ><H2
 254 >Measured Items</H2
 255 ><P
 256 >This section describes the various tests and the numbers presented.
 257 All tests use the C kernel API (available by way of
 258 <TT
 259 CLASS="FILENAME"
 260 >cyg/kernel/kapi.h</TT
 261 >). There is a single main thread
 262 in the system that performs the various tests. Additional threads may
 263 be created as part of the testing, but these are short lived and are
 264 destroyed between tests unless otherwise noted. The terminology
 265 &#8220;lower priority&#8221; means a priority that is less important,
 266 not necessarily lower in numerical value. A higher priority thread
 267 will run in preference to a lower priority thread even though the
 268 priority value of the higher priority thread may be numerically less
 269 than that of the lower priority thread.
 270           </P
 271 ><DIV
 272 CLASS="REFSECT2"
 273 ><A
 274 NAME="KERNEL-CHARACTERIZATION-MEASURE-THREADS"
 275 ></A
 276 ><H3
 277 >Thread Primitives</H3
 278 ><P
 279 ></P
 280 ><DIV
 281 CLASS="VARIABLELIST"
 282 ><DL
 283 ><DT
 284 >Create thread</DT
 285 ><DD
 286 ><P
 287 >This test measures the <TT
 288 CLASS="FUNCTION"
 289 >cyg_thread_create()</TT
 290 > call.
 291 Each call creates a totally new thread. The set of threads created by
 292 this test will be reused in the subsequent thread primitive tests.
 293                 </P
 294 ></DD
 295 ><DT
 296 >Yield thread</DT
 297 ><DD
 298 ><P
 299 >This test measures the <TT
 300 CLASS="FUNCTION"
 301 >cyg_thread_yield()</TT
 302 > call.
 303 For this test, there are no other runnable threads, thus the test
 304 should just measure the overhead of trying to give up the CPU.
 305                 </P
 306 ></DD
 307 ><DT
 308 >Suspend &#0091;suspended&#0093; thread</DT
 309 ><DD
 310 ><P
 311 >This test measures the <TT
 312 CLASS="FUNCTION"
 313 >cyg_thread_suspend()</TT
 314 > call.
 315 A thread may be suspended multiple times; each thread is already
 316 suspended from its initial creation, and is suspended again.
 317                 </P
 318 ></DD
 319 ><DT
 320 >Resume thread</DT
 321 ><DD
 322 ><P
 323 >This test measures the <TT
 324 CLASS="FUNCTION"
 325 >cyg_thread_resume()</TT
 326 > call.
 327 All of the threads have a suspend count of 2, thus this call does not
 328 make them runnable. This test just measures the overhead of resuming a
 329 thread.
 330                 </P
 331 ></DD
 332 ><DT
 333 >Set priority</DT
 334 ><DD
 335 ><P
 336 >This test measures the <TT
 337 CLASS="FUNCTION"
 338 >cyg_thread_set_priority()</TT
 339 >
 340 call. Each thread, currently suspended, has its priority set to a new
 341 value.
 342                 </P
 343 ></DD
 344 ><DT
 345 >Get priority</DT
 346 ><DD
 347 ><P
 348 >This test measures the <TT
 349 CLASS="FUNCTION"
 350 >cyg_thread_get_priority()</TT
 351 >
 352 call.
 353                 </P
 354 ></DD
 355 ><DT
 356 >Kill &#0091;suspended&#0093; thread</DT
 357 ><DD
 358 ><P
 359 >This test measures the <TT
 360 CLASS="FUNCTION"
 361 >cyg_thread_kill()</TT
 362 > call.
 363 Each thread in the set is killed. All threads are known to be
 364 suspended before being killed.
 365                 </P
 366 ></DD
 367 ><DT
 368 >Yield &#0091;no other&#0093; thread</DT
 369 ><DD
 370 ><P
 371 >This test measures the <TT
 372 CLASS="FUNCTION"
 373 >cyg_thread_yield()</TT
 374 > call
 375 again. This is to demonstrate that the
 376 <TT
 377 CLASS="FUNCTION"
 378 >cyg_thread_yield()</TT
 379 > call has a fixed overhead,
 380 regardless of whether there are other threads in the system.
 381                 </P
 382 ></DD
 383 ><DT
 384 >Resume &#0091;suspended low priority&#0093; thread</DT
 385 ><DD
 386 ><P
 387 >This test measures the <TT
 388 CLASS="FUNCTION"
 389 >cyg_thread_resume()</TT
 390 > call
 391 again. In this case, the thread being resumed is lower priority than
 392 the main thread, thus it will simply become ready to run but not be
 393 granted the CPU. This test measures the cost of making a thread ready
 394 to run.
 395                 </P
 396 ></DD
 397 ><DT
 398 >Resume &#0091;runnable low priority&#0093; thread</DT
 399 ><DD
 400 ><P
 401 >This test measures the <TT
 402 CLASS="FUNCTION"
 403 >cyg_thread_resume()</TT
 404 > call
 405 again. In this case, the thread being resumed is lower priority than
 406 the main thread and has already been made runnable, so in fact the
 407 resume call has no effect.
 408                 </P
 409 ></DD
 410 ><DT
 411 >Suspend &#0091;runnable&#0093; thread</DT
 412 ><DD
 413 ><P
 414 >This test measures the <TT
 415 CLASS="FUNCTION"
 416 >cyg_thread_suspend()</TT
 417 > call
 418 again. In this case, each thread has already been made runnable (by
 419 previous tests).
 420                 </P
 421 ></DD
 422 ><DT
 423 >Yield &#0091;only low priority&#0093; thread</DT
 424 ><DD
 425 ><P
 426 >This test measures the <TT
 427 CLASS="FUNCTION"
 428 >cyg_thread_yield()</TT
 429 > call.
 430 In this case, there are many other runnable threads, but they are all
 431 lower priority than the main thread, thus no thread switches will take
 432 place.
 433                 </P
 434 ></DD
 435 ><DT
 436 >Suspend &#0091;runnable-&gt;not runnable&#0093; thread</DT
 437 ><DD
 438 ><P
 439 >This test measures the <TT
 440 CLASS="FUNCTION"
 441 >cyg_thread_suspend()</TT
 442 > call
 443 again. The thread being suspended will become non-runnable by this
 444 action.
 445                 </P
 446 ></DD
 447 ><DT
 448 >Kill &#0091;runnable&#0093; thread</DT
 449 ><DD
 450 ><P
 451 >This test measures the <TT
 452 CLASS="FUNCTION"
 453 >cyg_thread_kill()</TT
 454 > call
 455 again. In this case, the thread being killed is currently runnable,
 456 but lower priority than the main thread.
 457                 </P
 458 ></DD
 459 ><DT
 460 >Resume &#0091;high priority&#0093; thread</DT
 461 ><DD
 462 ><P
 463 >This test measures the <TT
 464 CLASS="FUNCTION"
 465 >cyg_thread_resume()</TT
 466 > call.
 467 The thread being resumed is higher priority than the main thread, thus
 468 a thread switch will take place on each call. In fact there will be
 469 two thread switches; one to the new higher priority thread and a
 470 second back to the test thread. The test thread exits immediately.
 471                 </P
 472 ></DD
 473 ><DT
 474 >Thread switch</DT
 475 ><DD
 476 ><P
 477 >This test attempts to measure the cost of switching from one thread to
 478 another. Two equal priority threads are started and they will each
 479 yield to the other for a number of iterations. A time stamp is
 480 gathered in one thread before the
 481 <TT
 482 CLASS="FUNCTION"
 483 >cyg_thread_yield()</TT
 484 > call and after the call in the
 485 other thread.
 486                 </P
 487 ></DD
 488 ></DL
 489 ></DIV
 490 ></DIV
 491 ><DIV
 492 CLASS="REFSECT2"
 493 ><A
 494 NAME="KERNEL-CHARACTERIZATION-MEASURE-SCHEDULER"
 495 ></A
 496 ><H3
 497 >Scheduler Primitives</H3
 498 ><P
 499 ></P
 500 ><DIV
 501 CLASS="VARIABLELIST"
 502 ><DL
 503 ><DT
 504 >Scheduler lock</DT
 505 ><DD
 506 ><P
 507 >This test measures the <TT
 508 CLASS="FUNCTION"
 509 >cyg_scheduler_lock()</TT
 510 > call.
 511                 </P
 512 ></DD
 513 ><DT
 514 >Scheduler unlock &#0091;0 threads&#0093;</DT
 515 ><DD
 516 ><P
 517 >This test measures the <TT
 518 CLASS="FUNCTION"
 519 >cyg_scheduler_unlock()</TT
 520 >
 521 call. There are no other threads in the system and the unlock happens
 522 immediately after a lock so there will be no pending DSR&#8217;s to
 523 run.
 524                 </P
 525 ></DD
 526 ><DT
 527 >Scheduler unlock &#0091;1 suspended thread&#0093;</DT
 528 ><DD
 529 ><P
 530 >This test measures the <TT
 531 CLASS="FUNCTION"
 532 >cyg_scheduler_unlock()</TT
 533 >
 534 call. There is one other thread in the system which is currently
 535 suspended.
 536                 </P
 537 ></DD
 538 ><DT
 539 >Scheduler unlock &#0091;many suspended threads&#0093;</DT
 540 ><DD
 541 ><P
 542 >This test measures the <TT
 543 CLASS="FUNCTION"
 544 >cyg_scheduler_unlock()</TT
 545 >
 546 call. There are many other threads in the system which are currently
 547 suspended. The purpose of this test is to determine the cost of having
 548 additional threads in the system when the scheduler is activated by
 549 way of <TT
 550 CLASS="FUNCTION"
 551 >cyg_scheduler_unlock()</TT
 552 >.
 553                 </P
 554 ></DD
 555 ><DT
 556 >Scheduler unlock &#0091;many low priority threads&#0093;</DT
 557 ><DD
 558 ><P
 559 >This test measures the <TT
 560 CLASS="FUNCTION"
 561 >cyg_scheduler_unlock()</TT
 562 >
 563 call. There are many other threads in the system which are runnable
 564 but are lower priority than the main thread. The purpose of this test
 565 is to determine the cost of having additional threads in the system
 566 when the scheduler is activated by way of
 567 <TT
 568 CLASS="FUNCTION"
 569 >cyg_scheduler_unlock()</TT
 570 >.
 571                 </P
 572 ></DD
 573 ></DL
 574 ></DIV
 575 ></DIV
 576 ><DIV
 577 CLASS="REFSECT2"
 578 ><A
 579 NAME="KERNEL-CHARACTERIZATION-MEASURE-MUTEX"
 580 ></A
 581 ><H3
 582 >Mutex Primitives</H3
 583 ><P
 584 ></P
 585 ><DIV
 586 CLASS="VARIABLELIST"
 587 ><DL
 588 ><DT
 589 >Init mutex</DT
 590 ><DD
 591 ><P
 592 >This test measures the <TT
 593 CLASS="FUNCTION"
 594 >cyg_mutex_init()</TT
 595 > call. A
 596 number of separate mutex variables are created. The purpose of this
 597 test is to measure the cost of creating a new mutex and introducing it
 598 to the system.
 599                 </P
 600 ></DD
 601 ><DT
 602 >Lock &#0091;unlocked&#0093; mutex</DT
 603 ><DD
 604 ><P
 605 >This test measures the <TT
 606 CLASS="FUNCTION"
 607 >cyg_mutex_lock()</TT
 608 > call. The
 609 purpose of this test is to measure the cost of locking a mutex which
 610 is currently unlocked. There are no other threads executing in the
 611 system while this test runs.
 612                 </P
 613 ></DD
 614 ><DT
 615 >Unlock &#0091;locked&#0093; mutex</DT
 616 ><DD
 617 ><P
 618 >This test measures the <TT
 619 CLASS="FUNCTION"
 620 >cyg_mutex_unlock()</TT
 621 > call.
 622 The purpose of this test is to measure the cost of unlocking a mutex
 623 which is currently locked. There are no other threads executing in the
 624 system while this test runs.
 625                 </P
 626 ></DD
 627 ><DT
 628 >Trylock &#0091;unlocked&#0093; mutex</DT
 629 ><DD
 630 ><P
 631 >This test measures the <TT
 632 CLASS="FUNCTION"
 633 >cyg_mutex_trylock()</TT
 634 > call.
 635 The purpose of this test is to measure the cost of locking a mutex
 636 which is currently unlocked. There are no other threads executing in
 637 the system while this test runs.
 638                 </P
 639 ></DD
 640 ><DT
 641 >Trylock &#0091;locked&#0093; mutex</DT
 642 ><DD
 643 ><P
 644 >This test measures the <TT
 645 CLASS="FUNCTION"
 646 >cyg_mutex_trylock()</TT
 647 > call.
 648 The purpose of this test is to measure the cost of locking a mutex
 649 which is currently locked. There are no other threads executing in the
 650 system while this test runs.
 651                 </P
 652 ></DD
 653 ><DT
 654 >Destroy mutex</DT
 655 ><DD
 656 ><P
 657 >This test measures the <TT
 658 CLASS="FUNCTION"
 659 >cyg_mutex_destroy()</TT
 660 > call.
 661 The purpose of this test is to measure the cost of deleting a mutex
 662 from the system. There are no other threads executing in the system
 663 while this test runs.
 664                 </P
 665 ></DD
 666 ><DT
 667 >Unlock/Lock mutex</DT
 668 ><DD
 669 ><P
 670 >This test attempts to measure the cost of unlocking a mutex for which
 671 there is another higher priority thread waiting. When the mutex is
 672 unlocked, the higher priority waiting thread will immediately take the
 673 lock. The time from when the unlock is issued until after the lock
 674 succeeds in the second thread is measured, thus giving the round-trip
 675 or circuit time for this type of synchronizer.
 676                 </P
 677 ></DD
 678 ></DL
 679 ></DIV
 680 ></DIV
 681 ><DIV
 682 CLASS="REFSECT2"
 683 ><A
 684 NAME="KERNEL-CHARACTERIZATION-MEASURE-MAILBOX"
 685 ></A
 686 ><H3
 687 >Mailbox Primitives</H3
 688 ><P
 689 ></P
 690 ><DIV
 691 CLASS="VARIABLELIST"
 692 ><DL
 693 ><DT
 694 >Create mbox</DT
 695 ><DD
 696 ><P
 697 >This test measures the <TT
 698 CLASS="FUNCTION"
 699 >cyg_mbox_create()</TT
 700 > call. A
 701 number of separate mailboxes is created. The purpose of this test is
 702 to measure the cost of creating a new mailbox and introducing it to
 703 the system.
 704                 </P
 705 ></DD
 706 ><DT
 707 >Peek &#0091;empty&#0093; mbox</DT
 708 ><DD
 709 ><P
 710 >This test measures the <TT
 711 CLASS="FUNCTION"
 712 >cyg_mbox_peek()</TT
 713 > call. An
 714 attempt is made to peek the value in each mailbox, which is currently
 715 empty. The purpose of this test is to measure the cost of checking a
 716 mailbox for a value without blocking.
 717                 </P
 718 ></DD
 719 ><DT
 720 >Put &#0091;first&#0093; mbox</DT
 721 ><DD
 722 ><P
 723 >This test measures the <TT
 724 CLASS="FUNCTION"
 725 >cyg_mbox_put()</TT
 726 > call. One
 727 item is added to a currently empty mailbox. The purpose of this test
 728 is to measure the cost of adding an item to a mailbox. There are no
 729 other threads currently waiting for mailbox items to arrive.
 730                 </P
 731 ></DD
 732 ><DT
 733 >Peek &#0091;1 msg&#0093; mbox</DT
 734 ><DD
 735 ><P
 736 >This test measures the <TT
 737 CLASS="FUNCTION"
 738 >cyg_mbox_peek()</TT
 739 > call. An
 740 attempt is made to peek the value in each mailbox, which contains a
 741 single item. The purpose of this test is to measure the cost of
 742 checking a mailbox which has data to deliver.
 743                 </P
 744 ></DD
 745 ><DT
 746 >Put &#0091;second&#0093; mbox</DT
 747 ><DD
 748 ><P
 749 >This test measures the <TT
 750 CLASS="FUNCTION"
 751 >cyg_mbox_put()</TT
 752 > call. A
 753 second item is added to a mailbox. The purpose of this test is to
 754 measure the cost of adding an additional item to a mailbox. There are
 755 no other threads currently waiting for mailbox items to arrive.
 756                 </P
 757 ></DD
 758 ><DT
 759 >Peek &#0091;2 msgs&#0093; mbox</DT
 760 ><DD
 761 ><P
 762 >This test measures the <TT
 763 CLASS="FUNCTION"
 764 >cyg_mbox_peek()</TT
 765 > call. An
 766 attempt is made to peek the value in each mailbox, which contains two
 767 items. The purpose of this test is to measure the cost of checking a
 768 mailbox which has data to deliver.
 769                 </P
 770 ></DD
 771 ><DT
 772 >Get &#0091;first&#0093; mbox</DT
 773 ><DD
 774 ><P
 775 >This test measures the <TT
 776 CLASS="FUNCTION"
 777 >cyg_mbox_get()</TT
 778 > call. The
 779 first item is removed from a mailbox that currently contains two
 780 items. The purpose of this test is to measure the cost of obtaining an
 781 item from a mailbox without blocking.
 782               </P
 783 ></DD
 784 ><DT
 785 >Get &#0091;second&#0093; mbox</DT
 786 ><DD
 787 ><P
 788 >This test measures the <TT
 789 CLASS="FUNCTION"
 790 >cyg_mbox_get()</TT
 791 > call. The
 792 last item is removed from a mailbox that currently contains one item.
 793 The purpose of this test is to measure the cost of obtaining an item
 794 from a mailbox without blocking.
 795                 </P
 796 ></DD
 797 ><DT
 798 >Tryput &#0091;first&#0093; mbox</DT
 799 ><DD
 800 ><P
 801 >This test measures the <TT
 802 CLASS="FUNCTION"
 803 >cyg_mbox_tryput()</TT
 804 > call. A
 805 single item is added to a currently empty mailbox. The purpose of this
 806 test is to measure the cost of adding an item to a mailbox.
 807                 </P
 808 ></DD
 809 ><DT
 810 >Peek item &#0091;non-empty&#0093; mbox</DT
 811 ><DD
 812 ><P
 813 >This test measures the <TT
 814 CLASS="FUNCTION"
 815 >cyg_mbox_peek_item()</TT
 816 > call.
 817 A single item is fetched from a mailbox that contains a single item.
 818 The purpose of this test is to measure the cost of obtaining an item
 819 without disturbing the mailbox.
 820                 </P
 821 ></DD
 822 ><DT
 823 >Tryget &#0091;non-empty&#0093; mbox</DT
 824 ><DD
 825 ><P
 826 >This test measures the <TT
 827 CLASS="FUNCTION"
 828 >cyg_mbox_tryget()</TT
 829 > call. A
 830 single item is removed from a mailbox that contains exactly one item.
 831 The purpose of this test is to measure the cost of obtaining one item
 832 from a non-empty mailbox.
 833                 </P
 834 ></DD
 835 ><DT
 836 >Peek item &#0091;empty&#0093; mbox</DT
 837 ><DD
 838 ><P
 839 >This test measures the <TT
 840 CLASS="FUNCTION"
 841 >cyg_mbox_peek_item()</TT
 842 > call.
 843 An attempt is made to fetch an item from a mailbox that is empty. The
 844 purpose of this test is to measure the cost of trying to obtain an
 845 item when the mailbox is empty.
 846                 </P
 847 ></DD
 848 ><DT
 849 >Tryget &#0091;empty&#0093; mbox</DT
 850 ><DD
 851 ><P
 852 >This test measures the <TT
 853 CLASS="FUNCTION"
 854 >cyg_mbox_tryget()</TT
 855 > call. An
 856 attempt is made to fetch an item from a mailbox that is empty. The
 857 purpose of this test is to measure the cost of trying to obtain an
 858 item when the mailbox is empty.
 859                 </P
 860 ></DD
 861 ><DT
 862 >Waiting to get mbox</DT
 863 ><DD
 864 ><P
 865 >This test measures the <TT
 866 CLASS="FUNCTION"
 867 >cyg_mbox_waiting_to_get()</TT
 868 >
 869 call. The purpose of this test is to measure the cost of determining
 870 how many threads are waiting to obtain a message from this mailbox.
 871                 </P
 872 ></DD
 873 ><DT
 874 >Waiting to put mbox</DT
 875 ><DD
 876 ><P
 877 >This test measures the <TT
 878 CLASS="FUNCTION"
 879 >cyg_mbox_waiting_to_put()</TT
 880 >
 881 call. The purpose of this test is to measure the cost of determining
 882 how many threads are waiting to put a message into this mailbox.
 883                 </P
 884 ></DD
 885 ><DT
 886 >Delete mbox</DT
 887 ><DD
 888 ><P
 889 >This test measures the <TT
 890 CLASS="FUNCTION"
 891 >cyg_mbox_delete()</TT
 892 > call.
 893 The purpose of this test is to measure the cost of destroying a
 894 mailbox and removing it from the system.
 895                 </P
 896 ></DD
 897 ><DT
 898 >Put/Get mbox</DT
 899 ><DD
 900 ><P
 901 >In this round-trip test, one thread is sending data to a mailbox that
 902 is being consumed by another thread. The time from when the data is
 903 put into the mailbox until it has been delivered to the waiting thread
 904 is measured. Note that this time will contain a thread switch.
 905                 </P
 906 ></DD
 907 ></DL
 908 ></DIV
 909 ></DIV
 910 ><DIV
 911 CLASS="REFSECT2"
 912 ><A
 913 NAME="KERNEL-CHARACTERIZATION-MEASURE-SEMAPHORE"
 914 ></A
 915 ><H3
 916 >Semaphore Primitives</H3
 917 ><P
 918 ></P
 919 ><DIV
 920 CLASS="VARIABLELIST"
 921 ><DL
 922 ><DT
 923 >Init semaphore</DT
 924 ><DD
 925 ><P
 926 >This test measures the <TT
 927 CLASS="FUNCTION"
 928 >cyg_semaphore_init()</TT
 929 > call.
 930 A number of separate semaphore objects are created and introduced to
 931 the system. The purpose of this test is to measure the cost of
 932 creating a new semaphore.
 933                 </P
 934 ></DD
 935 ><DT
 936 >Post &#0091;0&#0093; semaphore</DT
 937 ><DD
 938 ><P
 939 >This test measures the <TT
 940 CLASS="FUNCTION"
 941 >cyg_semaphore_post()</TT
 942 > call.
 943 Each semaphore currently has a value of 0 and there are no other
 944 threads in the system. The purpose of this test is to measure the
 945 overhead cost of posting to a semaphore. This cost will differ if
 946 there is a thread waiting for the semaphore.
 947                 </P
 948 ></DD
 949 ><DT
 950 >Wait &#0091;1&#0093; semaphore</DT
 951 ><DD
 952 ><P
 953 >This test measures the <TT
 954 CLASS="FUNCTION"
 955 >cyg_semaphore_wait()</TT
 956 > call.
 957 The semaphore has a current value of 1 so the call is non-blocking.
 958 The purpose of the test is to measure the overhead of
 959 &#8220;taking&#8221; a semaphore.
 960                 </P
 961 ></DD
 962 ><DT
 963 >Trywait &#0091;0&#0093; semaphore</DT
 964 ><DD
 965 ><P
 966 >This test measures the <TT
 967 CLASS="FUNCTION"
 968 >cyg_semaphore_trywait()</TT
 969 >
 970 call. The semaphore has a value of 0 when the call is made. The
 971 purpose of this test is to measure the cost of seeing if a semaphore
 972 can be &#8220;taken&#8221; without blocking. In this case, the answer
 973 would be no.
 974                 </P
 975 ></DD
 976 ><DT
 977 >Trywait &#0091;1&#0093; semaphore</DT
 978 ><DD
 979 ><P
 980 >This test measures the <TT
 981 CLASS="FUNCTION"
 982 >cyg_semaphore_trywait()</TT
 983 >
 984 call. The semaphore has a value of 1 when the call is made. The
 985 purpose of this test is to measure the cost of seeing if a semaphore
 986 can be &#8220;taken&#8221; without blocking. In this case, the answer
 987 would be yes.
 988                 </P
 989 ></DD
 990 ><DT
 991 >Peek semaphore</DT
 992 ><DD
 993 ><P
 994 >This test measures the <TT
 995 CLASS="FUNCTION"
 996 >cyg_semaphore_peek()</TT
 997 > call.
 998 The purpose of this test is to measure the cost of obtaining the
 999 current semaphore count value.
1000                 </P
1001 ></DD
1002 ><DT
1003 >Destroy semaphore</DT
1004 ><DD
1005 ><P
1006 >This test measures the <TT
1007 CLASS="FUNCTION"
1008 >cyg_semaphore_destroy()</TT
1009 >
1010 call. The purpose of this test is to measure the cost of deleting a
1011 semaphore from the system.
1012                 </P
1013 ></DD
1014 ><DT
1015 >Post/Wait semaphore</DT
1016 ><DD
1017 ><P
1018 >In this round-trip test, two threads are passing control back and
1019 forth by using a semaphore. The time from when one thread calls
1020 <TT
1021 CLASS="FUNCTION"
1022 >cyg_semaphore_post()</TT
1023 > until the other thread
1024 completes its <TT
1025 CLASS="FUNCTION"
1026 >cyg_semaphore_wait()</TT
1027 > is measured.
1028 Note that each iteration of this test will involve a thread switch.
1029                 </P
1030 ></DD
1031 ></DL
1032 ></DIV
1033 ></DIV
1034 ><DIV
1035 CLASS="REFSECT2"
1036 ><A
1037 NAME="KERNEL-CHARACTERIZATION-MEASURE-COUNTERS"
1038 ></A
1039 ><H3
1040 >Counters</H3
1041 ><P
1042 ></P
1043 ><DIV
1044 CLASS="VARIABLELIST"
1045 ><DL
1046 ><DT
1047 >Create counter</DT
1048 ><DD
1049 ><P
1050 >This test measures the <TT
1051 CLASS="FUNCTION"
1052 >cyg_counter_create()</TT
1053 > call.
1054 A number of separate counters are created. The purpose of this test is
1055 to measure the cost of creating a new counter and introducing it to
1056 the system.
1057                 </P
1058 ></DD
1059 ><DT
1060 >Get counter value</DT
1061 ><DD
1062 ><P
1063 >This test measures the
1064 <TT
1065 CLASS="FUNCTION"
1066 >cyg_counter_current_value()</TT
1067 > call. The current
1068 value of each counter is obtained.
1069                 </P
1070 ></DD
1071 ><DT
1072 >Set counter value</DT
1073 ><DD
1074 ><P
1075 >This test measures the <TT
1076 CLASS="FUNCTION"
1077 >cyg_counter_set_value()</TT
1078 >
1079 call. Each counter is set to a new value.
1080                 </P
1081 ></DD
1082 ><DT
1083 >Tick counter</DT
1084 ><DD
1085 ><P
1086 >This test measures the <TT
1087 CLASS="FUNCTION"
1088 >cyg_counter_tick()</TT
1089 > call.
1090 Each counter is &#8220;ticked&#8221; once.
1091                 </P
1092 ></DD
1093 ><DT
1094 >Delete counter</DT
1095 ><DD
1096 ><P
1097 >This test measures the <TT
1098 CLASS="FUNCTION"
1099 >cyg_counter_delete()</TT
1100 > call.
1101 Each counter is deleted from the system. The purpose of this test is
1102 to measure the cost of deleting a counter object.
1103                 </P
1104 ></DD
1105 ></DL
1106 ></DIV
1107 ></DIV
1108 ><DIV
1109 CLASS="REFSECT2"
1110 ><A
1111 NAME="KERNEL-CHARACTERIZATION-MEASURE-ALARMS"
1112 ></A
1113 ><H3
1114 >Alarms</H3
1115 ><P
1116 ></P
1117 ><DIV
1118 CLASS="VARIABLELIST"
1119 ><DL
1120 ><DT
1121 >Create alarm</DT
1122 ><DD
1123 ><P
1124 >This test measures the <TT
1125 CLASS="FUNCTION"
1126 >cyg_alarm_create()</TT
1127 > call. A
1128 number of separate alarms are created, all attached to the same
1129 counter object. The purpose of this test is to measure the cost of
1130 creating a new counter and introducing it to the system.
1131                 </P
1132 ></DD
1133 ><DT
1134 >Initialize alarm</DT
1135 ><DD
1136 ><P
1137 >This test measures the <TT
1138 CLASS="FUNCTION"
1139 >cyg_alarm_initialize()</TT
1140 >
1141 call. Each alarm is initialized to a small value.
1142                 </P
1143 ></DD
1144 ><DT
1145 >Disable alarm</DT
1146 ><DD
1147 ><P
1148 >This test measures the <TT
1149 CLASS="FUNCTION"
1150 >cyg_alarm_disable()</TT
1151 > call.
1152 Each alarm is explicitly disabled.
1153                 </P
1154 ></DD
1155 ><DT
1156 >Enable alarm</DT
1157 ><DD
1158 ><P
1159 >This test measures the <TT
1160 CLASS="FUNCTION"
1161 >cyg_alarm_enable()</TT
1162 > call.
1163 Each alarm is explicitly enabled.
1164                 </P
1165 ></DD
1166 ><DT
1167 >Delete alarm</DT
1168 ><DD
1169 ><P
1170 >This test measures the <TT
1171 CLASS="FUNCTION"
1172 >cyg_alarm_delete()</TT
1173 > call.
1174 Each alarm is destroyed. The purpose of this test is to measure the
1175 cost of deleting an alarm and removing it from the system.
1176                 </P
1177 ></DD
1178 ><DT
1179 >Tick counter &#0091;1 alarm&#0093;</DT
1180 ><DD
1181 ><P
1182 >This test measures the <TT
1183 CLASS="FUNCTION"
1184 >cyg_counter_tick()</TT
1185 > call. A
1186 counter is created that has a single alarm attached to it. The purpose
1187 of this test is to measure the cost of &#8220;ticking&#8221; a counter
1188 when it has a single attached alarm. In this test, the alarm is not
1189 activated (fired).
1190                 </P
1191 ></DD
1192 ><DT
1193 >Tick counter &#0091;many alarms&#0093;</DT
1194 ><DD
1195 ><P
1196 >This test measures the <TT
1197 CLASS="FUNCTION"
1198 >cyg_counter_tick()</TT
1199 > call. A
1200 counter is created that has multiple alarms attached to it. The
1201 purpose of this test is to measure the cost of &#8220;ticking&#8221; a
1202 counter when it has many attached alarms. In this test, the alarms are
1203 not activated (fired).
1204                 </P
1205 ></DD
1206 ><DT
1207 >Tick &amp; fire counter &#0091;1 alarm&#0093;</DT
1208 ><DD
1209 ><P
1210 >This test measures the <TT
1211 CLASS="FUNCTION"
1212 >cyg_counter_tick()</TT
1213 > call. A
1214 counter is created that has a single alarm attached to it. The purpose
1215 of this test is to measure the cost of &#8220;ticking&#8221; a counter
1216 when it has a single attached alarm. In this test, the alarm is
1217 activated (fired). Thus the measured time will include the overhead of
1218 calling the alarm callback function.
1219                 </P
1220 ></DD
1221 ><DT
1222 >Tick &amp; fire counter &#0091;many alarms&#0093;</DT
1223 ><DD
1224 ><P
1225 >This test measures the <TT
1226 CLASS="FUNCTION"
1227 >cyg_counter_tick()</TT
1228 > call. A
1229 counter is created that has multiple alarms attached to it. The
1230 purpose of this test is to measure the cost of &#8220;ticking&#8221; a
1231 counter when it has many attached alarms. In this test, the alarms are
1232 activated (fired). Thus the measured time will include the overhead of
1233 calling the alarm callback function.
1234                 </P
1235 ></DD
1236 ><DT
1237 >Alarm latency &#0091;0 threads&#0093;</DT
1238 ><DD
1239 ><P
1240 >This test attempts to measure the latency in calling an alarm callback
1241 function. The time from the clock interrupt until the alarm function
1242 is called is measured. In this test, there are no threads that can be
1243 run, other than the system idle thread, when the clock interrupt
1244 occurs (all threads are suspended).
1245                 </P
1246 ></DD
1247 ><DT
1248 >Alarm latency &#0091;2 threads&#0093;</DT
1249 ><DD
1250 ><P
1251 >This test attempts to measure the latency in calling an alarm callback
1252 function. The time from the clock interrupt until the alarm function
1253 is called is measured. In this test, there are exactly two threads
1254 which are running when the clock interrupt occurs. They are simply
1255 passing back and forth by way of the
1256 <TT
1257 CLASS="FUNCTION"
1258 >cyg_thread_yield()</TT
1259 > call. The purpose of this test
1260 is to measure the variations in the latency when there are executing
1261 threads.
1262                 </P
1263 ></DD
1264 ><DT
1265 >Alarm latency &#0091;many threads&#0093;</DT
1266 ><DD
1267 ><P
1268 >This test attempts to measure the latency in calling an alarm callback
1269 function. The time from the clock interrupt until the alarm function
1270 is called is measured. In this test, there are a number of threads
1271 which are running when the clock interrupt occurs. They are simply
1272 passing back and forth by way of the
1273 <TT
1274 CLASS="FUNCTION"
1275 >cyg_thread_yield()</TT
1276 > call. The purpose of this test
1277 is to measure the variations in the latency when there are many
1278 executing threads.
1279                 </P
1280 ></DD
1281 ></DL
1282 ></DIV
1283 ></DIV
1284 ></DIV
1285 ><DIV
1286 CLASS="NAVFOOTER"
1287 ><HR
1288 ALIGN="LEFT"
1289 WIDTH="100%"><TABLE
1290 SUMMARY="Footer navigation table"
1291 WIDTH="100%"
1292 BORDER="0"
1293 CELLPADDING="0"
1294 CELLSPACING="0"
1295 ><TR
1296 ><TD
1297 WIDTH="33%"
1298 ALIGN="left"
1299 VALIGN="top"
1300 ><A
1301 HREF="kernel-interrupts.html"
1302 ACCESSKEY="P"
1303 >Prev</A
1304 ></TD
1305 ><TD
1306 WIDTH="34%"
1307 ALIGN="center"
1308 VALIGN="top"
1309 ><A
1310 HREF="ecos-ref.html"
1311 ACCESSKEY="H"
1312 >Home</A
1313 ></TD
1314 ><TD
1315 WIDTH="33%"
1316 ALIGN="right"
1317 VALIGN="top"
1318 ><A
1319 HREF="redboot.html"
1320 ACCESSKEY="N"
1321 >Next</A
1322 ></TD
1323 ></TR
1324 ><TR
1325 ><TD
1326 WIDTH="33%"
1327 ALIGN="left"
1328 VALIGN="top"
1329 >Interrupt Handling</TD
1330 ><TD
1331 WIDTH="34%"
1332 ALIGN="center"
1333 VALIGN="top"
1334 ><A
1335 HREF="kernel.html"
1336 ACCESSKEY="U"
1337 >Up</A
1338 ></TD
1339 ><TD
1340 WIDTH="33%"
1341 ALIGN="right"
1342 VALIGN="top"
1343 >RedBoot&#8482; User's Guide</TD
1344 ></TR
1345 ></TABLE
1346 ></DIV
1347 ></BODY
1348 ></HTML
1349 >