ecos-v3_0-branch: doc/sgml/user-guide/programming-concepts-techniques.sgml annotate

annotate doc/sgml/user-guide/programming-concepts-techniques.sgml @ 2729:74dbf4c3f2e1 after-copyright-change-20090129

Update all copyright banners to reflect FSF ownership; fix and improve licence text.

author	jlarmour
date	Thu, 29 Jan 2009 17:47:46 +0000
parents	14f00bde1f7a
children

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

Mercurial > ecos-v3_0-branch

annotate doc/sgml/user-guide/programming-concepts-techniques.sgml @ 2729:74dbf4c3f2e1 after-copyright-change-20090129