doc/html/user-guide/kernel-instrumentation.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 Instrumentation</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 User Guide"
  20 HREF="ecos-user-guide.html"><LINK
  21 REL="UP"
  22 TITLE="Debugging Techniques"
  23 HREF="debugging-techniques.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Debugging Techniques"
  26 HREF="debugging-techniques.html"><LINK
  27 REL="NEXT"
  28 TITLE="Configuration and the Package Repository"
  29 HREF="configuration-and-the-package-repository.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  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 User Guide</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="debugging-techniques.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 27. Debugging Techniques</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="configuration-and-the-package-repository.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="SECT1"
  82 ><H1
  83 CLASS="SECT1"
  84 ><A
  85 NAME="KERNEL-INSTRUMENTATION">Kernel Instrumentation</H1
  86 ><P
  87 ><I
  88 CLASS="FIRSTTERM"
  89 >Instrument buffers</I
  90 > can be used to
  91           find out how many events of a given type happened in the
  92           kernel during execution of a program.</P
  93 ><P
  94 >You can monitor a class of several types of events, or
  95           you can just look at individual events. </P
  96 ><P
  97 >Examples of <I
  98 CLASS="FIRSTTERM"
  99 >events</I
 100 > that can be
 101           monitored are:
 102         </P
 103 ><P
 104 ></P
 105 ><UL
 106 ><LI
 107 ><P
 108 >scheduler events </P
 109 ></LI
 110 ><LI
 111 ><P
 112 >thread operations</P
 113 ></LI
 114 ><LI
 115 ><P
 116 >interrupts </P
 117 ></LI
 118 ><LI
 119 ><P
 120 >mutex operations </P
 121 ></LI
 122 ><LI
 123 ><P
 124 >binary semaphore operations </P
 125 ></LI
 126 ><LI
 127 ><P
 128 >counting semaphore operations </P
 129 ></LI
 130 ><LI
 131 ><P
 132 >clock ticks and interrupts </P
 133 ></LI
 134 ></UL
 135 ><P
 136 >Examples of fine-grained scheduler event types are: </P
 137 ><P
 138 ></P
 139 ><UL
 140 ><LI
 141 ><P
 142 >scheduler lock</P
 143 ></LI
 144 ><LI
 145 ><P
 146 >scheduler unlock</P
 147 ></LI
 148 ><LI
 149 ><P
 150 >rescheduling</P
 151 ></LI
 152 ><LI
 153 ><P
 154 >time slicing </P
 155 ></LI
 156 ></UL
 157 ><P
 158 >Information about the events is stored in an
 159           <I
 160 CLASS="FIRSTTERM"
 161 >event record</I
 162 >. The structure that
 163           defines this record has type <SPAN
 164 CLASS="TYPE"
 165 >struct
 166           Instrument_Record</SPAN
 167 >:</P
 168 ><P
 169 >The list of records is stored in an array called <SPAN
 170 CLASS="TYPE"
 171 >instrument_buffer</SPAN
 172 >
 173 which you can let the kernel provide or you can provide yourself
 174 by setting the configuration option <TT
 175 CLASS="LITERAL"
 176 >CYGVAR_KERNEL_INSTRUMENT_EXTERNAL_BUFFER</TT
 177 >. </P
 178 ><P
 179 >To write a program that examines the instrumentation
 180           buffers: </P
 181 ><P
 182 ></P
 183 ><OL
 184 TYPE="1"
 185 ><LI
 186 ><P
 187 >Enable instrumentation buffers in the <SPAN
 188 CLASS="PRODUCTNAME"
 189 >eCos</SPAN
 190 > kernel configuration.
 191 The component macro is <TT
 192 CLASS="LITERAL"
 193 >CYGPKG_KERNEL_INSTRUMENT</TT
 194 >.</P
 195 ></LI
 196 ><LI
 197 ><P
 198 >To allocate the buffers yourself, enable the configuration
 199 option <TT
 200 CLASS="LITERAL"
 201 >CYGVAR_KERNEL_INSTRUMENT_EXTERNAL_BUFFER</TT
 202 >. </P
 203 ></LI
 204 ><LI
 205 ><P
 206 >Include the header file
 207 <TT
 208 CLASS="FILENAME"
 209 >cyg/kernel/instrmnt.h</TT
 210 >
 211 .
 212 <TABLE
 213 BORDER="5"
 214 BGCOLOR="#E0E0F0"
 215 WIDTH="70%"
 216 ><TR
 217 ><TD
 218 ><PRE
 219 CLASS="PROGRAMLISTING"
 220 >#include &lt;cyg/kernel/instrmnt.h&gt;</PRE
 221 ></TD
 222 ></TR
 223 ></TABLE
 224 ></P
 225 ></LI
 226 ><LI
 227 ><P
 228 >The <SPAN
 229 CLASS="STRUCTNAME"
 230 >Instrumentation_Record</SPAN
 231 > structure
 232 is not published in the kernel header file. In the future there
 233 will be a cleaner mechanism to access it, but for now you should
 234 paste into your code in the following lines:
 235             </P
 236 ><TABLE
 237 BORDER="5"
 238 BGCOLOR="#E0E0F0"
 239 WIDTH="70%"
 240 ><TR
 241 ><TD
 242 ><PRE
 243 CLASS="PROGRAMLISTING"
 244 >struct Instrument_Record
 245 {
 246  CYG_WORD16 type; // record type
 247  CYG_WORD16 thread; // current thread id
 248  CYG_WORD timestamp; // 32 bit timestamp
 249  CYG_WORD arg1; // first arg
 250  CYG_WORD arg2; // second arg
 251 };</PRE
 252 ></TD
 253 ></TR
 254 ></TABLE
 255 ></LI
 256 ><LI
 257 ><P
 258 >Enable the events you want to record using
 259 <TT
 260 CLASS="FUNCTION"
 261 >cyg_instrument_enable()</TT
 262 >
 263 , and disable them later. Look at
 264 <TT
 265 CLASS="FILENAME"
 266 >cyg/kernel/instrmnt.h</TT
 267 >
 268  and the examples below to see what events can be enabled. </P
 269 ></LI
 270 ><LI
 271 ><P
 272 >Place the code you want to debug between the matching
 273 functions
 274 <TT
 275 CLASS="FUNCTION"
 276 >cyg_instrument_enable()</TT
 277 >
 278  and
 279 <TT
 280 CLASS="FUNCTION"
 281 >cyg_instrument_disable()</TT
 282 >
 283 . </P
 284 ></LI
 285 ><LI
 286 ><P
 287 >Examine the buffer. For now you need to look at the data
 288 in there (the example program below shows how to do that), and future
 289 versions of <SPAN
 290 CLASS="PRODUCTNAME"
 291 >eCos</SPAN
 292 > will include a host-side tool to help you understand
 293 the data. </P
 294 ></LI
 295 ></OL
 296 ><DIV
 297 CLASS="EXAMPLE"
 298 ><A
 299 NAME="AEN2358"><P
 300 ><B
 301 >Example 27-2. Using instrument buffers</B
 302 ></P
 303 ><P
 304 >This program is also provided in the
 305             <TT
 306 CLASS="FILENAME"
 307 >examples</TT
 308 > directory.
 309           </P
 310 ><TABLE
 311 BORDER="5"
 312 BGCOLOR="#E0E0F0"
 313 WIDTH="70%"
 314 ><TR
 315 ><TD
 316 ><PRE
 317 CLASS="PROGRAMLISTING"
 318 >/* this is a program which uses <SPAN
 319 CLASS="PRODUCTNAME"
 320 >eCos</SPAN
 321 > instrumentation buffers; it needs
 322  to be linked with a kernel which was compiled with support for
 323  instrumentation */
 324
 325 #include &lt;stdio.h&gt;
 326 #include &lt;pkgconf/kernel.h&gt;
 327 #include &lt;cyg/kernel/instrmnt.h&gt;
 328 #include &lt;cyg/kernel/kapi.h&gt;
 329
 330 #ifndef CYGVAR_KERNEL_INSTRUMENT_EXTERNAL_BUFFER
 331 # error You must configure eCos with CYGVAR_KERNEL_INSTRUMENT_EXTERNAL_BUFFER
 332 #endif
 333
 334 struct Instrument_Record
 335 {
 336  CYG_WORD16 type; // record type
 337  CYG_WORD16 thread; // current thread id
 338  CYG_WORD timestamp; // 32 bit timestamp
 339  CYG_WORD arg1; // first arg
 340  CYG_WORD arg2; // second arg
 341 };
 342
 343 struct Instrument_Record instrument_buffer[20];
 344 cyg_uint32 instrument_buffer_size = 20;
 345
 346 int main(void)
 347 {
 348  int i;
 349
 350  cyg_instrument_enable(CYG_INSTRUMENT_CLASS_CLOCK, 0);
 351  cyg_instrument_enable(CYG_INSTRUMENT_CLASS_THREAD, 0);
 352  cyg_instrument_enable(CYG_INSTRUMENT_CLASS_ALARM, 0);
 353
 354  printf("Program to play with instrumentation buffer\n");
 355
 356  cyg_thread_delay(2);
 357
 358  cyg_instrument_disable(CYG_INSTRUMENT_CLASS_CLOCK, 0);
 359  cyg_instrument_disable(CYG_INSTRUMENT_CLASS_THREAD, 0);
 360  cyg_instrument_disable(CYG_INSTRUMENT_CLASS_ALARM, 0);
 361
 362  for (i = 0; i &lt; instrument_buffer_size; ++i) {
 363  printf("Record %02d: type 0x%04x, thread %d, ",
 364         i, instrument_buffer[i].type, instrument_buffer[i].thread);
 365  printf("time %5d, arg1 0x%08x, arg2 0x%08x\n",
 366         instrument_buffer[i].timestamp, instrument_buffer[i].arg1,
 367         instrument_buffer[i].arg2);
 368  }
 369  return 0;
 370 }</PRE
 371 ></TD
 372 ></TR
 373 ></TABLE
 374 ></DIV
 375 ><P
 376 >Here is how you could compile and run this program in the <TT
 377 CLASS="FILENAME"
 378 >examples</TT
 379 > directory,
 380 using (for example) the MN10300 simulator target: </P
 381 ><TABLE
 382 BORDER="5"
 383 BGCOLOR="#E0E0F0"
 384 WIDTH="70%"
 385 ><TR
 386 ><TD
 387 ><PRE
 388 CLASS="SCREEN"
 389 >$ make XCC=mn10300-elf-gcc INSTALL_DIR=/tmp/ecos-work-mn10300/install instrument-test
 390 mn10300-elf-gcc -c -o instrument-test.o -g -Wall -I/tmp/ecos-work-mn10300/install/include \
 391         -ffunction-sections -fdata-sections instrument-test.c
 392 mn10300-elf-gcc -nostartfiles -L/tmp/ecos-work-mn10300/install/lib -W1,--gc-sections -o \
 393         instrument-test instrument-test.o -Ttarget.ld -nostdlib
 394 $ mn10300-elf-run --board=stdeval1 instrument-test</PRE
 395 ></TD
 396 ></TR
 397 ></TABLE
 398 ><DIV
 399 CLASS="EXAMPLE"
 400 ><A
 401 NAME="AEN2367"><P
 402 ><B
 403 >Example 27-3. Instrument buffer output</B
 404 ></P
 405 ><P
 406 >Here is the output of the
 407             <B
 408 CLASS="COMMAND"
 409 >instrument-test</B
 410 > program. Notice that in
 411             little over 2 seconds, and with very little activity, and
 412             with few event types enabled, it gathered 17 records. In
 413             larger programs it will be necessary to select very few
 414             event types for debugging. </P
 415 ><TABLE
 416 BORDER="5"
 417 BGCOLOR="#E0E0F0"
 418 WIDTH="70%"
 419 ><TR
 420 ><TD
 421 ><PRE
 422 CLASS="PROGRAMLISTING"
 423 >Program to play with instrumentation buffer
 424 Record 00: type 0x0207, thread 2, time  6057, arg1 0x48001cd8, arg2 0x00000002
 425 Record 01: type 0x0202, thread 2, time  6153, arg1 0x48001cd8, arg2 0x00000000
 426 Record 02: type 0x0904, thread 2, time  6358, arg1 0x48001d24, arg2 0x00000000
 427 Record 03: type 0x0905, thread 2, time  6424, arg1 0x00000002, arg2 0x00000000
 428 Record 04: type 0x0906, thread 2, time  6490, arg1 0x00000000, arg2 0x00000000
 429 Record 05: type 0x0901, thread 2, time  6608, arg1 0x48009d74, arg2 0x48001d24
 430 Record 06: type 0x0201, thread 2, time  6804, arg1 0x48001cd8, arg2 0x480013e0
 431 Record 07: type 0x0803, thread 1, time    94, arg1 0x00000000, arg2 0x00000000
 432 Record 08: type 0x0801, thread 1, time   361, arg1 0x00000000, arg2 0x00000000
 433 Record 09: type 0x0802, thread 1, time   548, arg1 0x00000001, arg2 0x00000000
 434 Record 10: type 0x0803, thread 1, time    94, arg1 0x00000000, arg2 0x00000000
 435 Record 11: type 0x0801, thread 1, time   361, arg1 0x00000001, arg2 0x00000000
 436 Record 12: type 0x0903, thread 1, time   513, arg1 0x48009d74, arg2 0x48001d24
 437 Record 13: type 0x0208, thread 1, time   588, arg1 0x00000000, arg2 0x00000000
 438 Record 14: type 0x0203, thread 1, time   697, arg1 0x48001cd8, arg2 0x480013e0
 439 Record 15: type 0x0802, thread 1, time   946, arg1 0x00000002, arg2 0x00000000
 440 Record 16: type 0x0201, thread 1, time  1083, arg1 0x480013e0, arg2 0x48001cd8
 441 Record 17: type 0x0000, thread 0, time     0, arg1 0x00000000, arg2 0x00000000
 442 Record 18: type 0x0000, thread 0, time     0, arg1 0x00000000, arg2 0x00000000
 443 Record 19: type 0x0000, thread 0, time     0, arg1 0x00000000, arg2 0x00000000</PRE
 444 ></TD
 445 ></TR
 446 ></TABLE
 447 ></DIV
 448 ></DIV
 449 ><DIV
 450 CLASS="NAVFOOTER"
 451 ><HR
 452 ALIGN="LEFT"
 453 WIDTH="100%"><TABLE
 454 SUMMARY="Footer navigation table"
 455 WIDTH="100%"
 456 BORDER="0"
 457 CELLPADDING="0"
 458 CELLSPACING="0"
 459 ><TR
 460 ><TD
 461 WIDTH="33%"
 462 ALIGN="left"
 463 VALIGN="top"
 464 ><A
 465 HREF="debugging-techniques.html"
 466 ACCESSKEY="P"
 467 >Prev</A
 468 ></TD
 469 ><TD
 470 WIDTH="34%"
 471 ALIGN="center"
 472 VALIGN="top"
 473 ><A
 474 HREF="ecos-user-guide.html"
 475 ACCESSKEY="H"
 476 >Home</A
 477 ></TD
 478 ><TD
 479 WIDTH="33%"
 480 ALIGN="right"
 481 VALIGN="top"
 482 ><A
 483 HREF="configuration-and-the-package-repository.html"
 484 ACCESSKEY="N"
 485 >Next</A
 486 ></TD
 487 ></TR
 488 ><TR
 489 ><TD
 490 WIDTH="33%"
 491 ALIGN="left"
 492 VALIGN="top"
 493 >Debugging Techniques</TD
 494 ><TD
 495 WIDTH="34%"
 496 ALIGN="center"
 497 VALIGN="top"
 498 ><A
 499 HREF="debugging-techniques.html"
 500 ACCESSKEY="U"
 501 >Up</A
 502 ></TD
 503 ><TD
 504 WIDTH="33%"
 505 ALIGN="right"
 506 VALIGN="top"
 507 >Configuration and the Package Repository</TD
 508 ></TR
 509 ></TABLE
 510 ></DIV
 511 ></BODY
 512 ></HTML
 513 >