doc/sgml/user-guide/programming-concepts-techniques.sgml

   1 <!-- {{{ Banner                         -->
   2
   3 <!-- =============================================================== -->
   4 <!--                                                                 -->
   5 <!--     programming-concepts-techniques.sgml                        -->
   6 <!--                                                                 -->
   7 <!--     eCos User Guide                                             -->
   8 <!--                                                                 -->
   9 <!-- =============================================================== -->
  10 <!-- ####COPYRIGHTBEGIN####                                          -->
  11 <!--                                                                 -->
  12 <!-- =============================================================== -->
  13 <!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.  -->
  14 <!-- This material may be distributed only subject to the terms      -->
  15 <!-- and conditions set forth in the Open Publication License, v1.0  -->
  16 <!-- or later (the latest version is presently available at          -->
  17 <!-- http://www.opencontent.org/openpub/)                            -->
  18 <!-- Distribution of the work or derivative of the work in any       -->
  19 <!-- standard (paper) book form is prohibited unless prior           -->
  20 <!-- permission obtained from the copyright holder                   -->
  21 <!-- =============================================================== -->
  22 <!--                                                                 -->
  23 <!-- ####COPYRIGHTEND####                                            -->
  24 <!-- =============================================================== -->
  25 <!-- #####DESCRIPTIONBEGIN####                                       -->
  26 <!--                                                                 -->
  27 <!-- ####DESCRIPTIONEND####                                          -->
  28 <!-- =============================================================== -->
  29
  30 <!-- }}} -->
  31
  32 <PART id="ecos-programming-concepts-and-techniques">
  33 <TITLE><productname>eCos</productname> Programming Concepts and Techniques</TITLE>
  34 <PARTINTRO id="programming-partintro">
  35 <PARA>Programming with <productname>eCos</productname> is somewhat different from programming
  36       in more traditional environments. <productname>eCos</productname> is a configurable open
  37       source system, and you are able to configure and build a system
  38       specifically to meet the needs of your application. </PARA>
  39 <PARA>Various different directory hierarchies are involved in
  40       configuring and building the system: the <EMPHASIS>component
  41         repository</EMPHASIS>, the <EMPHASIS>build tree</EMPHASIS>,
  42       and the <EMPHASIS>install tree</EMPHASIS>. These directories
  43       exist in addition to the ones used to develop
  44       applications.</PARA>
  45 </PARTINTRO>
  46 <CHAPTER id="cdl-concepts">
  47 <TITLE>CDL Concepts</TITLE>
  48 <SECT1 id="cdl-concepts-about">
  49 <TITLE>About this chapter</TITLE>
  50 <PARA>This chapter serves as a brief introduction to the
  51         concepts involved in <productname>eCos</productname> (Embedded Configurable Operating
  52         System).  It describes the configuration architecture and the
  53         underlying technology to a level required for the embedded
  54         systems developer to configure <productname>eCos</productname>.  It does not describe in
  55         detail aspects such as how to write reusable components for
  56         <productname>eCos</productname>: this information is given in the <citetitle>Component
  57           Writer&rsquo;s Guide</citetitle>.</PARA>
  58 <SECT2>
  59 <TITLE>Background</TITLE>
  60 <PARA>Software solutions for the embedded space place
  61           particularly stringent demands on the developer, typically
  62           represented as requirements for small memory footprint, high
  63           performance and robustness.  These demands are addressed in
  64           <productname>eCos</productname> by providing the ability to perform compile-time
  65           specialization: the developer can tailor the operating
  66           system to suit the needs of the application.  In order to
  67           make this process manageable, <productname>eCos</productname> is built in the context
  68           of a Configuration Infrastructure: a set of tools including
  69           a <application>Configuration Tool</application> and a formal
  70           description of the process of configuration by means of a
  71           <EMPHASIS>Component Definition Language</EMPHASIS>.</PARA>
  72 </SECT2>
  73 <SECT2>
  74 <TITLE>Configurations</TITLE>
  75 <PARA><productname>eCos</productname> is tailored at source level (that is, before
  76             compilation or assembly) in order to create an <productname>eCos</productname>
  77             <EMPHASIS>configuration</EMPHASIS>. In concrete terms, an
  78             <productname>eCos</productname> configuration takes the form of a configuration save
  79             file (with extension .ecc) and set of files used to build
  80             user applications (including, when built, a library file
  81             against which the application is linked). </PARA>
  82 </SECT2>
  83 </SECT1>
  84 <SECT1 id="cdl-component-repository">
  85 <TITLE>Component Repository</TITLE>
  86 <PARA><productname>eCos</productname> is shipped in source in the form of a
  87           <EMPHASIS>component repository</EMPHASIS> - a directory
  88           hierarchy that contains the sources and other files which
  89           are used to build a configuration. The component repository
  90           can be added to by, for example, downloading from the
  91           net.</PARA>
  92 </SECT1>
  93 <SECT1 id="cdl-component-definition-language">
  94 <TITLE>Component Definition Language</TITLE>
  95 <PARA>Part of the component repository is a set of files
  96           containing a definition of its structure.  The form used for
  97           this purpose is the <EMPHASIS>Component Definition
  98             Language</EMPHASIS> (CDL).  CDL defines the relationships
  99           between components and other information used by tools such
 100           as the <productname>eCos</productname><APPLICATION>Configuration Tool</APPLICATION>.
 101           CDL is generally formulated by the writers of components: it
 102           is not necessary to write or understand CDL in order for the
 103           embedded systems developer to construct an <productname>eCos</productname>
 104           configuration. </PARA>
 105 </SECT1>
 106 <SECT1 id="cdl-packages">
 107 <TITLE>Packages</TITLE>
 108 <PARA>The building blocks of an <productname>eCos</productname> configuration are called
 109           <EMPHASIS>packages</EMPHASIS>. Packages are the units of
 110           software distribution.  A set of core packages (such as
 111           kernel, C library and math library) is provided by Red Hat:
 112           additional third-party packages will be available in
 113           future.</PARA>
 114 <PARA>A package may exist in one of a number of <EMPHASIS>versions</EMPHASIS>.
 115  The default version is the <EMPHASIS>current</EMPHASIS> version.
 116  Only one version of a given package may be present in the component
 117 repository at any given time.</PARA>
 118 <PARA>Packages are organized in a tree hierarchy.  Each package
 119 is either at the top-level or is the child of another package.</PARA>
 120 <PARA>The <productname>eCos</productname> <application> Package Administration Tool</application> can be used to add or remove
 121 packages from the component repository.  The <productname>eCos</productname> <APPLICATION>Configuration Tool</APPLICATION> can be used to include or exclude packages from the configuration
 122 being built.</PARA>
 123 </SECT1>
 124 <SECT1 id="cdl-configuration-items">
 125 <TITLE>Configuration Items</TITLE>
 126 <PARA><EMPHASIS>Configuration items</EMPHASIS> are the
 127           individual entities that form a configuration.  Each item
 128           corresponds to the setting of a C pre-processor macro (for
 129           example,
 130           <literal>CYGHWR_HAL_ARM_PID_GDB_BAUD</literal>).
 131           The code of <productname>eCos</productname> itself is written to test such pre-processor
 132           macros so as to tailor the code.  User code can do
 133           likewise.</PARA>
 134 <PARA>Configuration items come in the following flavors:</PARA>
 135 <ITEMIZEDLIST>
 136 <LISTITEM>
 137 <PARA><EMPHASIS>None</EMPHASIS>: such entities serve only as
 138 place holders in the hierarchy, allowing other entities to be grouped
 139 more easily.</PARA>
 140 </LISTITEM>
 141 <LISTITEM>
 142 <PARA><EMPHASIS>Boolean</EMPHASIS> entities are the most common
 143 flavor; they correspond to units of functionality that can be either
 144 enabled or disabled.  If the entity is enabled then there will be
 145 a #define; code will check the setting using, for example, #ifdef</PARA>
 146 </LISTITEM>
 147 <LISTITEM>
 148 <PARA><EMPHASIS>Data</EMPHASIS> entities encapsulate some arbitrary
 149 data. Other properties such as a set or range of legal values can
 150 be used to constrain the actual values, for example to an integer
 151 or floating point value within a certain range.</PARA>
 152 </LISTITEM>
 153 <LISTITEM>
 154 <PARA><EMPHASIS>Booldata</EMPHASIS> entities combine the attributes
 155 of <EMPHASIS>Boolean</EMPHASIS> and <EMPHASIS>Data</EMPHASIS>: they
 156 can be enabled or disabled and, if enabled, will hold a data value.</PARA>
 157 </LISTITEM>
 158 </ITEMIZEDLIST>
 159 <PARA>Like packages, configuration items exist in a tree-based hierarchy:
 160 each configuration item has a parent which may be another configuration
 161 item or a package.  Under some conditions (such as when packages
 162 are added or removed from a configuration), items may be &ldquo;re-parented&rdquo; such
 163 that their position in the tree changes. </PARA>
 164 <SECT2>
 165 <TITLE>Expressions</TITLE>
 166 <PARA>Expressions are relationships between CDL items.  There are
 167 three types of expression in CDL:</PARA>
 168         <table id="cdl-expressions">
 169           <title>CDL Expressions</title>
 170         <tgroup cols="3">
 171           <thead>
 172           <row>
 173               <entry>Expression Type</entry>
 174               <entry>Result</entry>
 175               <entry>Common Use (see <xref linkend="table-configuration-properties">)</entry></row>
 176           </thead>
 177           <tbody>
 178             <row>
 179               <entry>Ordinary</entry>
 180               <entry>A single value</entry>
 181               <entry>legal_values property</entry>
 182             </row>
 183             <row>
 184               <entry>List</entry><entry>A range of
 185                 values (for example &ldquo;1 to 10&rdquo;)</entry>
 186               <entry>legal_values property </entry></row>
 187             <row>
 188               <entry>Goal</entry><entry>True or False</entry>
 189               <entry>requires and active_if properties</entry></row>
 190             </tbody>
 191           </tgroup>
 192         </table>
 193       </SECT2>
 194       <SECT2>
 195         <TITLE>Properties</TITLE>
 196 <PARA>Each configuration item has a set of properties.  The following
 197 table describes the most commonly used:</PARA>
 198         <table id="table-configuration-properties">
 199           <title>Configuration properties</title>
 200           <tgroup cols="2">
 201             <thead><row>
 202                 <entry><emphasis>Property</emphasis></entry>
 203 <entry><emphasis>Use </emphasis></entry></row>
 204             </thead>
 205             <tbody>
 206               <row>
 207                 <entry>Flavor</entry>
 208                 <entry>The &ldquo;type&rdquo; of the item, as
 209                   described above </entry></row>
 210               <row>
 211                 <entry>Enabled</entry><entry>Whether
 212                   the item is enabled </entry></row>
 213               <row>
 214                 <entry>Current_value</entry>
 215 <entry>The current value of the item </entry></row>
 216               <row>
 217                 <entry>Default_value</entry>
 218 <entry>An ordinary expression defining the default value of the
 219                     item</entry></row>
 220               <row>
 221                 <entry>Legal_values</entry><entry>A
 222                   list expression defining the values the item may hold (for example,
 223                   1 to10) </entry></row>
 224               <row>
 225                 <entry>Active_if</entry><entry>A
 226                   goal expression denoting the requirement for this item to be active
 227 (see below: <emphasis>Inactive Items</emphasis>) </entry></row>
 228 <row>
 229 <entry>Requires</entry><entry>A goal
 230 expression denoting requirements this item places on others (see
 231 below: <emphasis>Conflicts</emphasis>) </entry></row>
 232 <row>
 233 <entry>Calculated</entry><entry>Whether
 234 the item as non-modifiable </entry></row>
 235 <row>
 236 <entry>Macro</entry><entry>The corresponding
 237 C pre-processor macro </entry></row>
 238 <row>
 239 <entry>File</entry><entry>The C header
 240 file in which the macro is defined </entry></row>
 241 <row>
 242 <entry>URL</entry><entry>The URL of
 243 a documentation page describing the item </entry></row>
 244 <row>
 245 <entry>Hardware</entry><entry>Indicates
 246 that a particular package is related to specific hardware</entry></row>
 247             </tbody>
 248           </tgroup>
 249         </table>
 250
 251 <PARA>A complete description of properties is contained in the <citetitle>Component
 252 Writer&rsquo;s Guide</citetitle>.</PARA>
 253 </SECT2>
 254 <SECT2>
 255 <TITLE>Inactive Items</TITLE>
 256 <PARA>Descendants of an item that is disabled are inactive: their
 257 values may not be changed.  Items may also become <EMPHASIS>inactive</EMPHASIS> if
 258 an active_if expression is used to make the item dependent
 259 on an expression involving other items. </PARA>
 260 </SECT2>
 261 </SECT1>
 262 <SECT1 id="cdl-conflicts">
 263 <TITLE>Conflicts</TITLE>
 264 <PARA>Not all settings of configuration items will lead to a
 265           coherent configuration; for example, the use of a timeout
 266           facility might require the existence of timer support, so if
 267           the one is required the other cannot be removed.  Coherence
 268           is policed by means of consistency rules (in particular, the
 269           goal expressions that appear as CDL items
 270           <EMPHASIS>requires</EMPHASIS> and
 271           <EMPHASIS>active_if</EMPHASIS> attributes [see
 272           above]).  A violation of consistency rules creates a
 273           <EMPHASIS>conflict</EMPHASIS>, which must be resolved in
 274           order to ensure a consistent configuration. Conflict
 275           resolution can be performed manually or with the assistance
 276           of the <productname>eCos</productname> tools.  Conflicts come in the following
 277           flavors:</PARA>
 278 <ITEMIZEDLIST>
 279 <LISTITEM>
 280 <PARA>An <EMPHASIS>unresolved</EMPHASIS> conflict means that
 281 there is a reference to an entity that is not yet in the current
 282 configuration </PARA>
 283 </LISTITEM>
 284 <LISTITEM>
 285 <PARA>An <EMPHASIS>illegal value</EMPHASIS> conflict is caused
 286 when a configuration item is set to a value that is not permitted
 287 (that is, a <EMPHASIS>legal_values</EMPHASIS> goal expression
 288 is failing) </PARA>
 289 </LISTITEM>
 290 <LISTITEM>
 291 <PARA>An <EMPHASIS>evaluation exception</EMPHASIS> conflict
 292 is caused when the evaluation of an expression would fail (for example,
 293 because of a division by zero) </PARA>
 294 </LISTITEM>
 295 <LISTITEM>
 296 <PARA>An <EMPHASIS>unsatisfied goal</EMPHASIS> conflict is caused
 297 by a failing <EMPHASIS>requires</EMPHASIS> goal expression </PARA>
 298 </LISTITEM>
 299 <LISTITEM>
 300 <PARA>A <EMPHASIS>bad data</EMPHASIS> conflict arises only rarely,
 301 and corresponds to badly constructed CDL.  Such a conflict can only
 302 be resolved by reference to the CDL writer.</PARA>
 303 </LISTITEM>
 304 </ITEMIZEDLIST>
 305 </SECT1>
 306 <SECT1 id="cdl-templates">
 307 <TITLE>Templates</TITLE>
 308 <PARA>A <EMPHASIS>template</EMPHASIS> is a saved configuration
 309           - that is, a set of packages and configuration item
 310           settings.  Templates are provided with <productname>eCos</productname> to allow you to
 311           get started quickly by instantiating (copying) a saved
 312           configuration corresponding to one of a number of common
 313           scenarios; for example, a basic <productname>eCos</productname> configuration template
 314           is supplied that contains the infrastructure, kernel, C and
 315           math libraries, plus their support packages.</PARA>
 316 </SECT1>
 317 </CHAPTER>
 318 <CHAPTER id="component-repo-and-working-dirs">
 319 <TITLE>The Component Repository and Working Directories</TITLE>
 320 <PARA>Each of the file trees involved in <productname>eCos</productname> development has a
 321         different role. </PARA>
 322 <SECT1 id="component-repo">
 323 <TITLE>Component Repository</TITLE>
 324 <PARA>The <productname>eCos</productname> <FIRSTTERM>component repository</FIRSTTERM>
 325           contains directories for all the packages that are shipped
 326           with <productname>eCos</productname> or provided by third parties.</PARA>
 327 <PARA>The component repository should not be modified as part of
 328 application development. </PARA>
 329 <!--
 330 <para>
 331 XXXXX We may want to change this picture XXXXX
 332 </para>
 333 -->
 334 <FIGURE>
 335 <TITLE>Component repository</TITLE>
 336 <GRAPHIC ENTITYREF="graphic30"></GRAPHIC>
 337 </FIGURE>
 338 <SECT2>
 339 <TITLE>Purpose</TITLE>
 340 <PARA>The component repository is the master copy of source code
 341 for all system and third party components. It also contains some
 342 files needed to administer and build the system, such as <command>ecosadmin.tcl</command>.</PARA>
 343 </SECT2>
 344 <SECT2>
 345 <TITLE>How is it modified?</TITLE>
 346 <PARA>You modify it by importing new versions of packages from a
 347 distribution or removing existing packages. These activities are
 348 undertaken using the <productname>eCos</productname> <application>Package Administration Tool</application>.</PARA>
 349 </SECT2>
 350 <SECT2>
 351 <TITLE>When is it edited manually?</TITLE>
 352 <PARA>Files in the component repository should only be edited manually
 353 as determined by the component maintainer.</PARA>
 354 </SECT2>
 355 <SECT2>
 356 <TITLE>User Applications</TITLE>
 357 <PARA>User application source code should <EMPHASIS>not</EMPHASIS> go
 358 into the component repository.</PARA>
 359 </SECT2>
 360 <SECT2>
 361 <TITLE>Examples of files in this hierarchy:</TITLE>
 362 <VARIABLELIST>
 363 <VARLISTENTRY>
 364 <TERM><FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/doc/ref/ecos-ref.html</FILENAME></TERM>
 365 <LISTITEM>
 366 <PARA>The top level HTML file for the
 367                   <citetitle><PRODUCTNAME>eCos</PRODUCTNAME> Reference
 368                     Manual</citetitle>. </PARA>
 369 </LISTITEM>
 370 </VARLISTENTRY>
 371 <VARLISTENTRY>
 372 <TERM><FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/prebuilt/pid/tests/kernel/<replaceable>&Version;</replaceable>/tests/thread_gdb.exe</FILENAME></TERM>
 373 <LISTITEM>
 374 <PARA></PARA>
 375 </LISTITEM>
 376 </VARLISTENTRY>
 377 <VARLISTENTRY>
 378 <TERM><FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/prebuilt/linux/tests/kernel/<replaceable>&Version;</replaceable>/tests/thread_gdb.exe</FILENAME></TERM>
 379 <LISTITEM>
 380 <PARA>Pre-built tests for the supported platforms, and
 381                   the synthetic Linux target.</PARA>
 382 </LISTITEM>
 383 </VARLISTENTRY>
 384 <VARLISTENTRY>
 385 <TERM><FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/examples/twothreads.c</FILENAME></TERM>
 386 <LISTITEM>
 387 <PARA>One of the example programs.</PARA>
 388 </LISTITEM>
 389 </VARLISTENTRY>
 390 <VARLISTENTRY>
 391 <TERM><FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/ecosadmin.tcl</FILENAME></TERM>
 392 <LISTITEM>
 393 <para>The Tcl program which is used to  import new versions of packages
 394 from a distribution or remove existing packages.</para>
 395 </LISTITEM>
 396 </VARLISTENTRY>
 397 <VARLISTENTRY>
 398 <TERM><FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/packages/language/c/libm/<replaceable>&Version;</replaceable>/src/double/portable-api/s_tanh.c</FILENAME></TERM>
 399 <LISTITEM>
 400 <para>Implementation of the hyperbolic tangent function in the standard
 401 math library.</para>
 402 </LISTITEM>
 403 </VARLISTENTRY>
 404 <VARLISTENTRY>
 405 <TERM><FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/pkgconf/rules.mak</FILENAME></TERM>
 406 <LISTITEM>
 407 <para>A file with <command>make</command> rules, used
 408 by the <FILENAME>makefile</FILENAME>.</para>
 409 </LISTITEM>
 410 </VARLISTENTRY>
 411 </VARIABLELIST>
 412 </SECT2>
 413 </SECT1>
 414 <SECT1 id="build-tree">
 415 <TITLE>Build Tree</TITLE>
 416 <PARA>The <FIRSTTERM>build tree</FIRSTTERM> is the directory
 417           hierarchy in which all <EMPHASIS>generated</EMPHASIS> files
 418           are placed. Generated files consist of the
 419           <FILENAME>makefile</FILENAME>, the compiled object files,
 420           and a dependency file (with a <FILENAME>.d</FILENAME>
 421           extension) for each source file.</PARA>
 422 <SECT2><!--<conditionaltext>-->
 423 <TITLE>Purpose</TITLE>
 424 <PARA>The build tree is where all intermediate object files are
 425             placed. </PARA>
 426 </SECT2>
 427 <SECT2>
 428 <TITLE>How is it modified?</TITLE>
 429 <PARA>Recompiling can modify the object files.</PARA>
 430 </SECT2>
 431 <SECT2>
 432 <TITLE>User applications</TITLE>
 433 <PARA>User application source or binary code should
 434             <EMPHASIS>not</EMPHASIS> go in the build tree. </PARA>
 435 </SECT2>
 436 <SECT2>
 437 <TITLE>Examples of files in this hierarchy</TITLE>
 438 <VARIABLELIST>
 439 <VARLISTENTRY>
 440 <TERM><FILENAME>ecos-work/language/c/libc/<replaceable>&Version;</replaceable>/src</FILENAME></TERM>
 441 <LISTITEM>
 442 <PARA>The directory in which object files for
 443                   the C library are built.</PARA>
 444 </LISTITEM>
 445 </VARLISTENTRY>
 446 </VARIABLELIST>
 447 </SECT2>
 448 </SECT1>
 449 <SECT1 id="install-tree">
 450 <TITLE>Install Tree</TITLE>
 451 <PARA>The <FIRSTTERM>install tree</FIRSTTERM> is the location
 452           for all files needed for application development. The
 453           <filename>libtarget.a</filename> library, which contains the
 454             custom-built <productname>eCos</productname> kernel and other components, is placed
 455             in the install tree, along with all packages&rsquo; public
 456             header files. If you build the tests, the test executable
 457             programs will also be placed in the install
 458             tree. </PARA>
 459 <PARA>By default, the install tree is created by
 460           <COMMAND>ecosconfig</COMMAND> in a subdirectory of the build
 461           tree called <FILENAME>install</FILENAME>. This can be
 462           modified with the <OPTION>--prefix</OPTION> option (see
 463           <xref linkend="manual-configuration">).
 464         </PARA>
 465 <SECT2><!--<conditionaltext>-->
 466 <TITLE>Purpose</TITLE>
 467 <PARA>The install tree is where the custom-built
 468             <FILENAME>libtarget.a</FILENAME> library, which contains
 469             the <productname>eCos</productname> kernel and other components, is located. The
 470             install tree is also the location for all the header files
 471             that are part of a published interface for their
 472             component. </PARA>
 473 </SECT2>
 474 <SECT2>
 475 <TITLE>How is it modified?</TITLE>
 476 <PARA>Recompiling can replace
 477             <FILENAME>libtarget.a</FILENAME> and the test
 478             executables. </PARA>
 479 </SECT2>
 480 <SECT2>
 481 <TITLE>When is it edited manually?</TITLE>
 482 <PARA>Where a memory layout requires modification without
 483             use of the <productname>eCos</productname> <application>Configuration Tool</application>, the memory layout
 484             files must be edited directly in the install tree. These
 485             files are located at
 486             <FILENAME>install/include/pkgconf/mlt_*.*</FILENAME>.
 487             Note that subsequent modification of the install tree
 488             using the Configuration Tool will result in such manual
 489             edits being lost.</PARA>
 490 </SECT2>
 491 <SECT2>
 492 <TITLE>User applications</TITLE>
 493 <PARA>User application source or binary code should
 494             <EMPHASIS>not</EMPHASIS> go in the install tree. </PARA>
 495 </SECT2>
 496 <SECT2>
 497 <TITLE>Examples of files in this hierarchy</TITLE>
 498 <VARIABLELIST>
 499 <VARLISTENTRY>
 500 <TERM><FILENAME>install/lib/libtarget.a</FILENAME></TERM>
 501 <LISTITEM>
 502 <PARA>The library containing the kernel and other components.</PARA>
 503 </LISTITEM>
 504 </VARLISTENTRY>
 505 <VARLISTENTRY>
 506 <TERM><FILENAME>install/include/cyg/kernel/kapi.h</FILENAME></TERM>
 507 <LISTITEM>
 508 <PARA>The header file for the kernel C language API.</PARA>
 509 </LISTITEM>
 510 </VARLISTENTRY>
 511 <VARLISTENTRY>
 512 <TERM><FILENAME>install/include/pkgconf/mlt_arm_pid_ram.ldi</FILENAME></TERM>
 513 <LISTITEM>
 514 <PARA>The linker script fragment describing the memory
 515                   layout for linking applications intended for
 516                   execution on an ARM PID development board using RAM
 517                   startup.</PARA>
 518 </LISTITEM>
 519 </VARLISTENTRY>
 520 <VARLISTENTRY>
 521 <TERM><FILENAME>install/include/stdio.h</FILENAME></TERM>
 522 <LISTITEM>
 523 <PARA>The C library header file for standard I/O. </PARA>
 524 </LISTITEM>
 525 </VARLISTENTRY>
 526 </VARIABLELIST>
 527 </SECT2>
 528 </SECT1>
 529 <SECT1 id="repository-app-build-tree">
 530 <TITLE>Application Build Tree</TITLE>
 531 <PARA>This tree is not part of <productname>eCos</productname> itself: it is the
 532           directory in which <productname>eCos</productname> end users write their own
 533           applications.</PARA>
 534 <PARA>Example applications and their
 535           <FILENAME>Makefile</FILENAME> are located in the component
 536           repository, in the directory
 537           <FILENAME>BASE_DIR</FILENAME><FILENAME>/examples</FILENAME>.
 538
 539         </PARA>
 540 <PARA>There is no imposed format on this directory, but there
 541           are certain compiler and linker flags that must be used to
 542           compile an <productname>eCos</productname> application. The basic set of flags is shown
 543           in the example <FILENAME>Makefile</FILENAME>, and additional
 544           details can be found in <xref linkend="compiler-and-linker-options">. </PARA>
 545 </SECT1>
 546 </CHAPTER>
 547 <CHAPTER id="compiler-and-linker-options">
 548 <TITLE>Compiler and Linker Options</TITLE>
 549
 550     <PARA><productname>eCos</productname> is built using
 551       the GNU C and C++ compilers. <productname>eCos</productname> relies on certain features of these
 552       tools such as constructor priority ordering and selective linking
 553       which are not part of other toolchains.
 554     </PARA>
 555
 556 <PARA>Some <application>GCC</application> options are required for <productname>eCos</productname>,
 557 and others can be useful. This chapter gives a brief description
 558 of the required options as well as some recommended <productname>eCos</productname>-specific options.
 559 All other <application>GCC</application> options (described in the <application>GCC</application> manuals)
 560 are available. </PARA>
 561 <SECT1 id="compiling-c-app">
 562 <TITLE>Compiling a C Application</TITLE>
 563 <PARA>The following command lines demonstrate the
 564           <EMPHASIS>minimum</EMPHASIS> set of options required to
 565           compile and link an <productname>eCos</productname> program written in C. </PARA>
 566 <NOTE>
 567 <PARA>Remember that when this manual shows
 568             <COMMAND><replaceable>TARGET-</replaceable>gcc</COMMAND>
 569             you should use the full name of the cross compiler,
 570             e.g. <COMMAND>i386-elf-gcc</COMMAND>,
 571             <COMMAND>arm-elf-gcc</COMMAND>, or
 572             <COMMAND>sh-elf-gcc</COMMAND>. When compiling for the
 573             synthetic Linux target, use the native
 574             <command>gcc</command> which must have the features
 575             required by <productname>eCos</productname>.</PARA>
 576 </NOTE>
 577 <SCREEN>
 578 $ <replaceable>TARGET-</replaceable>gcc -c  -I<EMPHASIS>INSTALL_DIR</EMPHASIS>/include file.c
 579 $ <replaceable>TARGET-</replaceable>gcc -o program file.o -L<EMPHASIS>INSTALL_DIR</EMPHASIS>/lib -Ttarget.ld -nostdlib
 580 </SCREEN>
 581 <NOTE>
 582 <PARA>Certain targets may require extra options, for example
 583             the SPARClite architectures require the option
 584             <OPTION>-mcpu=sparclite</OPTION>. Examine the
 585             <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/examples/Makefile</FILENAME>
 586             or the &ldquo;Global compiler flags&rdquo; option
 587             (CYGBLD_GLOBAL_CFLAGS) in your generated
 588             <productname>eCos</productname> configuration) to see if any extra options are
 589             required, and if so, what they are. </PARA>
 590 <PARA>The following command lines use some other options
 591             which are recommended because they use the
 592         <!-- <index></index> -->selective linking feature:</PARA>
 593 <SCREEN>$ <replaceable>TARGET-</replaceable>gcc -c  -I<REPLACEABLE>INSTALL_DIR</REPLACEABLE>/include -I. -ffunction-sections -fdata-sections -g -O2 file.c
 594 $ <replaceable>TARGET-</replaceable>gcc -o program file.o -ffunction-sections -fdata-sections -Wl,--gc-sections -g -O2 \
 595           -L<REPLACEABLE>INSTALL_DIR</REPLACEABLE>/lib -Ttarget.ld -nostdlib
 596 </SCREEN>
 597
 598 </NOTE>
 599 </SECT1>
 600 <SECT1 id="compiling-cpp-app">
 601 <TITLE>Compiling a C++ Application</TITLE>
 602 <PARA>The following command lines demonstrate the
 603           <EMPHASIS>minimum</EMPHASIS> set of options required to
 604           compile and link an <productname>eCos</productname> program written in C++.
 605         </PARA>
 606 <NOTE>
 607 <PARA>Remember that when this manual shows
 608             <COMMAND><replaceable>TARGET-</replaceable>g++</COMMAND>
 609             you should use the full name of the cross compiler,
 610             e.g. <COMMAND>i386-elf-g++</COMMAND>,
 611             <COMMAND>arm-elf-g++</COMMAND>, or
 612             <COMMAND>sh-elf-g++</COMMAND>. When compiling for the
 613             synthetic Linux target, use the native
 614             <command>g++</command> which must have the features
 615             required by <productname>eCos</productname>.</PARA>
 616 </NOTE>
 617 <SCREEN>$ <replaceable>TARGET-</replaceable>g++ -c  -I<REPLACEABLE>INSTALL_DIR</REPLACEABLE>/include -fno-rtti -fno-exceptions file.cxx
 618 $ <replaceable>TARGET-</replaceable>g++ -o program file.o -L<REPLACEABLE>INSTALL_DIR</REPLACEABLE>/lib -Ttarget.ld -nostdlib
 619 </SCREEN>
 620
 621 <NOTE>
 622 <PARA>Certain targets may require extra options,
 623             for example the SPARClite architectures require the option
 624             <OPTION>-mcpu=sparclite</OPTION>. Examine the
 625             <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/packages/targets</FILENAME>
 626             file or <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/examples/Makefile</FILENAME>
 627             or the &ldquo;Global compiler flags&rdquo; option
 628             (CYGBLD_GLOBAL_CFLAGS) in your generated
 629             <productname>eCos</productname> configuration) to see if any extra options are
 630             required, and if so, what they are.</PARA>
 631 <PARA>The following command lines use some other options
 632             which are recommended because they use the
 633             <FIRSTTERM>selective linking</FIRSTTERM> feature:</PARA>
 634 <SCREEN>
 635 $ <replaceable>TARGET-</replaceable>g++ -c -I<REPLACEABLE>INSTALL_DIR</REPLACEABLE>/include -I. -ffunction-sections -fdata-sections -fno-rtti \
 636           -fno-exceptions -finit-priority -g -O2 file.cxx
 637 $ <replaceable>TARGET-</replaceable>g++ -o program file.o -W1,--gc-sections -g -O2 -L<REPLACEABLE>INSTALL_DIR</REPLACEABLE>/lib -Ttarget.ld  -nostdlib</SCREEN>
 638 </NOTE>
 639 </SECT1>
 640 </CHAPTER>
 641
 642 <CHAPTER id="debugging-techniques">
 643 <TITLE>Debugging Techniques</TITLE>
 644 <PARA><productname>eCos</productname> applications and components can be debugged in
 645         traditional ways, with printing statements and debugger
 646         single-stepping, but there are situations in which these
 647         techniques cannot be used. One example of this is when a
 648         program is getting data at a high rate from a real-time
 649         source, and cannot be slowed down or interrupted.</PARA>
 650 <PARA><productname>eCos</productname>&rsquo;s infrastructure module provides a
 651         <EMPHASIS>tracing</EMPHASIS> formalism, allowing the
 652         kernel&rsquo;s tracing macros to be configured in many useful
 653         ways. <productname>eCos</productname>&rsquo;s kernel provides <FIRSTTERM>instrumentation
 654           buffers</FIRSTTERM> which also collect specific
 655         (configurable) data about the system&rsquo;s history and
 656         performance.</PARA>
 657 <SECT1 id="tracing">
 658 <TITLE>Tracing</TITLE>
 659 <PARA>To use <productname>eCos</productname>&rsquo;s tracing facilities you must first
 660           configure your system to use <FIRSTTERM>tracing</FIRSTTERM>.
 661           You should enable the Asserts and Tracing component
 662           (<OPTION>CYGPKG_INFRA_DEBUG</OPTION>) and the
 663           <OPTION>Use tracing</OPTION> component within it
 664           (<OPTION>CYGDBG_USE_TRACING</OPTION>). These
 665           options can be enabled with the <APPLICATION>Configuration
 666             Tool</APPLICATION> or by editing the file
 667           <FILENAME><REPLACEABLE>BUILD_DIR</REPLACEABLE>/pkgconf/infra.h
 668           </FILENAME> manually.</PARA>
 669 <PARA>You should then examine all the tracing-related options in
 670 the <citetitle>Package: Infrastructure</citetitle> chapter of the <citetitle><PRODUCTNAME>eCos</PRODUCTNAME> Reference
 671 Manual</citetitle>. One useful set of configuration options are: <literal>CYGDBG_INFRA_DEBUG_FUNCTION_REPORTS</literal> and <literal>CYGDBG_INFRA_DEBUG_TRACE_MESSAGE</literal>,
 672 which are both enabled by default when tracing is enabled.</PARA>
 673 <PARA>The following &ldquo;Hello world with tracing&rdquo; shows
 674 the output from running the hello world program (from <xref linkend="ecos-hello-world">) that was
 675 built with tracing enabled: </PARA>
 676 <EXAMPLE>
 677 <TITLE>Hello world with tracing</TITLE>
 678 <SCREEN>$ mips-tx39-elf-run --board=jmr3904  hello
 679 Hello, eCos world!
 680 ASSERT FAIL: &lt;2&gt;cyg_trac.h          [ 623] Cyg_TraceFunction_Report_::set_exitvoid()                                                            exitvoid used in typed function
 681 TRACE: &lt;1&gt;mlqueue.cxx         [ 395] Cyg_ThreadQueue_Implementation::enqueue()                                                            {{enter
 682 TRACE: &lt;1&gt;mlqueue.cxx         [ 395] Cyg_ThreadQueue_Implementation::enqueue()                                                            }}RETURNING UNSET!
 683 TRACE: &lt;1&gt;mlqueue.cxx         [ 126] Cyg_Scheduler_Implementation::add_thread()                                                           }}RETURNING UNSET!
 684 TRACE: &lt;1&gt;thread.cxx          [ 654] Cyg_Thread::resume()                                                                                 }}return void
 685 TRACE: &lt;1&gt;cstartup.cxx        [ 160] cyg_iso_c_start()                                                                                    }}return void
 686 TRACE: &lt;1&gt;startup.cxx         [ 142] cyg_package_start()                                                                                  }}return void
 687 TRACE: &lt;1&gt;startup.cxx         [ 150] cyg_user_start()                                                                                     {{enter
 688 TRACE: &lt;1&gt;startup.cxx         [ 150] cyg_user_start()                                                                                     (((void)))
 689 TRACE: &lt;1&gt;startup.cxx         [ 153] cyg_user_start()                                                                                     'This is the system default cyg_user_start()'
 690 TRACE: &lt;1&gt;startup.cxx         [ 157] cyg_user_start()                                                                                     }}return void
 691 TRACE: &lt;1&gt;sched.cxx           [ 212] Cyg_Scheduler::start()                                                                               {{enter
 692 TRACE: &lt;1&gt;mlqueue.cxx         [ 102] Cyg_Scheduler_Implementation::schedule()                                                             {{enter
 693 TRACE: &lt;1&gt;mlqueue.cxx         [ 437] Cyg_ThreadQueue_Implementation::highpri()                                                            {{enter
 694 TRACE: &lt;1&gt;mlqueue.cxx         [ 437] Cyg_ThreadQueue_Implementation::highpri()                                                            }}RETURNING UNSET!
 695 TRACE: &lt;1&gt;mlqueue.cxx         [ 102] Cyg_Scheduler_Implementation::schedule()                                                             }}RETURNING UNSET!
 696 TRACE: &lt;2&gt;intr.cxx            [ 450] Cyg_Interrupt::enable_interrupts()                                                                   {{enter
 697 TRACE: &lt;2&gt;intr.cxx            [ 450] Cyg_Interrupt::enable_interrupts()                                                                   }}RETURNING UNSET!
 698 TRACE: &lt;2&gt;thread.cxx          [  69] Cyg_HardwareThread::thread_entry()                                                                   {{enter
 699 TRACE: &lt;2&gt;cstartup.cxx        [ 127] invoke_main()                                                                                        {{enter
 700 TRACE: &lt;2&gt;cstartup.cxx        [ 127] invoke_main()                                                                                        ((argument is ignored))
 701 TRACE: &lt;2&gt;dummyxxmain.cxx     [  60] __main()                                                                                             {{enter
 702 TRACE: &lt;2&gt;dummyxxmain.cxx     [  60] __main()                                                                                             (((void)))
 703 TRACE: &lt;2&gt;dummyxxmain.cxx     [  63] __main()                                                                                             'This is the system default __main()'
 704 TRACE: &lt;2&gt;dummyxxmain.cxx     [  67] __main()                                                                                             }}return void
 705 TRACE: &lt;2&gt;memcpy.c            [ 112] _memcpy()                                                                                            {{enter
 706 TRACE: &lt;2&gt;memcpy.c            [ 112] _memcpy()                                                                                            ((dst=80002804, src=BFC14E58, n=19))
 707 TRACE: &lt;2&gt;memcpy.c            [ 164] _memcpy()                                                                                            }}returning 80002804
 708 TRACE: &lt;2&gt;cstartup.cxx        [ 137] invoke_main()                                                                                        'main() has returned with code 0. Calling exit()'
 709 TRACE: &lt;2&gt;exit.cxx            [  71] __libc_exit()                                                                                        {{enter
 710 TRACE: &lt;2&gt;exit.cxx            [  71] __libc_exit()                                                                                        ((status=0 ))
 711 TRACE: &lt;2&gt;atexit.cxx          [  84] cyg_libc_invoke_atexit_handlers()                                                                    {{enter
 712 TRACE: &lt;2&gt;atexit.cxx          [  84] cyg_libc_invoke_atexit_handlers()                                                                      (((void)))
 713
 714 Scheduler:
 715
 716 Lock:                0
 717 Current Thread:      &lt;null&gt;
 718
 719 Threads:
 720
 721 Idle Thread          pri =  31 state = R      id =   1
 722                      stack base = 800021F0 ptr = 80002510 size = 00000400
 723                      sleep reason NONE     wake reason NONE
 724                      queue = 80000C54      wait info = 00000000
 725
 726 &lt;null&gt;               pri =   0 state = R      id =   2
 727                      stack base = 80002A48 ptr = 8000A968 size = 00008000
 728                      sleep reason NONE     wake reason NONE
 729                      queue = 80000BD8      wait info = 00000000
 730           </SCREEN>
 731 </EXAMPLE>
 732 </SECT1>
 733 <SECT1 id="kernel-instrumentation">
 734 <TITLE>Kernel Instrumentation</TITLE>
 735 <PARA><FIRSTTERM>Instrument buffers</FIRSTTERM> can be used to
 736           find out how many events of a given type happened in the
 737           kernel during execution of a program.</PARA>
 738 <PARA>You can monitor a class of several types of events, or
 739           you can just look at individual events. </PARA>
 740 <PARA>Examples of <FIRSTTERM>events</FIRSTTERM> that can be
 741           monitored are:
 742         </PARA>
 743 <ITEMIZEDLIST>
 744 <LISTITEM>
 745 <PARA>scheduler events </PARA>
 746 </LISTITEM>
 747 <LISTITEM>
 748 <PARA>thread operations</PARA>
 749 </LISTITEM>
 750 <LISTITEM>
 751 <PARA>interrupts </PARA>
 752 </LISTITEM>
 753 <LISTITEM>
 754 <PARA>mutex operations </PARA>
 755 </LISTITEM>
 756 <LISTITEM>
 757 <PARA>binary semaphore operations </PARA>
 758 </LISTITEM>
 759 <LISTITEM>
 760 <PARA>counting semaphore operations </PARA>
 761 </LISTITEM>
 762 <LISTITEM>
 763 <PARA>clock ticks and interrupts </PARA>
 764 </LISTITEM>
 765 </ITEMIZEDLIST>
 766 <PARA>Examples of fine-grained scheduler event types are: </PARA>
 767 <ITEMIZEDLIST>
 768 <LISTITEM>
 769 <PARA>scheduler lock</PARA>
 770 </LISTITEM>
 771 <LISTITEM>
 772 <PARA>scheduler unlock</PARA>
 773 </LISTITEM>
 774 <LISTITEM>
 775 <PARA>rescheduling</PARA>
 776 </LISTITEM>
 777 <LISTITEM>
 778 <PARA>time slicing </PARA>
 779 </LISTITEM>
 780 </ITEMIZEDLIST>
 781 <PARA>Information about the events is stored in an
 782           <FIRSTTERM>event record</FIRSTTERM>. The structure that
 783           defines this record has type <type>struct
 784           Instrument_Record</type>:
 785 </PARA>
 786 <PARA>The list of records is stored in an array called <TYPE>instrument_buffer</TYPE>
 787 which you can let the kernel provide or you can provide yourself
 788 by setting the configuration option <literal>CYGVAR_KERNEL_INSTRUMENT_EXTERNAL_BUFFER</literal>. </PARA>
 789 <PARA>To write a program that examines the instrumentation
 790           buffers: </PARA>
 791 <ORDEREDLIST>
 792 <LISTITEM>
 793 <PARA>Enable instrumentation buffers in the <productname>eCos</productname> kernel configuration.
 794 The component macro is <literal>CYGPKG_KERNEL_INSTRUMENT</literal>.</PARA>
 795 </LISTITEM>
 796 <LISTITEM>
 797 <PARA>To allocate the buffers yourself, enable the configuration
 798 option <literal>CYGVAR_KERNEL_INSTRUMENT_EXTERNAL_BUFFER</literal>. </PARA>
 799 </LISTITEM>
 800 <LISTITEM>
 801 <PARA>Include the header file
 802 <FILENAME>cyg/kernel/instrmnt.h</FILENAME>
 803 .
 804 <PROGRAMLISTING>#include &lt;cyg/kernel/instrmnt.h&gt;</PROGRAMLISTING></PARA>
 805 </LISTITEM>
 806 <LISTITEM>
 807 <PARA>The <STRUCTNAME>Instrumentation_Record</STRUCTNAME> structure
 808 is not published in the kernel header file. In the future there
 809 will be a cleaner mechanism to access it, but for now you should
 810 paste into your code in the following lines:
 811             </para>
 812 <PROGRAMLISTING>struct Instrument_Record
 813 {
 814  CYG_WORD16 type; // record type
 815  CYG_WORD16 thread; // current thread id
 816  CYG_WORD timestamp; // 32 bit timestamp
 817  CYG_WORD arg1; // first arg
 818  CYG_WORD arg2; // second arg
 819 };</PROGRAMLISTING>
 820 </LISTITEM>
 821 <LISTITEM>
 822 <PARA>Enable the events you want to record using
 823 <FUNCTION>cyg_instrument_enable()</FUNCTION>
 824 , and disable them later. Look at
 825 <filename>cyg/kernel/instrmnt.h</filename>
 826  and the examples below to see what events can be enabled. </PARA>
 827 </LISTITEM>
 828 <LISTITEM>
 829 <PARA>Place the code you want to debug between the matching
 830 functions
 831 <FUNCTION>cyg_instrument_enable()</FUNCTION>
 832  and
 833 <FUNCTION>cyg_instrument_disable()</FUNCTION>
 834 . </PARA>
 835 </LISTITEM>
 836 <LISTITEM>
 837 <PARA>Examine the buffer. For now you need to look at the data
 838 in there (the example program below shows how to do that), and future
 839 versions of <productname>eCos</productname> will include a host-side tool to help you understand
 840 the data. </PARA>
 841 </LISTITEM>
 842 </ORDEREDLIST>
 843 <EXAMPLE>
 844 <TITLE>Using instrument buffers</TITLE>
 845 <PARA>This program is also provided in the
 846             <FILENAME>examples</FILENAME> directory.
 847           </PARA>
 848 <PROGRAMLISTING>
 849 /* this is a program which uses <productname>eCos</productname> instrumentation buffers; it needs
 850  to be linked with a kernel which was compiled with support for
 851  instrumentation */
 852
 853 #include &lt;stdio.h&gt;
 854 #include &lt;pkgconf/kernel.h&gt;
 855 #include &lt;cyg/kernel/instrmnt.h&gt;
 856 #include &lt;cyg/kernel/kapi.h&gt;
 857
 858 #ifndef CYGVAR_KERNEL_INSTRUMENT_EXTERNAL_BUFFER
 859 # error You must configure eCos with CYGVAR_KERNEL_INSTRUMENT_EXTERNAL_BUFFER
 860 #endif
 861
 862 struct Instrument_Record
 863 {
 864  CYG_WORD16 type; // record type
 865  CYG_WORD16 thread; // current thread id
 866  CYG_WORD timestamp; // 32 bit timestamp
 867  CYG_WORD arg1; // first arg
 868  CYG_WORD arg2; // second arg
 869 };
 870
 871 struct Instrument_Record instrument_buffer[20];
 872 cyg_uint32 instrument_buffer_size = 20;
 873
 874 int main(void)
 875 {
 876  int i;
 877
 878  cyg_instrument_enable(CYG_INSTRUMENT_CLASS_CLOCK, 0);
 879  cyg_instrument_enable(CYG_INSTRUMENT_CLASS_THREAD, 0);
 880  cyg_instrument_enable(CYG_INSTRUMENT_CLASS_ALARM, 0);
 881
 882  printf("Program to play with instrumentation buffer\n");
 883
 884  cyg_thread_delay(2);
 885
 886  cyg_instrument_disable(CYG_INSTRUMENT_CLASS_CLOCK, 0);
 887  cyg_instrument_disable(CYG_INSTRUMENT_CLASS_THREAD, 0);
 888  cyg_instrument_disable(CYG_INSTRUMENT_CLASS_ALARM, 0);
 889
 890  for (i = 0; i &lt; instrument_buffer_size; ++i) {
 891  printf("Record %02d: type 0x%04x, thread %d, ",
 892         i, instrument_buffer[i].type, instrument_buffer[i].thread);
 893  printf("time %5d, arg1 0x%08x, arg2 0x%08x\n",
 894         instrument_buffer[i].timestamp, instrument_buffer[i].arg1,
 895         instrument_buffer[i].arg2);
 896  }
 897  return 0;
 898 }</PROGRAMLISTING>
 899 </EXAMPLE>
 900 <PARA>Here is how you could compile and run this program in the <filename>examples</filename> directory,
 901 using (for example) the MN10300 simulator target: </PARA>
 902 <SCREEN>
 903 $ make XCC=mn10300-elf-gcc INSTALL_DIR=/tmp/ecos-work-mn10300/install instrument-test
 904 mn10300-elf-gcc -c -o instrument-test.o -g -Wall -I/tmp/ecos-work-mn10300/install/include \
 905         -ffunction-sections -fdata-sections instrument-test.c
 906 mn10300-elf-gcc -nostartfiles -L/tmp/ecos-work-mn10300/install/lib -W1,--gc-sections -o \
 907         instrument-test instrument-test.o -Ttarget.ld -nostdlib
 908 $ mn10300-elf-run --board=stdeval1 instrument-test
 909 </SCREEN>
 910 <EXAMPLE>
 911 <TITLE>Instrument buffer output</TITLE>
 912 <PARA>Here is the output of the
 913             <COMMAND>instrument-test</COMMAND> program. Notice that in
 914             little over 2 seconds, and with very little activity, and
 915             with few event types enabled, it gathered 17 records. In
 916             larger programs it will be necessary to select very few
 917             event types for debugging. </PARA>
 918 <PROGRAMLISTING>Program to play with instrumentation buffer
 919 Record 00: type 0x0207, thread 2, time  6057, arg1 0x48001cd8, arg2 0x00000002
 920 Record 01: type 0x0202, thread 2, time  6153, arg1 0x48001cd8, arg2 0x00000000
 921 Record 02: type 0x0904, thread 2, time  6358, arg1 0x48001d24, arg2 0x00000000
 922 Record 03: type 0x0905, thread 2, time  6424, arg1 0x00000002, arg2 0x00000000
 923 Record 04: type 0x0906, thread 2, time  6490, arg1 0x00000000, arg2 0x00000000
 924 Record 05: type 0x0901, thread 2, time  6608, arg1 0x48009d74, arg2 0x48001d24
 925 Record 06: type 0x0201, thread 2, time  6804, arg1 0x48001cd8, arg2 0x480013e0
 926 Record 07: type 0x0803, thread 1, time    94, arg1 0x00000000, arg2 0x00000000
 927 Record 08: type 0x0801, thread 1, time   361, arg1 0x00000000, arg2 0x00000000
 928 Record 09: type 0x0802, thread 1, time   548, arg1 0x00000001, arg2 0x00000000
 929 Record 10: type 0x0803, thread 1, time    94, arg1 0x00000000, arg2 0x00000000
 930 Record 11: type 0x0801, thread 1, time   361, arg1 0x00000001, arg2 0x00000000
 931 Record 12: type 0x0903, thread 1, time   513, arg1 0x48009d74, arg2 0x48001d24
 932 Record 13: type 0x0208, thread 1, time   588, arg1 0x00000000, arg2 0x00000000
 933 Record 14: type 0x0203, thread 1, time   697, arg1 0x48001cd8, arg2 0x480013e0
 934 Record 15: type 0x0802, thread 1, time   946, arg1 0x00000002, arg2 0x00000000
 935 Record 16: type 0x0201, thread 1, time  1083, arg1 0x480013e0, arg2 0x48001cd8
 936 Record 17: type 0x0000, thread 0, time     0, arg1 0x00000000, arg2 0x00000000
 937 Record 18: type 0x0000, thread 0, time     0, arg1 0x00000000, arg2 0x00000000
 938 Record 19: type 0x0000, thread 0, time     0, arg1 0x00000000, arg2 0x00000000</PROGRAMLISTING>
 939 </EXAMPLE>
 940 </SECT1>
 941 </CHAPTER>
 942 </PART>
 943 <!-- Keep this comment at the end of the file
 944 Local variables:
 945 mode: sgml
 946 sgml-omittag:nil
 947 sgml-shorttag:t
 948 sgml-namecase-general:t
 949 sgml-general-insert-case:lower
 950 sgml-minimize-attributes:nil
 951 sgml-always-quote-attributes:t
 952 sgml-indent-step:2
 953 sgml-indent-data:t
 954 sgml-parent-document:("user-guide.sgml" "book" "part")
 955 sgml-exposed-tags:nil
 956 sgml-local-catalogs:nil
 957 sgml-local-ecat-files:nil
 958 End:
 959 -->