flash_v2: doc/sgml/user-guide/programming-concepts-techniques.sgml annotate

annotate doc/sgml/user-guide/programming-concepts-techniques.sgml @ 1387:5d11e2db0035

* sgml/doclist: Added ipsec packages documentation * sgml/makemakefile: Added another set of man pages to the kludge.

author	asl
date	Sat, 22 Nov 2003 13:06:58 +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 <!-- =============================================================== -->
c9cbf5dfb306 Update documentation licenses to remove restriction on redistributing bartv parents: 208 diff changeset	10 <!-- ####COPYRIGHTBEGIN#### -->
c9cbf5dfb306 Update documentation licenses to remove restriction on redistributing bartv parents: 208 diff changeset	11 <!-- -->
c9cbf5dfb306 Update documentation licenses to remove restriction on redistributing bartv parents: 208 diff changeset	12 <!-- =============================================================== -->
c9cbf5dfb306 Update documentation licenses to remove restriction on redistributing bartv parents: 208 diff changeset	13 <!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc. -->
c9cbf5dfb306 Update documentation licenses to remove restriction on redistributing bartv parents: 208 diff changeset	14 <!-- This material may be distributed only subject to the terms -->
c9cbf5dfb306 Update documentation licenses to remove restriction on redistributing bartv parents: 208 diff changeset	15 <!-- and conditions set forth in the Open Publication License, v1.0 -->
c9cbf5dfb306 Update documentation licenses to remove restriction on redistributing bartv parents: 208 diff changeset	16 <!-- or later (the latest version is presently available at -->
c9cbf5dfb306 Update documentation licenses to remove restriction on redistributing bartv parents: 208 diff changeset	17 <!-- http://www.opencontent.org/openpub/) -->
c9cbf5dfb306 Update documentation licenses to remove restriction on redistributing bartv parents: 208 diff changeset	18 <!-- Distribution of the work or derivative of the work in any -->
c9cbf5dfb306 Update documentation licenses to remove restriction on redistributing bartv parents: 208 diff changeset	19 <!-- standard (paper) book form is prohibited unless prior -->
c9cbf5dfb306 Update documentation licenses to remove restriction on redistributing bartv parents: 208 diff changeset	20 <!-- permission obtained from the copyright holder -->
c9cbf5dfb306 Update documentation licenses to remove restriction on redistributing bartv parents: 208 diff changeset	21 <!-- =============================================================== -->
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 <!-- ####COPYRIGHTEND#### -->
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 <!-- #####DESCRIPTIONBEGIN#### -->
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 <!-- ####DESCRIPTIONEND#### -->
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
c9cbf5dfb306 Update documentation licenses to remove restriction on redistributing bartv parents: 208 diff changeset	30 <!-- }}} -->
c9cbf5dfb306 Update documentation licenses to remove restriction on redistributing bartv parents: 208 diff changeset	31
208 e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	32 <PART id="ecos-programming-concepts-and-techniques">
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	33 <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	34 <PARTINTRO id="programming-partintro">
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	35 <PARA>Programming with <productname>eCos</productname> is somewhat different from programming
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	36 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	37 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	38 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	39 <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	40 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	41 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	42 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	43 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	44 applications.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	45 </PARTINTRO>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	46 <CHAPTER id="cdl-concepts">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	47 <TITLE>CDL Concepts</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	48 <SECT1 id="cdl-concepts-about">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	49 <TITLE>About this chapter</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	50 <PARA>This chapter serves as a brief introduction to the
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	51 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	52 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	53 underlying technology to a level required for the embedded
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	54 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	55 detail aspects such as how to write reusable components for
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	56 <productname>eCos</productname>: this information is given in the <citetitle>Component
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	57 Writer’s Guide</citetitle>.</PARA>
208 e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	58 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	59 <TITLE>Background</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	60 <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	61 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	62 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	63 performance and robustness. These demands are addressed in
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	64 <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	65 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	66 system to suit the needs of the application. In order to
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	67 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	68 of a Configuration Infrastructure: a set of tools including
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	69 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	70 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	71 <EMPHASIS>Component Definition Language</EMPHASIS>.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	72 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	73 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	74 <TITLE>Configurations</TITLE>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	75 <PARA><productname>eCos</productname> is tailored at source level (that is, before
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	76 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	77 <EMPHASIS>configuration</EMPHASIS>. In concrete terms, an
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	78 <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	79 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	80 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	81 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	82 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	83 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	84 <SECT1 id="cdl-component-repository">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	85 <TITLE>Component Repository</TITLE>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	86 <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	87 <EMPHASIS>component repository</EMPHASIS> - a directory
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	88 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	89 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	90 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	91 net.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	92 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	93 <SECT1 id="cdl-component-definition-language">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	94 <TITLE>Component Definition Language</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	95 <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	96 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	97 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	98 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	99 between components and other information used by tools such
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	100 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	101 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	102 is not necessary to write or understand CDL in order for the
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	103 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	104 configuration. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	105 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	106 <SECT1 id="cdl-packages">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	107 <TITLE>Packages</TITLE>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	108 <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	109 <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	110 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	111 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	112 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	113 future.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	114 <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	115 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	116 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	117 repository at any given time.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	118 <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	119 is either at the top-level or is the child of another package.</PARA>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	120 <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	121 packages from the component repository. The <productname>eCos</productname> <APPLICATION>Configuration Tool</APPLICATION> can be used to include or exclude packages from the configuration
208 e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	122 being built.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	123 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	124 <SECT1 id="cdl-configuration-items">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	125 <TITLE>Configuration Items</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	126 <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	127 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	128 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	129 example,
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	130 <literal>CYGHWR_HAL_ARM_PID_GDB_BAUD</literal>).
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	131 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	132 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	133 likewise.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	134 <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	135 <ITEMIZEDLIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	136 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	137 <PARA><EMPHASIS>None</EMPHASIS>: such entities serve only as
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	138 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	139 more easily.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	140 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	141 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	142 <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	143 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	144 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	145 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	146 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	147 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	148 <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	149 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	150 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	151 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	152 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	153 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	154 <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	155 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	156 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	157 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	158 </ITEMIZEDLIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	159 <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	160 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	161 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	162 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	163 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	164 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	165 <TITLE>Expressions</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	166 <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	167 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	168 <table id="cdl-expressions">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	169 <title>CDL Expressions</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	170 <tgroup cols="3">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	171 <thead>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	172 <row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	173 <entry>Expression Type</entry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	174 <entry>Result</entry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	175 <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	176 </thead>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	177 <tbody>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	178 <row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	179 <entry>Ordinary</entry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	180 <entry>A single value</entry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	181 <entry>legal_values property</entry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	182 </row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	183 <row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	184 <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	185 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	186 <entry>legal_values property </entry></row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	187 <row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	188 <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	189 <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	190 </tbody>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	191 </tgroup>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	192 </table>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	193 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	194 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	195 <TITLE>Properties</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	196 <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	197 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	198 <table id="table-configuration-properties">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	199 <title>Configuration properties</title>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	200 <tgroup cols="2">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	201 <thead><row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	202 <entry><emphasis>Property</emphasis></entry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	203 <entry><emphasis>Use </emphasis></entry></row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	204 </thead>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	205 <tbody>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	206 <row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	207 <entry>Flavor</entry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	208 <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	209 described above </entry></row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	210 <row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	211 <entry>Enabled</entry><entry>Whether
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	212 the item is enabled </entry></row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	213 <row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	214 <entry>Current_value</entry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	215 <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	216 <row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	217 <entry>Default_value</entry>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	218 <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	219 item</entry></row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	220 <row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	221 <entry>Legal_values</entry><entry>A
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	222 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	223 1 to10) </entry></row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	224 <row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	225 <entry>Active_if</entry><entry>A
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	226 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	227 (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	228 <row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	229 <entry>Requires</entry><entry>A goal
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	230 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	231 below: <emphasis>Conflicts</emphasis>) </entry></row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	232 <row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	233 <entry>Calculated</entry><entry>Whether
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	234 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	235 <row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	236 <entry>Macro</entry><entry>The corresponding
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	237 C pre-processor macro </entry></row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	238 <row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	239 <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	240 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	241 <row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	242 <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	243 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	244 <row>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	245 <entry>Hardware</entry><entry>Indicates
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	246 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	247 </tbody>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	248 </tgroup>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	249 </table>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	250
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	251 <PARA>A complete description of properties is contained in the <citetitle>Component
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	252 Writer’s Guide</citetitle>.</PARA>
208 e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	253 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	254 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	255 <TITLE>Inactive Items</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	256 <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	257 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	258 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	259 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	260 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	261 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	262 <SECT1 id="cdl-conflicts">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	263 <TITLE>Conflicts</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	264 <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	265 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	266 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	267 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	268 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	269 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	270 <EMPHASIS>requires</EMPHASIS> and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	271 <EMPHASIS>active_if</EMPHASIS> attributes [see
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	272 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	273 <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	274 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	275 resolution can be performed manually or with the assistance
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	276 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	277 flavors:</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	278 <ITEMIZEDLIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	279 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	280 <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	281 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	282 configuration </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	283 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	284 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	285 <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	286 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	287 (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	288 is failing) </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	289 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	290 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	291 <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	292 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	293 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	294 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	295 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	296 <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	297 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	298 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	299 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	300 <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	301 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	302 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	303 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	304 </ITEMIZEDLIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	305 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	306 <SECT1 id="cdl-templates">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	307 <TITLE>Templates</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	308 <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	309 - that is, a set of packages and configuration item
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	310 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	311 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	312 configuration corresponding to one of a number of common
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	313 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	314 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	315 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	316 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	317 </CHAPTER>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	318 <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	319 <TITLE>The Component Repository and Working Directories</TITLE>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	320 <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	321 different role. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	322 <SECT1 id="component-repo">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	323 <TITLE>Component Repository</TITLE>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	324 <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	325 contains directories for all the packages that are shipped
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	326 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	327 <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	328 application development. </PARA>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	329 <!--
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	330 <para>
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	331 XXXXX We may want to change this picture XXXXX
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	332 </para>
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	333 -->
208 e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	334 <FIGURE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	335 <TITLE>Component repository</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	336 <GRAPHIC ENTITYREF="graphic30"></GRAPHIC>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	337 </FIGURE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	338 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	339 <TITLE>Purpose</TITLE>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	340 <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	341 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	342 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	343 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	344 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	345 <TITLE>How is it modified?</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	346 <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	347 distribution or removing existing packages. These activities are
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	348 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	349 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	350 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	351 <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	352 <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	353 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	354 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	355 <SECT2>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	356 <TITLE>User Applications</TITLE>
208 e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	357 <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	358 into the component repository.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	359 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	360 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	361 <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	362 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	363 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	364 <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	365 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	366 <PARA>The top level HTML file for the
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	367 <citetitle><PRODUCTNAME>eCos</PRODUCTNAME> Reference
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	368 Manual</citetitle>. </PARA>
208 e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	369 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	370 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	371 <VARLISTENTRY>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	372 <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	373 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	374 <PARA></PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	375 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	376 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	377 <VARLISTENTRY>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	378 <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	379 <LISTITEM>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	380 <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	381 the synthetic Linux target.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	382 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	383 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	384 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	385 <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	386 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	387 <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	388 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	389 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	390 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	391 <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	392 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	393 <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	394 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	395 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	396 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	397 <VARLISTENTRY>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	398 <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	399 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	400 <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	401 math library.</para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	402 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	403 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	404 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	405 <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	406 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	407 <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	408 by the <FILENAME>makefile</FILENAME>.</para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	409 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	410 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	411 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	412 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	413 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	414 <SECT1 id="build-tree">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	415 <TITLE>Build Tree</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	416 <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	417 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	418 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	419 <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	420 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	421 extension) for each source file.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	422 <SECT2><!--<conditionaltext>-->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	423 <TITLE>Purpose</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	424 <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	425 placed. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	426 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	427 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	428 <TITLE>How is it modified?</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	429 <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	430 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	431 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	432 <TITLE>User applications</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	433 <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	434 <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	435 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	436 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	437 <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	438 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	439 <VARLISTENTRY>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	440 <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	441 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	442 <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	443 the C library are built.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	444 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	445 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	446 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	447 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	448 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	449 <SECT1 id="install-tree">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	450 <TITLE>Install Tree</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	451 <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	452 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	453 <filename>libtarget.a</filename> library, which contains the
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	454 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	455 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	456 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	457 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	458 tree. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	459 <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	460 <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	461 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	462 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	463 <xref linkend="manual-configuration">).
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	464 </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	465 <SECT2><!--<conditionaltext>-->
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	466 <TITLE>Purpose</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	467 <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	468 <FILENAME>libtarget.a</FILENAME> library, which contains
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	469 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	470 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	471 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	472 component. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	473 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	474 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	475 <TITLE>How is it modified?</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	476 <PARA>Recompiling can replace
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	477 <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	478 executables. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	479 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	480 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	481 <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	482 <PARA>Where a memory layout requires modification without
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	483 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	484 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	485 files are located at
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	486 <FILENAME>install/include/pkgconf/mlt_.</FILENAME>.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	487 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	488 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	489 edits being lost.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	490 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	491 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	492 <TITLE>User applications</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	493 <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	494 <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	495 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	496 <SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	497 <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	498 <VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	499 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	500 <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	501 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	502 <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	503 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	504 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	505 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	506 <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	507 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	508 <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	509 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	510 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	511 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	512 <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	513 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	514 <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	515 layout for linking applications intended for
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	516 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	517 startup.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	518 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	519 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	520 <VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	521 <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	522 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	523 <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	524 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	525 </VARLISTENTRY>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	526 </VARIABLELIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	527 </SECT2>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	528 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	529 <SECT1 id="repository-app-build-tree">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	530 <TITLE>Application Build Tree</TITLE>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	531 <PARA>This tree is not part of <productname>eCos</productname> itself: it is the
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	532 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	533 applications.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	534 <PARA>Example applications and their
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	535 <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	536 repository, in the directory
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	537 <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	538
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	539 </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	540 <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	541 are certain compiler and linker flags that must be used to
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	542 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	543 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	544 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	545 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	546 </CHAPTER>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	547 <CHAPTER id="compiler-and-linker-options">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	548 <TITLE>Compiler and Linker Options</TITLE>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	549
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	550 <PARA><productname>eCos</productname> is built using
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	551 the GNU C and C++ compilers. <productname>eCos</productname> relies on certain features of these
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	552 tools such as constructor priority ordering and selective linking
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	553 which are not part of other toolchains.
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	554 </PARA>
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	555
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	556 <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	557 and others can be useful. This chapter gives a brief description
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	558 of the required options as well as some recommended <productname>eCos</productname>-specific options.
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	559 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	560 are available. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	561 <SECT1 id="compiling-c-app">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	562 <TITLE>Compiling a C Application</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	563 <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	564 <EMPHASIS>minimum</EMPHASIS> set of options required to
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	565 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	566 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	567 <PARA>Remember that when this manual shows
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	568 <COMMAND><replaceable>TARGET-</replaceable>gcc</COMMAND>
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	569 you should use the full name of the cross compiler,
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	570 e.g. <COMMAND>i386-elf-gcc</COMMAND>,
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	571 <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	572 <COMMAND>sh-elf-gcc</COMMAND>. When compiling for the
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	573 synthetic Linux target, use the native
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	574 <command>gcc</command> which must have the features
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	575 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	576 </NOTE>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	577 <SCREEN>
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	578 $ <replaceable>TARGET-</replaceable>gcc -c -I<EMPHASIS>INSTALL_DIR</EMPHASIS>/include file.c
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	579 $ <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	580 </SCREEN>
208 e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	581 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	582 <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	583 the SPARClite architectures require the option
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	584 <OPTION>-mcpu=sparclite</OPTION>. Examine the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	585 <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	586 or the “Global compiler flags” option
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	587 (CYGBLD_GLOBAL_CFLAGS) in your generated
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	588 <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	589 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	590 <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	591 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	592 <!-- <index></index> -->selective linking feature:</PARA>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	593 <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	594 $ <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	595 -L<REPLACEABLE>INSTALL_DIR</REPLACEABLE>/lib -Ttarget.ld -nostdlib
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	596 </SCREEN>
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	597
208 e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	598 </NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	599 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	600 <SECT1 id="compiling-cpp-app">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	601 <TITLE>Compiling a C++ Application</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	602 <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	603 <EMPHASIS>minimum</EMPHASIS> set of options required to
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	604 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	605 </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	606 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	607 <PARA>Remember that when this manual shows
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	608 <COMMAND><replaceable>TARGET-</replaceable>g++</COMMAND>
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	609 you should use the full name of the cross compiler,
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	610 e.g. <COMMAND>i386-elf-g++</COMMAND>,
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	611 <COMMAND>arm-elf-g++</COMMAND>, or
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	612 <COMMAND>sh-elf-g++</COMMAND>. When compiling for the
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	613 synthetic Linux target, use the native
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	614 <command>g++</command> which must have the features
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	615 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	616 </NOTE>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	617 <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	618 $ <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	619 </SCREEN>
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	620
208 e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	621 <NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	622 <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	623 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	624 <OPTION>-mcpu=sparclite</OPTION>. Examine the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	625 <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	626 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	627 or the “Global compiler flags” option
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	628 (CYGBLD_GLOBAL_CFLAGS) in your generated
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	629 <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	630 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	631 <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	632 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	633 <FIRSTTERM>selective linking</FIRSTTERM> feature:</PARA>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	634 <SCREEN>
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	635 $ <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	636 -fno-exceptions -finit-priority -g -O2 file.cxx
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	637 $ <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	638 </NOTE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	639 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	640 </CHAPTER>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	641
208 e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	642 <CHAPTER id="debugging-techniques">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	643 <TITLE>Debugging Techniques</TITLE>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	644 <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	645 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	646 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	647 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	648 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	649 source, and cannot be slowed down or interrupted.</PARA>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	650 <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	651 <EMPHASIS>tracing</EMPHASIS> formalism, allowing the
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	652 kernel’s tracing macros to be configured in many useful
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	653 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	654 buffers</FIRSTTERM> which also collect specific
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	655 (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	656 performance.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	657 <SECT1 id="tracing">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	658 <TITLE>Tracing</TITLE>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	659 <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	660 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	661 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	662 (<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	663 <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	664 (<OPTION>CYGDBG_USE_TRACING</OPTION>). These
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	665 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	666 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	667 <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	668 </FILENAME> manually.</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	669 <PARA>You should then examine all the tracing-related options in
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	670 the <citetitle>Package: Infrastructure</citetitle> chapter of the <citetitle><PRODUCTNAME>eCos</PRODUCTNAME> Reference
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	671 Manual</citetitle>. One useful set of configuration options are: <literal>CYGDBG_INFRA_DEBUG_FUNCTION_REPORTS</literal> and <literal>CYGDBG_INFRA_DEBUG_TRACE_MESSAGE</literal>,
208 e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	672 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	673 <PARA>The following “Hello world with tracing” shows
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	674 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	675 built with tracing enabled: </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	676 <EXAMPLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	677 <TITLE>Hello world with tracing</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	678 <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	679 Hello, eCos world!
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	680 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	681 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	682 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	683 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	684 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	685 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	686 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	687 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	688 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	689 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	690 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	691 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	692 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	693 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	694 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	695 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	696 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	697 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	698 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	699 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	700 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	701 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	702 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	703 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	704 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	705 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	706 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	707 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	708 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	709 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	710 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	711 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	712 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	713
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	714 Scheduler:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	715
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	716 Lock: 0
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	717 Current Thread: <null>
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 Threads:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	720
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	721 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	722 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	723 sleep reason NONE wake reason NONE
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	724 queue = 80000C54 wait info = 00000000
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	725
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	726 <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	727 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	728 sleep reason NONE wake reason NONE
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	729 queue = 80000BD8 wait info = 00000000
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	730 </SCREEN>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	731 </EXAMPLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	732 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	733 <SECT1 id="kernel-instrumentation">
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	734 <TITLE>Kernel Instrumentation</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	735 <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	736 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	737 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	738 <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	739 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	740 <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	741 monitored are:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	742 </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	743 <ITEMIZEDLIST>
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 <PARA>scheduler events </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	746 </LISTITEM>
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 <PARA>thread operations</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	749 </LISTITEM>
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 <PARA>interrupts </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	752 </LISTITEM>
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 <PARA>mutex operations </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	755 </LISTITEM>
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 <PARA>binary semaphore operations </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	758 </LISTITEM>
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 <PARA>counting semaphore operations </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	761 </LISTITEM>
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 <PARA>clock ticks and interrupts </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	764 </LISTITEM>
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 <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	767 <ITEMIZEDLIST>
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 <PARA>scheduler lock</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	770 </LISTITEM>
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 <PARA>scheduler unlock</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	773 </LISTITEM>
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 <PARA>rescheduling</PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	776 </LISTITEM>
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 <PARA>time slicing </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	779 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	780 </ITEMIZEDLIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	781 <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	782 <FIRSTTERM>event record</FIRSTTERM>. The structure that
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	783 defines this record has type <type>struct
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	784 Instrument_Record</type>:
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	785 </PARA>
208 e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	786 <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	787 which you can let the kernel provide or you can provide yourself
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	788 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	789 <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	790 buffers: </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	791 <ORDEREDLIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	792 <LISTITEM>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	793 <PARA>Enable instrumentation buffers in the <productname>eCos</productname> kernel configuration.
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	794 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	795 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	796 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	797 <PARA>To allocate the buffers yourself, enable the configuration
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	798 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	799 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	800 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	801 <PARA>Include the header file
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	802 <FILENAME>cyg/kernel/instrmnt.h</FILENAME>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	803 .
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	804 <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	805 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	806 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	807 <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	808 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	809 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	810 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	811 </para>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	812 <PROGRAMLISTING>struct Instrument_Record
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	813 {
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	814 CYG_WORD16 type; // record type
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	815 CYG_WORD16 thread; // current thread id
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	816 CYG_WORD timestamp; // 32 bit timestamp
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	817 CYG_WORD arg1; // first arg
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	818 CYG_WORD arg2; // second arg
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	819 };</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	820 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	821 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	822 <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	823 <FUNCTION>cyg_instrument_enable()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	824 , and disable them later. Look at
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	825 <filename>cyg/kernel/instrmnt.h</filename>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	826 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	827 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	828 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	829 <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	830 functions
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	831 <FUNCTION>cyg_instrument_enable()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	832 and
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	833 <FUNCTION>cyg_instrument_disable()</FUNCTION>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	834 . </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	835 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	836 <LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	837 <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	838 in there (the example program below shows how to do that), and future
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	839 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	840 the data. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	841 </LISTITEM>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	842 </ORDEREDLIST>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	843 <EXAMPLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	844 <TITLE>Using instrument buffers</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	845 <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	846 <FILENAME>examples</FILENAME> directory.
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	847 </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	848 <PROGRAMLISTING>
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	849 /* 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	850 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	851 instrumentation */
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	852
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	853 #include <stdio.h>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	854 #include <pkgconf/kernel.h>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	855 #include <cyg/kernel/instrmnt.h>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	856 #include <cyg/kernel/kapi.h>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	857
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	858 #ifndef CYGVAR_KERNEL_INSTRUMENT_EXTERNAL_BUFFER
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	859 # 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	860 #endif
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 struct Instrument_Record
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	863 {
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	864 CYG_WORD16 type; // record type
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	865 CYG_WORD16 thread; // current thread id
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	866 CYG_WORD timestamp; // 32 bit timestamp
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	867 CYG_WORD arg1; // first arg
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	868 CYG_WORD arg2; // second arg
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	869 };
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	870
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	871 struct Instrument_Record instrument_buffer[20];
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	872 cyg_uint32 instrument_buffer_size = 20;
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 main(void)
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 int i;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	877
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_CLOCK, 0);
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	879 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	880 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	881
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	882 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	883
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	884 cyg_thread_delay(2);
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	885
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_CLOCK, 0);
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	887 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	888 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	889
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	890 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	891 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	892 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	893 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	894 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	895 instrument_buffer[i].arg2);
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	896 }
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	897 return 0;
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	898 }</PROGRAMLISTING>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	899 </EXAMPLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	900 <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	901 using (for example) the MN10300 simulator target: </PARA>
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	902 <SCREEN>
783 14f00bde1f7a * programming-concepts-techniques.sgml: jld parents: 596 diff changeset	903 $ make XCC=mn10300-elf-gcc INSTALL_DIR=/tmp/ecos-work-mn10300/install instrument-test
596 d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	904 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	905 -ffunction-sections -fdata-sections instrument-test.c
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	906 mn10300-elf-gcc -nostartfiles -L/tmp/ecos-work-mn10300/install/lib -W1,--gc-sections -o \
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	907 instrument-test instrument-test.o -Ttarget.ld -nostdlib
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	908 $ mn10300-elf-run --board=stdeval1 instrument-test
d729dea5c4a8 * user-guide.sgml: nickg parents: 334 diff changeset	909 </SCREEN>
208 e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	910 <EXAMPLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	911 <TITLE>Instrument buffer output</TITLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	912 <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	913 <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	914 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	915 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	916 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	917 event types for debugging. </PARA>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	918 <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	919 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	920 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	921 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	922 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	923 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	924 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	925 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	926 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	927 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	928 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	929 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	930 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	931 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	932 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	933 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	934 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	935 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	936 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	937 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	938 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	939 </EXAMPLE>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	940 </SECT1>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	941 </CHAPTER>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	942 </PART>
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	943 <!-- 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	944 Local variables:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	945 mode: sgml
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	946 sgml-omittag:nil
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	947 sgml-shorttag:t
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	948 sgml-namecase-general:t
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	949 sgml-general-insert-case:lower
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	950 sgml-minimize-attributes:nil
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	951 sgml-always-quote-attributes:t
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	952 sgml-indent-step:2
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	953 sgml-indent-data:t
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	954 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	955 sgml-exposed-tags:nil
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	956 sgml-local-catalogs:nil
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	957 sgml-local-ecat-files:nil
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	958 End:
e0c0827131d1 Merge from eCos master repository on 2002-05-20-20:11:54-BST jlarmour parents: diff changeset	959 -->

Mercurial > flash_v2

annotate doc/sgml/user-guide/programming-concepts-techniques.sgml @ 1387:5d11e2db0035