path: root/ecos/doc/sgml/user-guide/configuration.sgml

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     configuration.sgml                                          -->
<!--                                                                 -->
<!--     eCos User Guide                                             -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####ECOSDOCCOPYRIGHTBEGIN####                                       -->
<!-- ===============================================================     -->
<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. -->
<!-- This material may be distributed only subject to the terms          -->
<!-- and conditions set forth in the Open Publication License, v1.0      -->
<!-- or later (the latest version is presently available at              -->
<!-- http://www.opencontent.org/openpub/)                                -->
<!-- Distribution of the work or derivative of the work in any           -->
<!-- standard (paper) book form is prohibited unless prior               -->
<!-- permission obtained from the copyright holder                       -->
<!-- ===============================================================     -->
<!-- ####ECOSDOCCOPYRIGHTEND####                                         -->
<!-- =============================================================== -->
<!-- #####DESCRIPTIONBEGIN####                                       -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<PART id="configuration-and-the-package-repository">
<TITLE>Configuration and the Package Repository</TITLE>
<PARTINTRO>
<PARA>The following chapters contain information on running
	<COMMAND>ecosconfig</COMMAND> (the command line tool that
	manipulates configurations and constructs build trees) and on
	managing a source repository across multiple versions of
	<productname>eCos</productname>. </PARA>
</PARTINTRO>
<CHAPTER id="manual-configuration">
<TITLE>Manual Configuration</TITLE>

    <PARA><productname>eCos</productname> developers will generally use the graphical
      Configuration Tool for configuring an <productname>eCos</productname> system and building
      the target library. However, some user prefer to use command
      line tools. These command line tools can also be used for batch
      operations on all platforms, for example as part of a nightly
      rebuild and testing procedure.
    </PARA>

<PARA>In the current release of the system the command line tools
      do not provide exactly the same functionality as the graphical
      tool. Most importantly, there is no facility to resolve
      configuration conflicts interactively.</PARA>
<PARA>The <productname>eCos</productname> configuration system, both graphical and command
      line tools, are under constant development and enhancement.
      Developers should note that the procedures described may change
      considerably in future releases. </PARA>

<SECT1 id="directory-tree-structure">
<TITLE>Directory Tree Structure</TITLE>
<PARA>When building <productname>eCos</productname> there are three main directory trees to
	consider: the source tree, the build tree, and the install
	tree.</PARA>
<PARA>The source tree, also known as the component repository,
	  is read-only. It is possible to use a single component
	  repository for any number of different configurations, and
	  it is also possible to share a component repository between
	  multiple users by putting it on a network drive.</PARA>
<PARA>The build tree contains everything that is specific to a
	  particular configuration, including header and other files
	  that contain configuration data, and the object files that
	  result from compiling the system sources for this
	  configuration. </PARA>
<PARA>The install tree is usually located in the <filename>install</filename> subdirectory
of the build tree. Once an <productname>eCos</productname> system has been built, the install
tree contains all the files needed for application development including
the header files and the target library. By making copies of the
install tree after a build it is possible to separate application
development and system configuration, which may be desirable for
some organizations. </PARA>
</SECT1>

<SECT1 id="creating-build-tree">
<TITLE>Creating the Build Tree</TITLE>
<PARA>Generating a build tree is a non-trivial operation and
	  should not be attempted manually. Instead, <productname>eCos</productname> is shipped
	  with a tool called <COMMAND>ecosconfig</COMMAND> that should
	  be used to create a build tree.</PARA>
<PARA>Usually <command>ecosconfig</command> will be
run inside the build tree itself. If you are creating a new build
tree then typically you will create a new empty directory using
the <command>mkdir</command> command, <command>cd</command> into
that directory, and then invoke <command>ecosconfig</command> to
create a configuration. By default, the configuration is stored
in a file <filename>ecos.ecc</filename> in the current
directory. The configuration may be modified by editing this file directly. <command>ecosconfig</command> itself
deals with a number of coarse-grained configuration options such
as the target platform and the packages that should be used.</PARA>
<PARA>The <command>ecosconfig</command> tool is also
used subsequently to generate a build tree for a configuration.
Once a build tree exists, it is possible to run <command>ecosconfig</command> again
inside the same build tree. This will be necessary if your wish
to change some of the configuration options.</PARA>
<PARA><COMMAND>ecosconfig</COMMAND> does not generate
the top-level directory of the build tree; you must do this
	yourself. </PARA>
<SCREEN>$ mkdir ecos-work
$ cd ecos-work</SCREEN>
<PARA>The next step is to run <COMMAND>ecosconfig</COMMAND>: </PARA>
<SCREEN>$ ecosconfig &lt;qualifiers&gt; &lt;command&gt;</SCREEN>
<SECT2>
<TITLE>ecosconfig qualifiers</TITLE>
<PARA>The available command line qualifiers for
	    <COMMAND>ecosconfig</COMMAND> are as follows. Multiple
	    qualifiers may be used on the command line:
	  </PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM><OPTION>--help</OPTION></TERM>
<LISTITEM>
<PARA>Provides basic usage guidelines for the
	      available commands and qualifiers.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><OPTION>--config=&lt;file&gt;</OPTION></TERM>
<LISTITEM>
<PARA>Specifies an <productname>eCos</productname> configuration save file for
		  use by the tool. By default, the file
		  <filename>ecos.ecc</filename> in the
		  current directory is used. Developers may prefer to
		  use a common location for all their <productname>eCos</productname>
		  configurations rather than keep the configuration
		  information in the base of the build tree.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><OPTION>--prefix=&lt;dir&gt;</OPTION></TERM>
<LISTITEM>
<PARA>Specifies an alternative location for the
		  install tree. By default, the install tree resides
		  inside the <filename>install</filename>
		  directory in the build tree. Developers may prefer
		  to locate the build tree in a temporary file
		  hierarchy but keep the install tree in a more
		  permanent location.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><OPTION>--srcdir=&lt;dir&gt;</OPTION></TERM>
<LISTITEM>
<PARA>Specifies the location of the component
		  repository. By default, the tool uses the location
		  specified in the
		  <REPLACEABLE>ECOS_REPOSITORY</REPLACEABLE>
		  environment variable. Developers may prefer to use
		  of this qualifier if they are working with more than
		  one repository.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><OPTION>--no-resolve</OPTION></TERM>
<LISTITEM>
<PARA>Disables the implicit resolution of conflicts
		  while manipulating the configuration data.
		  developers may prefer to resolve conflicts by
		  editing the <productname>eCos</productname> configuration save file
		  manually.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><OPTION>--ignore-errors</OPTION></TERM>
<TERM><OPTION>-i</OPTION></TERM>
<LISTITEM>
<PARA>
By default, ecosconfig will exit with an error code if the current
configuration contains any conflicts, and it is not possible to
generate or update a build tree for such configurations. This
qualifier causes ecosconfig to ignore such problems, and hence it is
possible to generate a build tree even if there are still
conflicts. Of course, there are no guarantees that the resulting
system will actually do anything.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><OPTION>--verbose</OPTION></TERM>
<TERM><OPTION>-v</OPTION></TERM>
<LISTITEM>
<PARA>
Display more information.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><OPTION>--quiet</OPTION></TERM>
<TERM><OPTION>-q</OPTION></TERM>
<LISTITEM>
<PARA>
Display less information.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
<PARA>
The <OPTION>--config</OPTION>, <OPTION>--prefix</OPTION> and
<OPTION>--srcdir</OPTION> qualifiers can also be written with two arguments,
for example:
</para>
<SCREEN>
ecosconfig --srcdir <REPLACEABLE>&lt;dir&gt;</REPLACEABLE> ...
</SCREEN>
<para>
This simplifies filename completion with some shells.
</PARA>
</SECT2>
<SECT2>
<TITLE>ecosconfig commands</TITLE>
<PARA>The available commands for
	    <COMMAND>ecosconfig</COMMAND> are as
	    follows:</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM><COMMAND>list</COMMAND></TERM>
<LISTITEM>
<PARA>Lists the available packages, targets and
		  templates as installed in the <productname>eCos</productname> repository.
		  Aliases and package versions are also
		  reported.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>new &lt;target&gt; [&lt;template&gt; [&lt;version&gt;]]</COMMAND></TERM>
<LISTITEM>
<PARA>Creates a new <productname>eCos</productname> configuration for
		  the specified target hardware and saves it. A
		  software template may also be specified. By default,
		  the template named &lsquo;default&rsquo; is used. If
		  the template version is not specified, the latest
		  version is used.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>target &lt;target&gt;</COMMAND></TERM>
<LISTITEM>
<PARA>Changes the target hardware selection
		  for the <productname>eCos</productname> configuration. This has the effect of
		  unloading packages supporting the target selected
		  previously and loading the packages which support
		  the new hardware. This command will be used
		  typically when switching between a simulator and
		  real hardware.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>template &lt;template&gt; [&lt;version&gt;]</COMMAND></TERM>
<LISTITEM>
<PARA>Changes the template selection for the <productname>eCos</productname>
		  configuration. This has the effect of unloading
		  packages specified by the template selected
		  previously and loading the packages specified by the
		  new template. By default, the latest version of the
		  specified template is used.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>remove &lt;packages&gt;</COMMAND></TERM>
<LISTITEM>
<PARA>Removes the specified packages from the <productname>eCos</productname>
		  configuration. This command will be used typically
		  when the template on which a configuration is based
		  contains packages which are not required.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>add &lt;packages&gt;</COMMAND></TERM>
<LISTITEM>
<PARA>Adds the specified packages to the <productname>eCos</productname> configuration. This
command will be used typically when the template on which a
configuration is based does not contain all the packages which are
required.For example, add-on packages provided by third parties will
not be known to the standard templates, so they will have to be added
explicitly. </PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>version &lt;version&gt; &lt;packages&gt;</COMMAND></TERM>
<LISTITEM>
<PARA>Selects the specified version of a
		  number of packages in the <productname>eCos</productname> configuration. By
		  default, the most recent version of each package is
		  used. This command will be used typically when an
		  older version of a package is required.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>check</COMMAND></TERM>
<LISTITEM>
<PARA>Presents the following information
		  concerning the current configuration:</PARA>
<ORDEREDLIST>
<LISTITEM>
<PARA>the selected target hardware</PARA>
</LISTITEM>
<LISTITEM>
<PARA>the selected template</PARA>
</LISTITEM>
<LISTITEM>
<PARA>additional packages</PARA>
</LISTITEM>
<LISTITEM>
<PARA>removed packages</PARA>
</LISTITEM>
<LISTITEM>
<PARA>the selected version of packages
		      where this is not the most recent
		      version</PARA>
</LISTITEM>
<LISTITEM>
<PARA>conflicts in the current configuration</PARA>
</LISTITEM>
</ORDEREDLIST>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>resolve</COMMAND></TERM>
<LISTITEM>
<PARA>Resolves conflicts identified in the
		  current <productname>eCos</productname> configuration by invoking an inference
		  capability. Resolved conflicts are reported, but not
		  all conflicts may be resolvable. This command will
		  be used typically following manual editing of the
		  configuration.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>export &lt;file&gt;</COMMAND></TERM>
<LISTITEM>
<PARA>Exports a minimal <productname>eCos</productname> configuration
		  save file with the specified name. This file
		  contains only those options which do not have their
		  default value. Such files are used typically to
		  transfer option values from one configuration to
		  another.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>import &lt;file&gt;</COMMAND></TERM>
<LISTITEM>
<PARA>Imports a minimal <productname>eCos</productname> configuration
		  save file with the specified name. The values of
		  those options specified in the file are applied to
		  the current configuration.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>tree</COMMAND></TERM>
<LISTITEM>
<PARA>Generates a build tree based on the current <productname>eCos</productname>
		  configuration. This command will be used typically
		  just before building <productname>eCos</productname>.Normally a build tree can
only be generated if if the configuration has no unresolved
conflicts, but <OPTION>--ignore-errors</OPTION> can be used to override
this.</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</SECT2>
</SECT1>
<SECT1 id="conflicts-and-constraints">
<TITLE>Conflicts and constraints</TITLE>
<PARA>Configuration options are not completely independent. For example
the C library's <FUNCTION>strtod()</FUNCTION> and <FUNCTION>atof()</FUNCTION>
functions rely on the math library package to provide certain functionality. If the math library package is removed then the C
library can no longer provide these functions. Each package describes constraints like these in CDL <EMPHASIS>"requires"</EMPHASIS> properties. If a constraint is not satisfied, then the configuration contains a conflict. For any given conflict there can
be several resolution options. For example, it would be possible to add the math library package back to the
configuration, or to disable the <FUNCTION>strtod()</FUNCTION> and <FUNCTION>atof()</FUNCTION> functions.</PARA>
<PARA>
The <productname>eCos</productname> configuration tools will report any conflicts in the current configuration. If there are any such conflicts
then the configuration is usually unsafe and it makes no sense to build and run <productname>eCos</productname> in such circumstances. In fact,
any attempt at building <productname>eCos</productname> is likely to fail. In exceptional cases it is possible to override this by using e.g. the
<OPTION>--ignore-errors</OPTION> qualifier with ecosconfig. 
</PARA>
<PARA>
Many constraints are fairly simple in nature, and the configuration tools contain an inference engine which can
resolve the associated conflicts automatically. For example, if the math library package is removed then the
inference engine can resolve the resulting conflict by disabling the configuration option for <FUNCTION>strtod()</FUNCTION> and <FUNCTION>atof()</FUNCTION>. All
such changes will be reported. Sometimes the inference engine cannot resolve a conflict, for example it is not
allowed to override a change that has been made explicitly by the user. Sometimes it will find a solution which does
not match the application's requirements. 
</PARA>
<PARA>
A typical session involving conflicts would look something like this: 
<SCREEN>
$ ecosconfig new pid
</SCREEN>This creates a new configuration with the default template. For most targets this will not result in any conflicts,
because the default settings for the various options meet the requirements of the default template.
</PARA><PARA> For some targets
there may be conflicts and the inference engine would come into play. 
<SCREEN>
$ ecosconfig remove libm 
U CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, new inferred value 0 
U CYGFUN_LIBC_strtod, new inferred value 0 
U CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, new inferred value 0 
</SCREEN>
ecosconfig reports that this change caused three conflicts, all in the C library. The inference engine was able to
resolve all the conflicts and update the relevant configuration options accordingly. </PARA>
<PARA>To suppress the inference engine <OPTION>--no-resolve</OPTION> can be used: 
<SCREEN>
$ ecosconfig new pid
$ ecosconfig --no-resolve remove libm 
C CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, "requires" constraint not satisfied:      CYGPKG_LIBM 
C CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, "requires" constraint not satisfied:      CYGPKG_LIBM 
C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM 
</SCREEN>
Three unresolved conflicts are reported.
</PARA>
<PARA>The <COMMAND>check</COMMAND> command can be used to get the current state of the
configuration, and the <OPTION>--verbose</OPTION> qualifier will provide additional information: </PARA>
<SCREEN>
$ ecosconfig --srcdir /home/bartv/ecc/ecc --verbose check 
Target: pid 
Template: default 
Removed:
 CYGPKG_LIBM 
3 conflict(s): 
C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM
 Possible solution: 
    CYGFUN_LIBC_strtod -> 0 
    CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT -> 0 
C CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, "requires" constraint not satisfied:      CYGPKG_LIBM 
 Possible solution: 
    CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT -> 0 
C CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, "requires" constraint not satisfied:      CYGPKG_LIBM 
 Possible solution: 
    CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT -> 0 
</SCREEN>
<PARA>
If the proposed solutions are acceptable, the resolve command can be used to apply them: 
<SCREEN>
$ ecosconfig resolve 
U CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, new inferred value 0 
U CYGFUN_LIBC_strtod, new inferred value 0 
U CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, new inferred value 0 
</SCREEN></PARA>
<PARA>The current configuration is again conflict-free and it is possible to generate a build tree. The <OPTION>--quiet</OPTION> qualifier can
be used to suppress the change messages, if desired.
</PARA><PARA>
When changing individual configuration options by editing the ecos.ecc file (as described below), the resulting
system should be checked and any problems should be resolved. For example, if CYGFUN_LIBC_strtod is
explicitly enabled in the savefile:
<SCREEN>
$ edit ecos.ecc
$ ecosconfig check 
Target: pid 
Template: default 
Removed: 
    CYGPKG_LIBM 
1 conflict(s): 
C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM 
$ ecosconfig resolve 
C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM 
</SCREEN>
In this case the inference engine cannot resolve the conflict automatically because that would involve changing a
user setting. Any attempt to generate a build tree will fail: 
<SCREEN>
$ ecosconfig --srcdir /home/bartv/ecc/ecc tree 
C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM
Unable to generate build tree, this configuration still contains conflicts.
Either resolve the conflicts or use --ignore-errors 
</SCREEN>
</PARA><PARA>
It is still possible to generate a build tree: 
<SCREEN>
$ ecosconfig --srcdir /home/bartv/ecc/ecc --ignore-errors tree 
C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM 
$ make 
</SCREEN>
In this case <productname>eCos</productname> will fail to build. In other cases of unresolved conflicts <productname>eCos</productname> may build, but may not run. In
general all conflicts should be resolved by editing the <FILENAME>ecos.ecc</FILENAME> file, by letting the inference engine make appropriate
changes, or by other means, before any attempt is made to build or run <productname>eCos</productname>. 
</PARA>
</SECT1>
<SECT1 id="building-the-system">
<TITLE>Building the System</TITLE>
<PARA>Once a build tree has been generated with
	  <COMMAND>ecosconfig</COMMAND>, <!-- <index></index>
	  -->building <productname>eCos</productname> is straightforward:</PARA>
<SCREEN>$ make</SCREEN>
<PARA>The build tree contains the subdirectories, makefiles,
	  and everything else that is needed to generate the default
	  configuration for the selected architecture and platform.
	  The only requirement is that the tools needed for that
	  architecture, for example
	  <COMMAND>powerpc-eabi-g++</COMMAND>,
	  are available using the standard search path. If this is not
	  the case then the <COMMAND>make</COMMAND> will
	  fail with an error message. If you have a multiprocessor
	  system then it may be more efficient to use:</PARA>
<SCREEN>$ make -j <REPLACEABLE>n</REPLACEABLE></SCREEN>
<PARA>where <REPLACEABLE>n</REPLACEABLE> is equal to the
	  number of processors on your system.</PARA>
<PARA>Once the <COMMAND>make</COMMAND> process
	  has completed, the install tree will contain the header
	  files and the target library that are needed for application
	  development. </PARA>
<PARA>It is also possible to build the system&rsquo;s test cases
for the current configuration:</PARA>
<SCREEN>$ make tests</SCREEN>
<PARA>The resulting test executables will end up in a
	  <FILENAME>tests</FILENAME> subdirectory of the
	  <!-- <index></index> -->install tree. </PARA>
<PARA>If disk space is scarce then it is possible to make the copy
of the install tree for application development purposes, and then
use: </PARA>
<SCREEN>$ make clean</SCREEN>
<PARA>The build tree will now use up a minimum of disk space &mdash; the
bulk of what is left consists of configuration header files that
you may have edited and hence should not be deleted automatically.
However, it is possible to rebuild the system at any time without
re-invoking <COMMAND>ecosconfig</COMMAND>, just by
running <COMMAND>make</COMMAND> again. </PARA>
<PARA>Under exceptional circumstances it may be necessary to run <COMMAND>make
clean</COMMAND> for other reasons, such as when a new release
of the toolchain is installed. The toolchain includes a number of
header files which are closely tied to the compiler, for example <filename>limits.h</filename>,
and these header files are not and should not be duplicated by <productname>eCos</productname>.
The makefiles perform header file dependency analysis, so that when
a header file is changed all affected sources will be rebuilt during
the next <COMMAND>make</COMMAND>. This is very useful
when the configuration header files are changed, but it also means
that a build tree containing information about the locations of
header files must be rebuilt. If a new version of the toolchain
is installed and the old version is removed then this location information
is no longer accurate, and <COMMAND>make</COMMAND> will
complain that certain dependencies cannot be satisfied. Under such circumstances
it is necessary to do a <COMMAND>make clean</COMMAND> first. </PARA>
</SECT1>
<SECT1 id="ecos-packages">
<TITLE>Packages</TITLE>
<PARA><productname>eCos</productname> is a component architecture. The system comes as a
	  number of <!-- <index></index> -->packages which can be
	  enabled or disabled as required, and new packages can be
	  added as they become available. Unfortunately, the packages
	  are not completely independent: for example the &micro;ITRON
	  compatibility package relies almost entirely on
	  functionality provided by the kernel package, and it would
	  not make sense to try to build &micro;ITRON if the kernel
	  was disabled. The C library has fewer dependencies: some
	  parts of the C library rely on kernel functionality, but it
	  is possible to disable these parts and thus build a system
	  that has the C library but no kernel. The
	<command>ecosconfig</command> tool has the capability of
	    checking that all the dependencies are satisfied, but it
	    may still be possible to produce configurations that will
	    not build or (conceivably) that will build but not run.
	    Developers should be aware of this and take appropriate
	    care.</PARA>
<PARA>By default, <!-- <index></index> --><command>ecosconfig</command> will
include all packages that are appropriate for the specified hardware
in the configuration. The common <!-- <index></index> -->HAL package and
the <productname>eCos</productname> infrastructure must be present in every configuration. In
addition, it is always necessary to have one architectural HAL package
and one platform HAL package. Other packages are optional, and can
be added or removed from a configuration as required.</PARA>
<PARA>The application may not require all of the packages; for example,
it might not need the &micro;ITRON compatibility
package, or the floating point support provided by the math library.
There is a slight overhead when <productname>eCos</productname> is built because the packages
will get compiled, and there is also a small disk space penalty.
However, any unused facilities will get stripped out at link-time,
so having redundant packages will not affect the final executable. </PARA>
</SECT1>
<SECT1 id="coarse-grained-configuration">
<TITLE>Coarse-grained Configuration</TITLE>
<PARA>Coarse-grained <!-- <index></index> -->configuration of
	  an <productname>eCos</productname> system means making configuration changes using the
	  <COMMAND>ecosconfig</COMMAND> tool. These changes
	  include: </PARA>
<ORDEREDLIST>
<LISTITEM>
<PARA>switching to different target hardware</PARA>
</LISTITEM>
<LISTITEM>
<PARA>switching to a different template</PARA>
</LISTITEM>
<LISTITEM>
<PARA>adding or removing a package</PARA>
</LISTITEM>
<LISTITEM>
<PARA>changing the version of a package</PARA>
</LISTITEM>
</ORDEREDLIST>
<PARA>Whenever <COMMAND>ecosconfig</COMMAND> generates or
	  updates an <productname>eCos</productname> configuration, it generates a configuration
	  save file.</PARA>
<PARA>Suppose that the configuration was first created using
	  the following command line: </PARA>
<SCREEN>$ ecosconfig new stdeval1</SCREEN>
<PARA>To change the target hardware to the Cogent CMA28x
	  PowerPC board, the following command would be needed:
	</PARA>
<SCREEN>$ ecosconfig target cma28x</SCREEN>
<PARA>To switch to the PowerPC simulator instead: </PARA>
<SCREEN>$ ecosconfig target psim</SCREEN>
<PARA>As the hardware changes, hardware-related packages such as
the HAL packages and device drivers will be added to and removed
from the configuration as appropriate. </PARA>
<PARA>To remove any package from the current configuration, use
the <COMMAND>remove</COMMAND> command: </PARA>
<SCREEN>$ ecosconfig remove uitron</SCREEN>
<PARA>You can disable multiple packages using multiple arguments,
for example: </PARA>
<SCREEN>$ ecosconfig remove uitron libm</SCREEN>
<PARA>If this turns out to have been a mistake then you can
	  re-enable one or more packages with the
	  <COMMAND>add</COMMAND> command: </PARA>
<SCREEN>$ ecosconfig add libm</SCREEN>
<PARA>Changing the desired version for a package is also
	  straightforward:</PARA>
<SCREEN>$ ecosconfig version v2_1 kernel</SCREEN>
<PARA>It is necessary to regenerate the build tree and header
	  files following any changes to the configuration before
	  rebuilding <productname>eCos</productname>:</PARA>
<SCREEN>$ ecosconfig tree</SCREEN>
</SECT1>
<SECT1 id="fine-grained-configuration">
<TITLE>Fine-grained Configuration</TITLE>
<PARA><COMMAND>ecosconfig</COMMAND> only provides
	  coarse-grained control over the configuration: the hardware,
	  the template and the packages that should be built. Unlike
	  the Configuration Tool,
	  <COMMAND>ecosconfig</COMMAND> does not provide
	  any facilities for manipulating finer-grained <!--
	  <index></index> -->configuration options such as how many
	  priority levels the scheduler should support. There are
	  hundreds of these options, and manipulating them by means of
	  command line arguments would not be sensible. </PARA>
<PARA>In the current system fine-grained configuration options may
be manipulated by manual editing of the configuration file. When
a file has been edited in this way, the <COMMAND>ecosconfig</COMMAND> tool
should be used to check the configuration for any conflicts which
may have been introduced:</PARA>
<SCREEN>$ ecosconfig check</SCREEN>
<PARA>The <COMMAND>check</COMMAND> command will list
all conflicts and will also rewrite the configuration file, propagating
any changes which affect other options. The user may choose to resolve
the conflicts either by re-editing the configuration file manually
or by invoking the inference engine using the <COMMAND>resolve</COMMAND> command:</PARA>
<SCREEN>$ ecosconfig resolve</SCREEN>
<PARA>The  <COMMAND>resolve</COMMAND> command will
list all conflicts which can be resolved and save the resulting changes
to the configuration.</PARA>
<PARA>It is necessary to regenerate the build tree and header files
following any changes to the configuration before rebuilding <productname>eCos</productname>:</PARA>
<SCREEN>$ ecosconfig tree</SCREEN>
<PARA>All the configuration options and their descriptions are listed
in the <citetitle><productname>eCos</productname> Reference Manual</citetitle>. </PARA>
</SECT1>
<SECT1 id="editing-an-ecos-savefile">
<TITLE>Editing an <productname>eCos</productname> Savefile</TITLE>
<PARA>The <productname>eCos</productname> configuration information is held in a single
	  savefile, typically <FILENAME>ecos.ecc</FILENAME>, which can
	  be generated by either the GUI configuration tool or by the
	  command line <command>ecosconfig</command> tool. The file
	  normally exists at the top level of the build tree. It is a
	  text file, allowing the various configurations options to be
	  edited inside a suitable text editor or by other programs or
	  scripts, as well as in the GUI config tool.</PARA>
<PARA>An <productname>eCos</productname> savefile is actually a script in the <EMPHASIS>Tcl</EMPHASIS> programming
language, so any modifications to the file need to preserve Tcl
syntax. For most configuration options, any modifications will be
trivial and there is no need to worry about Tcl syntax. For example,
changing a 1 to a 0 to disable an option.  For more complicated
options, for example<literal> CYGDAT_UITRON_TASK_EXTERNS</literal>,
which involves some lines of C code, more care has
to be taken. If an edited savefile is no longer a valid Tcl script
then the configuration tools will be unable to read back the data
for further processing, for example to generate a build tree. An
outline of Tcl syntax is given below. One point worth noting here
is that a line that begins with a &ldquo;#&rdquo; is
usually a comment, and the bulk of an <productname>eCos</productname> savefile actually consists
of such comments, to make it easier to edit.</PARA>
<SECT2>
<TITLE>Header</TITLE>
<PARA>An <productname>eCos</productname> savefile begins with a header, which typically
	    looks something like this:</PARA>
<SCREEN># eCos saved configuration
# ---- commands -------------------------------------------------------- 
# This section contains information about the savefile format. 
# It should not be edited. Any modifications made to this section 
# may make it impossible for the configuration tools to read 
# the savefile.

cdl_savefile_version 1; 
cdl_savefile_command cdl_savefile_version {};
cdl_savefile_command cdl_savefile_command {}; 
cdl_savefile_command 
cdl_configuration { description hardware template package }; 
cdl_savefile_command cdl_package { value_source user_value wizard_value inferred_value }; 
cdl_savefile_command cdl_component { value_source user_value wizard_value inferred_value }; 
cdl_savefile_command cdl_option { value_source user_value wizard_value inferred_value }; 
cdl_savefile_command cdl_interface { value_source user_value wizard_value inferred_value }; 
      </SCREEN>
<PARA>This section of the savefile is intended for use by the
	configuration system, and should not be edited. If this
	section is edited then the various configuration tools may no
	longer be able to read in the modified savefile.</PARA>
</SECT2>
<SECT2>
<TITLE>Toplevel Section</TITLE>
<PARA>The header is followed by a section that defines the
	    configuration as a whole. A typical example would
	    be:</PARA>
<SCREEN># ---- toplevel -------------------------------------------------------- 
# This section defines the toplevel configuration object. The only 
# values that can be changed are the name of the configuration and 
# the description field. It is not possible to modify the target, 
# the template or the set of packages simply by editing the lines 
# below because these changes have wide-ranging effects. Instead 
# the appropriate tools should be used to make such modifications.

cdl_configuration eCos {     
description &ldquo;&ldquo; ;         

# These fields should not be modified.     
hardware    pid ;     
template    uitron ;     
package -hardware CYGPKG_HAL_ARM current ;     
package -hardware CYGPKG_HAL_ARM_PID current ;     
package -hardware CYGPKG_IO_SERIAL current ;     
package -template CYGPKG_HAL current ;     
package -template CYGPKG_IO current ;     
package -template CYGPKG_INFRA current ;     
package -template CYGPKG_KERNEL current ;     
package -template CYGPKG_UITRON current ;     
package -template CYGPKG_LIBC current ;     
package -template CYGPKG_LIBM current ;     
package -template CYGPKG_DEVICES_WALLCLOCK current ;     
package -template CYGPKG_ERROR current ; 
}; 
      </SCREEN>
<PARA>This section allows the configuration tools to reload the
various packages that make up the configuration. Most of the information
should not be edited. If it is necessary to add a new package or
to remove an existing one then the appropriate tools should be used
for this, for example:</PARA>
<PROGRAMLISTING>$ ecosconfig remove CYGPKG_LIBM</PROGRAMLISTING>
<PARA>There are two fields which can be edited. Configurations have
a name; in this case <productname>eCos</productname>. They can also have a description, which
is some arbitrary text. The configuration tools do not make use
of these fields, they exist so that users can store additional information
about a configuration.</PARA>
</SECT2>
<SECT2>
<TITLE>Conflicts Section</TITLE>
<PARA>The toplevel section is followed by details of all the
	    conflicts (if any) in the configuration, for
	    example:</PARA>
<SCREEN># ---- conflicts ------------------------------------------------------- 
# There are 2 conflicts. 
# 
# option CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET 
#   Property LegalValues 
#   Illegal current value 100000 
#   Legal values are: -90000 to 90000 
# 
# option CYGSEM_LIBC_TIME_CLOCK_WORKING 
#   Property Requires 
#   Requires constraint not satisfied: CYGFUN_KERNEL_THREADS_TIMER 
	  </SCREEN>
<PARA>When editing a configuration you may end up with something
that is invalid. Any problems in the configuration will be reported
in the conflicts section. In this case there are two conflicts.
The option <literal>CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET</literal> has
been given an illegal value: typically this would be fixed by searching
for the definition of that option later on in the savefile and modifying
the value. The second conflict is more interesting, an unsatisfied <EMPHASIS>requires</EMPHASIS> constraint.
Configuration options are not independent: disabling some functionality
in, say, the kernel, can have an impact elsewhere; in this case
the C library. The various dependencies between the options are
specified by the component developers and checked by the configuration
system. In this case there are two obvious ways in which the conflict could
be resolved: re-enabling <literal>CYGFUN_KERNEL_THREADS_TIMER</literal>,
or disabling <literal>CYGSEM_LIBC_TIME_CLOCK_WORKING</literal>.
Both of these options will be listed later on in the file.</PARA>
<PARA>Some care has to be taken when modifying configuration options,
to avoid introducing new conflict. For instance it is possible that
there might be other options in the system which have a dependency
on <literal>CYGSEM_LIBC_TIME_CLOCK_WORKING</literal>,
so disabling that option may not be the best way to resolve the
conflict. Details of all such dependencies are provided in the appropriate
places in the savefile.</PARA>
<PARA>It is not absolutely required that a configuration be conflict-free
before generating a build tree and building <productname>eCos</productname>. It is up to the
developers of each component to decide what would happen if an attempt
is made to build <productname>eCos</productname> while there are still conflicts. In serious
cases there is likely to be a compile-time failure, or possibly
a link-time failure. In less serious cases the system may build
happily and the application can be linked with the resulting library,
but the component may not quite function as intended - although
it may still be good enough for the specific needs of the application.
It is also possible that everything builds and links, but once in
a while the system will unaccountably crash. Using a configuration
that still has conflicts is done entirely at the user&rsquo;s
risk.</PARA>
</SECT2>
<SECT2>
<TITLE>Data Section</TITLE>
<PARA>The bulk of the savefile lists the various packages,
	    components, and options, including their values and the
	    various dependencies. A number of global options come
	    first, especially those related to the build process such
	    as compiler flags. These are followed by the various
	    packages, and the components and options within those
	    packages, in order.</PARA>
<PARA>Packages, components and options are organized in a
	    hierarchy. If a particular component is disabled then all
	    options and sub-components below it will be inactive: any
	    changes made to these will have no effect. The savefile
	    contains information about the hierarchy in the form of
	    comments, for example:</PARA>
<SCREEN>cdl_package CYGPKG_KERNEL ... 
# &gt; 
cdl_component CYGPKG_KERNEL_EXCEPTIONS ... 
# &gt; 
cdl_option CYGSEM_KERNEL_EXCEPTIONS_DECODE ... 
cdl_option CYGSEM_KERNEL_EXCEPTIONS_GLOBAL ... 
# &lt; 
cdl_component CYGPKG_KERNEL_SCHED ... 
# &gt; 
cdl_option CYGSEM_KERNEL_SCHED_MLQUEUE ... 
cdl_option CYGSEM_KERNEL_SCHED_BITMAP ... 
# &lt; 
# &lt; 
	  </SCREEN>
<PARA>This corresponds to the following hierarchy:</PARA>
<SCREEN> CYGPKG_KERNEL
   CYGPKG_KERNEL_EXCEPTIONS
     CYGSEM_KERNEL_EXCEPTIONS_DECODE
     CYGSEM_KERNEL_EXCEPTIONS_GLOBAL
   CYGPKG_KERNEL_SCHED
     CYGSEM_KERNEL_SCHED_MLQUEUE
     CYGSEM_KERNEL_SCHED_BITMAP 
	  </SCREEN>
<PARA>Providing the hierarchy information in this way allows
	    programs or scripts to analyze the savefile and readily
	    determine the hierarchy. It could also be used by a
	    sufficiently powerful editor to support structured editing
	    of <productname>eCos</productname> savefiles. The information is not used by the
	    configuration tools themselves since they obtain the
	    hierarchy from the original CDL scripts.</PARA>
<PARA>Each configurable entity is preceded by a comment, of
	    the following form:</PARA>
<SCREEN># Kernel schedulers 
# doc: ref/ecos-ref/ecos-kernel-overview.html#THE-SCHEDULER 
# The eCos kernel provides a choice of schedulers. In addition 
# there are a number of configuration options to control the 
# detailed behaviour of these schedulers. 
cdl_component CYGPKG_KERNEL_SCHED {     
... 
}; 
	  </SCREEN>
<PARA>This provides a short textual alias
	    <literal>Kernel schedulers</literal> for the
	    component. If online documentation is available for the
	    configurable entity then this will come next. Finally
	    there is a short description of the entity as a whole. All
	    this information is provided by the component
	    developers.</PARA>
<PARA>Each configurable entity takes the form:</PARA>
<SCREEN>&lt;type&gt; &lt;name&gt; {
     &lt;data&gt;
};</SCREEN>
<PARA>Configurable entities may not be active. This can be either
because the parent is disabled or inactive, or because there are
one or more <EMPHASIS>active_if</EMPHASIS> properties. Modifying
the value of an inactive entity has no effect on the configuration,
so this information is provided first:</PARA>
<PARA></PARA>
<SCREEN>cdl_option CYGSEM_KERNEL_EXCEPTIONS_DECODE {     
# This option is not active     
# The parent CYGPKG_KERNEL_EXCEPTIONS is disabled     
... 
};
 
...

cdl_option CYGIMP_IDLE_THREAD_YIELD {     
# This option is not active     
# ActiveIf constraint: (CYGNUM_KERNEL_SCHED_PRIORITIES == 1)     
#     CYGNUM_KERNEL_SCHED_PRIORITIES == 32     
#   --&gt; 0     
... 
}; 

</SCREEN>
<PARA>For <literal>CYGIMP_IDLE_THREAD_YIELD</literal> the
savefile lists the expression that must be satisfied if the option
is to be active, followed by the current value of all entities that
are referenced in the expression, and finally the result of evaluating
that expression.</PARA>
<PARA>Not all options are directly modifiable in the savefile. First,
the value of packages (which is the version of that package loaded
into the configuration) cannot be modified here.</PARA>
<SCREEN>

cdl_package CYGPKG_KERNEL {     
# Packages cannot be added or removed, nor can their version be changed,     
# simply by editing their value. Instead the appropriate configuration     
# should be used to perform these actions.
...
};

</SCREEN>
<PARA>The version of a package can be changed using e.g.:    </PARA>
<SCREEN>$ ecosconfig version 1.3 CYGPKG_KERNEL</SCREEN>
<PARA>Even though a package&rsquo;s value cannot be modified
here, it is still important for the savefile to contain the details.
In particular packages may impose constraints on other configurable
entities and may be referenced by other configurable entities. Also
it would be difficult to understand or extract the configuration&rsquo;s
hierarchy if the packages were not listed in the appropriate places
in the savefile.</PARA>
<PARA>Some components (or, conceivably, options) do not have any
associated data. Typically they serve only to introduce another
level in the hierarchy, which can be useful in the context of the
GUI configuration tool.</PARA>
<SCREEN>

cdl_component CYGPKG_HAL_COMMON_INTERRUPTS {     
# There is no associated value. 
}; 

</SCREEN>
<PARA>Other components or options have a calculated value. These
are not user-modifiable, but typically the value will depend on
other options which can be modified. Such calculated options can
be useful when controlling what gets built or what ends up in the
generated configuration header files. A calculated value may also
effect other parts of the configuration, for instance, via a <EMPHASIS>requires</EMPHASIS> constraint.</PARA>
<SCREEN>

cdl_option BUFSIZ {     
# Calculated value: CYGSEM_LIBC_STDIO_WANT_BUFFERED_IO ? CYGNUM_LIBC_STDIO_BUFSIZE : 0     
#     CYGSEM_LIBC_STDIO_WANT_BUFFERED_IO == 1     
#     CYGNUM_LIBC_STDIO_BUFSIZE == 256     
# Current_value: 256 
}; 

</SCREEN>
<PARA>A special type of calculated value is the <EMPHASIS>interface</EMPHASIS>.
The value of an interface is the number of active and enabled options
which <EMPHASIS>implement</EMPHASIS> that interface. Again the value
of an interface cannot be modified directly; only by modifying the
options which implement the interface. However, an interface can
be referenced by other parts of the configuration. </PARA>
<SCREEN>cdl_interface CYGINT_KERNEL_SCHEDULER {     
# Implemented by CYGSEM_KERNEL_SCHED_MLQUEUE, active, enabled     
# Implemented by CYGSEM_KERNEL_SCHED_BITMAP, active, disabled     
# This value cannot be modified here.     
# Current_value: 1     
# Requires: 1 == CYGINT_KERNEL_SCHEDULER     
#     CYGINT_KERNEL_SCHEDULER == 1     
#   --&gt; 1

</SCREEN>
<SCREEN># The following properties are affected by this value     
# interface CYGINT_KERNEL_SCHEDULER     
#     Requires: 1 == CYGINT_KERNEL_SCHEDULER 
}; </SCREEN>
<PARA>If the configurable entity is modifiable then there will be
lines like the following:</PARA>
<SCREEN> 
cdl_option CYGSEM_KERNEL_SCHED_MLQUEUE {     
...     
# Flavor: bool     
# No user value, uncomment the following line to provide one.     
# user_value 1     
# value_source default     
# Default value: 1     
... 
}; 

</SCREEN>
<PARA>Configurable entities can have one of four different flavors:
none, bool, data and booldata. Flavor none indicates that there
is no data associated with the entity, typically it just acts as
a placeholder in the overall hierarchy. Flavor bool is the most
common, it is a simple yes-or-no choice. Flavor data is for more
complicated configuration choices, for instance the size of an array
or the name of a device. Flavor booldata is a combination of bool
and data: the option can be enabled or disabled, and there is some
additional data associated with the option as well.</PARA>
<PARA>In the above example the user has not modified this particular
option, as indicated by the comment and by the commented-out <literal>user_value</literal> line.
To disable this option the file should be edited to:</PARA>
<SCREEN>

cdl_option CYGSEM_KERNEL_SCHED_MLQUEUE {     
...     
# Flavor: bool     
# No user value, uncomment the following line to provide one.     
user_value 0     
# value_source default     
# Default value: 1     
... 
} 

</SCREEN>
<PARA>The comment preceding the <literal>user_value
0</literal> line can be removed if desired, otherwise it
will be removed automatically the next time the file is read and
updated by the configuration tools.</PARA>
<PARA>Much the same process should be used for options with the
data flavor, for example:</PARA>
<SCREEN> 
cdl_option CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET {     
# Flavor: data     
# No user value, uncomment the following line to provide one.     
# user_value 3600     
# value_source default     
# Default value: 3600     
# Legal values: -90000 to 90000 
}; 

</SCREEN>
<PARA>can be changed to:</PARA>
<SCREEN>

cdl_option CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET {     
# Flavor: data     
user_value 7200     
# value_source default     
# Default value: 3600     
# Legal values: -90000 to 90000 }; 

</SCREEN>
<PARA>Note that the original text provides the default value in
the <literal>user_value</literal> comment,
on the assumption that the desired new value is likely to be similar
to the default value. The <literal>value_source</literal> comment
does not need to be updated, it will be fixed up if the savefile
is fed back into the configuration system and regenerated.</PARA>
<PARA>For options with the booldata flavor, the <literal>user_value</literal> line
needs take two arguments. The first argument is for the boolean
part, the second for the data part. For example:</PARA>
<SCREEN> 
cdl_component CYGNUM_LIBM_COMPATIBILITY {     
# Flavor: booldata     
# No user value, uncomment the following line to provide one.    
# user_value 1 POSIX     
# value_source default     
# Default value: 1 POSIX     
# Legal values:  &ldquo;POSIX&rdquo; &ldquo;IEEE&rdquo; &ldquo;XOPEN&rdquo; &ldquo;SVID&rdquo;     
... 
}; 

</SCREEN>
<PARA>could be changed to:</PARA>
<SCREEN> 
cdl_component CYGNUM_LIBM_COMPATIBILITY {     
# Flavor: booldata     
user_value 1 IEEE     
# value_source default     
# Default value: 1 POSIX     
# Legal values:  &ldquo;POSIX&rdquo; &ldquo;IEEE&rdquo; &ldquo;XOPEN&rdquo; &ldquo;SVID&rdquo;     
... 
}; 

</SCREEN>
<PARA>or alternatively, if the whole component should be disabled,
to:</PARA>
<SCREEN> 
cdl_component CYGNUM_LIBM_COMPATIBILITY {     
# Flavor: booldata     
user_value 0 POSIX     
# value_source default     
# Default value: 1 POSIX     
# Legal values:  &ldquo;POSIX&rdquo; &ldquo;IEEE&rdquo; &ldquo;XOPEN&rdquo; &ldquo;SVID&rdquo;     
... 
}; 

</SCREEN>
<PARA>Some options take values that span multiple lines. An example
would be:</PARA>
<SCREEN>

cdl_option CYGDAT_UITRON_MEMPOOLVAR_INITIALIZERS {     
# Flavor: data     
# No user value, uncomment the following line to provide one.     
# user_value \     
# &ldquo;CYG_UIT_MEMPOOLVAR( vpool1, 2000 ), \\     
#  CYG_UIT_MEMPOOLVAR( vpool2, 2000 ), \\     
#  CYG_UIT_MEMPOOLVAR( vpool3, 2000 ),&rdquo;     
# value_source default     
# Default value: \     
#     &ldquo;CYG_UIT_MEMPOOLVAR( vpool1, 2000 ), \\     
#      CYG_UIT_MEMPOOLVAR( vpool2, 2000 ), \\     
#      CYG_UIT_MEMPOOLVAR( vpool3, 2000 ),&rdquo; 
}; 

</SCREEN>
<PARA>Setting a user value for this option involves uncommenting
and modifying all relevant lines, for example:</PARA>
<SCREEN>

cdl_option CYGDAT_UITRON_MEMPOOLVAR_INITIALIZERS {     
# Flavor: data     
user_value \     
&ldquo;CYG_UIT_MEMPOOLVAR( vpool1, 4000 ), \\      
CYG_UIT_MEMPOOLVAR( vpool2, 4000 ),&rdquo;     
# value_source default     
# Default value: \     
#     &ldquo;CYG_UIT_MEMPOOLVAR( vpool1, 2000 ), \\     
#      CYG_UIT_MEMPOOLVAR( vpool2, 2000 ), \\     
#      CYG_UIT_MEMPOOLVAR( vpool3, 2000 ),&rdquo; 
}; 

</SCREEN>
<PARA>In such cases appropriate care has to be taken to preserve
Tcl syntax, as discussed below.</PARA>
<PARA>The configuration system has the ability to keep track of
	  several different values for any given option. All options
	  start off with a default value, in other words their value
	  source is set to <literal>default</literal>. If a
	  configuration involves conflicts and the configuration
	  system&rsquo;s inference engine is allowed to resolve these
	  automatically then it may provide an
	  <literal>inferred</literal> value instead, for
	  example:</PARA>
<SCREEN>

cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT {     
# Flavor: bool     
# No user value, uncomment the following line to provide one.     
# user_value 1     
# The inferred value should not be edited directly.     
inferred_value 0     
# value_source inferred     
# Default value: 1     
... 
}; 

</SCREEN>
<PARA>Inferred values are calculated by the configuration system
and should not be edited by the user. If the inferred value is not
correct then a user value should be substituted instead:</PARA>
<SCREEN>

cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT {     
# Flavor: bool     
user_value 1     
# The inferred value should not be edited directly.     
inferred_value 0     
# value_source inferred     
# Default value: 1     
... 
}; </SCREEN>
<PARA>The inference engine will not override a user value with an
inferred one. Making a change like this may well re-introduce a
conflict, since the inferred value was only calculated to resolve
a conflict. Another run of the inference engine may find a different
and more acceptable way of resolving the conflict, but this is not guaranteed
and it may be up to the user to examine the various dependencies
and work out an acceptable solution.</PARA>
<PARA>Inferred values are listed in the savefile because the exact
inferred value may depend on the order in which changes were made
and conflicts were resolved. If the inferred values were absent
then it is possible that reloading a savefile would not exactly
restore the configuration. Default values on the other hand are
entirely deterministic so there is no actual need for the values
to be listed in the savefile. However, the default value can be
very useful information so it is provided in a comment.</PARA>
<PARA>Occasionally the user will want to do some experimentation,
and temporarily switch an option from a user value back to a default
or inferred one to see what the effect would be. This could be achieved
by simply commenting out the user value. For instance, if the current
savefile contains:</PARA>
<SCREEN> 
cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT {     
# Flavor: bool     
user_value 1     
# The inferred value should not be edited directly.     
inferred_value 0     
# value_source user     
# Default value: 1     
... 
}; 

</SCREEN>
<PARA>then the inferred value could be restored by commenting out
or removing the <literal>user_value</literal> line:</PARA>
<SCREEN> 
cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT {     
# Flavor: bool     
# user_value 1     
# The inferred value should not be edited directly.     
inferred_value 0     
# value_source user     
# Default value: 1     
... 
}; 

</SCREEN>
<PARA>This is fine for simple values. However if the value is complicated
then there is a problem: commenting out the <LITERAL>user_value</LITERAL> line
or lines means that the user value becomes invisible to the configuration system,
so if the savefile is loaded and then regenerated the information
will be lost. An alternative approach is to keep the <LITERAL>user_value</LITERAL> but
explicitly set the <LITERAL>value_source</LITERAL> line,
for example:</PARA>
<SCREEN>

cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT {     
# Flavor: bool     
user_value 1     
# The inferred value should not be edited directly.     
inferred_value 0     
value_source inferred     
# Default value: 1     
... 
}; 

</SCREEN>
<PARA>In this case the configuration system will use the inferred
value for the purposes of dependency analysis etc., even though
a user value is present. To restore the user value the <LITERAL>value_source</LITERAL> line
can be commented out again. If there is no explicit <LITERAL>value_source</LITERAL> then
the configuration system will just use the highest priority one:
the user value if it exists; otherwise the inferred value if it
exists; otherwise the default value which always exists.</PARA>
<PARA>The default value for an option can be a simple constant,
or it can be an expression involving other options. In the latter
case the expression will be listed, together with the values for
all options referenced in the expression and the current result
of evaluating that expression. This is for informational purposes
only, the default value is always recalculated deterministically
when loading in a savefile.</PARA>
<SCREEN>

cdl_option CYGBLD_GLOBAL_COMMAND_PREFIX {     
# Flavor: data     
# No user value, uncomment the following line to provide one.     
# user_value arm-elf     
# value_source default     
# Default value:  CYGHWR_THUMB ? &ldquo;thumb-elf&rdquo; : &ldquo;arm-elf&rdquo;     
#     CYGHWR_THUMB == 0     
#   --&gt; arm-elf 
}; 

</SCREEN>
<PARA>For options with the data or booldata flavor, there are likely
to be constraints on the possible values. If the value is supposed
to be a number in a given range and a user value of &ldquo;<LITERAL>hello
world</LITERAL>&rdquo; is provided instead then there
are likely to be compile-time failures. Component developers can
specify constraints on the legal values, and these will be listed
in the savefile.</PARA>
<SCREEN> 
cdl_option X_TLOSS {     
# Flavor: data     
# No user value, uncomment the following line to provide one.     
# user_value 1.41484755040569E+16     
# value_source default     
# Default value: 1.41484755040569E+16     
# Legal values: 1 to 1e308 
};

</SCREEN>
<SCREEN>cdl_component CYGNUM_LIBM_COMPATIBILITY {     
# Flavor: booldata     
# No user value, uncomment the following line to provide one.     
# user_value 1 POSIX     
# value_source default     
# Default value: 1 POSIX     
# Legal values:  &ldquo;POSIX&rdquo; &ldquo;IEEE&rdquo; &ldquo;XOPEN&rdquo; &ldquo;SVID&rdquo;     
... 
};

</SCREEN>
<PARA>In some cases the legal values list may be an expression involving
other options. If so then the current values of the referenced options
will be listed, together with the result of evaluating the list
expression, just as for default value expressions.</PARA>
<PARA>If an illegal value is provided then this will result in a
conflict, listed in the conflicts section of the savefile. For more
complicated options a simple legal values list is not sufficient
to allow the current value to be validated, and the configuration
system will be unable to flag conflicts. This issue will be addressed in
future releases of the configuration system.</PARA>
<PARA>Following the value-related fields for a given option, any <EMPHASIS>requires</EMPHASIS> constraints belonging
to this option will be listed. These constraints are only effective
if the option is active and, for bool and booldata flavors, enabled.
If some aspect of <productname>eCos</productname> functionality is inactive or disabled then
it cannot impose any constraints on the rest of the system. As usual,
the full expression will be listed followed by the current values
of all options that are referenced and the result of evaluating
the expression:</PARA>
<SCREEN>

cdl_option CYGSEM_LIBC_TIME_TIME_WORKING {     
...     
# Requires: CYGPKG_DEVICES_WALLCLOCK     
#     CYGPKG_DEVICES_WALLCLOCK == current     
#   --&gt; 1 
};

</SCREEN>
<PARA>When modifying the value of an option it is useful to know
not only what constraints the option imposes on the rest of the
system but also what other options in the system depend in some
way on this one. The savefile provides this information:</PARA>
<SCREEN>cdl_option CYGFUN_KERNEL_THREADS_TIMER {     
...     
# The following properties are affected by this value     
# option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT     
#     Requires: CYGFUN_KERNEL_THREADS_TIMER     
# option CYGIMP_UITRON_STRICT_CONFORMANCE     
#     Requires: CYGFUN_KERNEL_THREADS_TIMER     
# option CYGSEM_LIBC_TIME_CLOCK_WORKING     
#     Requires: CYGFUN_KERNEL_THREADS_TIMER 
}; 

</SCREEN>
</SECT2>
<SECT2>
<TITLE>Tcl Syntax</TITLE>
<PARA><productname>eCos</productname> savefiles are implemented as Tcl scripts, and are read
in by running the data through a standard Tcl interpreter that has
been extended with a small number of additional commands such as <LITERAL>cdl_option</LITERAL> and <LITERAL>cdl_configuration</LITERAL>.
In many cases this is an implementation detail that can be safely
ignored while editing a savefile: simply replacing a <LITERAL>1</LITERAL> with
a <LITERAL>0</LITERAL> to disable some functionality
is not going to affect whether or not the savefile is still a valid
Tcl script and can be processed by a Tcl interpreter. However, there
are more complicated cases where an understanding of Tcl syntax
is at least desirable, for example:</PARA>
<SCREEN>

cdl_option CYGDAT_UITRON_MEMPOOLVAR_EXTERNS {
     # Flavor: data
     user_value \
      &ldquo;static char vpool1\[ 2000 \], \\
      vpool2\[ 2000 \], \\
       vpool3\[ 2000 \];&rdquo;     
# value_source default     
# Default value: \
     #     &ldquo;static char vpool1\[ 2000 \], \\
     #      vpool2\[ 2000 \], \\
    #      vpool3\[ 2000 \];&rdquo; 
};

</SCREEN>
<PARA>The backslash at the end of the <LITERAL>user_value</LITERAL> line
is processed by the Tcl interpreter as a line continuation character.
The quote marks around the user data are also interpreted by the
Tcl interpreter and serve to turn the entire data field into a single
argument. The backslashes preceding the opening and closing square
brackets prevent the Tcl interpreter from treating these characters
specially, otherwise there would be an attempt at <EMPHASIS>command
substitution</EMPHASIS> as described below. The double backslashes
at the end of each line of the data will be turned into a single
backslash by the Tcl interpreter, rather than escaping the newline
character, so that the actual data seen by the configuration system
is:</PARA>
<SCREEN>

static char vpool1[ 2000 ], \
      vpool2[ 2000 ], \
      vpool3[ 2000 ];

</SCREEN>
<PARA>This is of course the data that should end up in the &micro;ITRON
configuration header file. The opening and closing braces surrounding
the entire body of the option data are also significant and cause
this body to be passed as a single argument to the <command>cdl_option</command> command.
The closing semicolon is optional in this example, but provides
a small amount of additional robustness if the savefile is edited
such that it is no longer a valid Tcl script. If the data contained
any <LITERAL>$</LITERAL> characters then
these would have to be treated specially as well, via a backslash escape.</PARA>
<PARA>In spite of what all the above might seem to suggest, Tcl
is actually a very simple yet powerful scripting language: the syntax
is defined by just eleven rules. On occasion this simplicity means
that Tcl&rsquo;s behaviour is subtly different from other languages,
which can confuse newcomers.</PARA>
<PARA>When the Tcl interpreter is passed some data such as <LITERAL>puts
Hello</LITERAL>, it splits this data into a command and its
arguments. The command will be terminated by a newline or by a semicolon,
unless one of the quoting mechanisms is used. The command and each
of its arguments are separated by white space. So in the following
example:</PARA>
<SCREEN>puts Hello 
set x 42 </SCREEN>
<PARA>will result in two separate commands being executed. The first
command is <LITERAL>puts</LITERAL> and is passed a
single argument, <LITERAL>Hello</LITERAL>. The second
command is <LITERAL>set</LITERAL> and is passed two
arguments, <LITERAL>x</LITERAL> and <LITERAL>42</LITERAL>.
The intervening newline character serves to terminate the first
command, and a semi-colon separator could be used instead: </PARA>
<programlisting>puts Hello;set x 42</programlisting>
<PARA>Any white space surrounding the semicolon is just ignored
because it does not serve to separate arguments.</PARA>
<PARA>Now consider the following:</PARA>
<SCREEN>set x Hello world</SCREEN>
<PARA>This is not valid Tcl. It is an attempt to invoke the <LITERAL>set</LITERAL> command
with three arguments: <LITERAL>x</LITERAL>, <LITERAL>Hello</LITERAL>,
and <LITERAL>world</LITERAL>. The <LITERAL>set</LITERAL> only
takes two arguments, a variable name and a value, so it is necessary
to combine the data into a single argument by quoting:</PARA>
<PROGRAMLISTING>set x &ldquo;Hello world&rdquo;</PROGRAMLISTING>
<PARA>When the Tcl interpreter encounters the first quote character
it treats all subsequent data up to but not including the closing
quote as part of the current argument. The quote marks are removed
by the interpreter, so the second argument passed to the <LITERAL>set</LITERAL> command
is just <LITERAL>Hello world</LITERAL> without the
quote characters. This can be significant in the context of <productname>eCos</productname> savefiles.
For instance, consider the following configuration option:</PARA>
<SCREEN>

cdl_option CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE {     
# Flavor: data     
# No user value, uncomment the following line to provide one.     
# user_value &ldquo;\&rdquo;/dev/ttydiag\&rdquo;&rdquo;     
# value_source default     
# Default value: &ldquo;\&rdquo;/dev/ttydiag\&rdquo;&rdquo; 
}; 

</SCREEN>
<PARA>The desired value of the configuration option should be a
valid C string, complete with quote characters. If the savefile
was edited to: </PARA>
<SCREEN>

cdl_option CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE {     
# Flavor: data     
user_value &ldquo;/dev/ttydiag&rdquo;     
# value_source default     
# Default value: &ldquo;\&rdquo;/dev/ttydiag\&rdquo;&rdquo; 
}; 

</SCREEN>
<PARA>then the Tcl interpreter would remove the quote marks when
the savefile is read back in, so the option&rsquo;s value would
not have any quote marks and would not be a valid C string. The
configuration system is not yet able to perform the required validation
so the following <LITERAL>#define</LITERAL> would
be generated in the configuration header file:</PARA>
<PROGRAMLISTING>#define CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE /dev/ttydiag </PROGRAMLISTING>
<PARA>This is likely to cause a compile-time failure when building
<productname>eCos</productname>.</PARA>
<PARA>A quoted argument continues until the closing quote character
is encountered, which means that it can span multiple lines. This
can also be encountered in <productname>eCos</productname> savefiles, for instance, in the <literal>CYGDAT_UITRON_MEMPOOLVAR_EXTERNS</literal> example
mentioned earlier. Newline or semicolon characters do not terminate
the current command in such cases.</PARA>
<PARA>The Tcl interpreter supports much the same forms of backslash
substitution as other common programming languages. Some backslash
sequences such as <literal>\n</literal> will
be replaced by the appropriate character. The sequence <literal>\\</literal> will
be replaced by a single backslash. A backslash at the very end of
a line will cause that backslash, the newline character, and any
white space at the start of the next line to be replaced by a single
space. Hence the following two Tcl commands are equivalent:</PARA>
<PROGRAMLISTING>puts  &ldquo;Hello\nworld\n&rdquo; 
puts \ 
&ldquo;Hello 
world 
&ldquo;</PROGRAMLISTING>
<PARA>In addition to quote and backslash characters, the Tcl interpreter
treats square brackets, the <literal>$</literal> character,
and braces specially. Square brackets are used for command substitution,
for example:</PARA>
<PROGRAMLISTING>puts &ldquo;The answer is [expr 6 * 9]&rdquo;</PROGRAMLISTING>
<PARA>When the Tcl interpreter encounters the square brackets it
will treat the contents as another command that should be executed
first, and the result of executing that is used when continuing
to process the script. In this case the Tcl interpreter will execute
the command <literal>expr 6 * 9</literal>,
yielding a result of 54, and then the Tcl interpreter will execute
<literal>puts &ldquo;The answer is 54&rdquo;</literal>. It should be noted that
the interpreter contains only one level of substitution: if the
result of performing command substitution performs further special
characters such as square brackets then these will not be treated
specially.</PARA>
<PARA>Command line substitution is very unlikely to prove useful
in the context of an <productname>eCos</productname> savefile, but it is part of the Tcl language
and hence cannot be easily suppressed while reading in a savefile.
As a result care has to be taken when savefile data involves square
brackets. Consider the following:</PARA>
<PROGRAMLISTING>

cdl_option CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS {
     ...
     user_value \ 
&ldquo;static char fpool1[ 2000 ], 
fpool2[ 2000 ];&rdquo;
     ... 
};
</PROGRAMLISTING>
<PARA>The Tcl interpreter will interpret the square brackets as
an attempt at command substitution and hence it will attempt to
execute the command <literal>2000</literal> with no
arguments. No such command is defined by the Tcl language or by
the savefile-related extensions provided by the configuration system,
so this will result in an error when an attempt is made to read
back the savefile. Instead it is necessary to backslash-escape the
square brackets and thus suppress command substitution:</PARA>
<PROGRAMLISTING>

cdl_option CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS {
     ...
     user_value \ 
&ldquo;static char fpool1\[ 2000 \], 
fpool2\[ 2000 \];&rdquo;
     ... 
}; </PROGRAMLISTING>
<PARA>Similarly the <literal>$</literal> character
is used in Tcl scripts to perform variable substitution:</PARA>
<PROGRAMLISTING>set x [expr 6 * 9] 
puts &ldquo;The answer is $x&rdquo; </PROGRAMLISTING>
<PARA>Variable substitution, like command substitution, is very
unlikely to prove useful in the context of an <productname>eCos</productname> savefile. Should
it be necessary to have a <literal>$</literal> character
in configuration data then again a backslash escape needs to be
used.</PARA>
<PROGRAMLISTING>cdl_option FOODAT_MONITOR_PROMPT {
     ...
     user_value &ldquo;\$ &ldquo;
     ... 
};</PROGRAMLISTING>
<PARA>Braces are used to collect a sequence of characters into a
single argument, just like quotes. The difference is that variable,
command and backslash substitution do not occur inside braces (with
the sole exception of backslash substitution at the end of a line).
So, for example, the <literal>CYGDAT_UITRON_MEMPOOL_EXTERNFIXED_EXTERNS</literal> value
could be written as:</PARA>
<PROGRAMLISTING>cdl_option CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS {
     ...
     user_value \ 
{static char fpool1[ 2000 ], 
fpool2[ 2000 ];}
     ... 
};</PROGRAMLISTING>
<PARA>The configuration system does not use this when generating
savefiles because for simple edits of a savefile by inexperienced
users the use of brace characters is likely to be a little bit more
confusing than the use of quotes.</PARA>
<PARA>At this stage it is worth noting that the basic format of
each configuration option in the savefile makes use of braces:</PARA>
<PROGRAMLISTING>cdl_option &lt;name&gt; {
     ... 
};</PROGRAMLISTING>
<PARA>The configuration system extends the Tcl language with a small
number of additional commands such as <LITERAL>cdl_option</LITERAL>.
These commands take two arguments, a name and a body, where the
body consists of all the text between the braces. First a check
is made that the specified option is actually present in the configuration.
Then the body is executed in a recursive invocation of the Tcl interpreter,
this time with additional commands such as <LITERAL>user_value</LITERAL> and <LITERAL>value_source</LITERAL>.
If, after editing, the braces are not correctly matched up then
the savefile will no longer be a valid Tcl script and errors will
be reported when the savefile is loaded again.</PARA>
<PARA>Comments in Tcl scripts are introduced by a hash character <LITERAL>#</LITERAL>.
However, a hash character only introduces a comment if it occurs
where a command is expected. Consider the following:</PARA>
<PROGRAMLISTING># This is a comment 
puts &ldquo;Hello&rdquo; # world </PROGRAMLISTING>
<PARA>The first line is a valid comment, since the hash character
occurs right at the start where a command name is expected. The
second line does not contain a comment. Instead it is an attempt
to invoke the <LITERAL>puts</LITERAL> command with
three arguments: <LITERAL>Hello</LITERAL>, <LITERAL>#</LITERAL> and <LITERAL>world</LITERAL>.
These are not valid arguments for the <LITERAL>puts</LITERAL> command
so an error will be raised.</PARA>
<PARA>If the second line was rewritten as:</PARA>
<PROGRAMLISTING>puts &ldquo;Hello&rdquo;; # world</PROGRAMLISTING>
<PARA>then this is a valid Tcl script. The semicolon identifies
the end of the current command, so the hash character occurs at
a point where the next command would start and hence it is interpreted
as the start of a comment.</PARA>
<PARA>This handling of comments can lead to subtle behaviour. Consider
the following:</PARA>
<PROGRAMLISTING>cdl_option WHATEVER {
     # This is a comment }
     user_value 42
     ... 
}</PROGRAMLISTING>
<PARA>Consider the way the Tcl interpreter processes this. The command
name and the first argument do not pose any special difficulties.
The opening brace is interpreted as the start of the next argument,
which continues until a closing brace is encountered. In this case
the closing brace occurs on the second line, so the second argument
passed to <LITERAL>cdl_option</LITERAL> is <literal>\n # This is a comment</LITERAL> . This second argument
is processed in a recursive invocation of the Tcl interpreter and
does not contain any commands, just a comment. Toplevel savefile
processing then resumes, and the next command that is encountered
is <LITERAL>user_value</LITERAL>. Since the
relevant savefile code is not currently processing a configuration
option this is an error. Later on the Tcl interpreter would encounter
a closing brace by itself, which is also an error. Fortunately this
sequence of events is very unlikely to occur when editing generated
savefiles.</PARA>
<PARA>This should be sufficient information about Tcl to allow for
safe editing of <productname>eCos</productname> savefiles. Further information is available
from a wide variety of sources, for example the book <EMPHASIS>Tcl
and the Tk Toolkit </EMPHASIS>by John K Ousterhout.</PARA>
</SECT2>
</SECT1>
<SECT1 id="editing-the-sources">
<TITLE>Editing the Sources</TITLE>
<PARA>For many users, controlling the packages and
	  manipulating the available configuration options will be
	  sufficient to create an embedded operating system that meets
	  the application's requirements. However, since <productname>eCos</productname> is
	  shipped entirely in source form, it is possible to go
	  further when necessary: you can edit the <productname>eCos</productname> <!--
	  <index></index> -->sources themselves. This requires some
	  understanding of the way the <productname>eCos</productname> build system works.
	</PARA>
<PARA>The most obvious place to edit the source code is directly
in the <!-- <index></index> -->component repository. For example, you could
edit the file <filename>kernel/<replaceable>&Version;</replaceable>/src/sync/mutex.cxx</filename>
to change the way kernel mutexes work, or possibly just to add some
extra diagnostics or assertions. Once the file has been edited,
it is possible to invoke <command>make</command> at
the top level of the build tree and the target library will be rebuilt
as required. A small optimization is possible: the build tree is
largely a mirror of the component repository, so it too will contain
a subdirectory <filename>kernel/<replaceable>&Version;</replaceable></filename>;
if make is invoked in this directory
then it will only check for changes to the kernel sources, which
is a bit more efficient than checking for changes throughout the component
repository. </PARA>
<PARA>Editing a file in the component repository is fine if this
tree is used for only one <productname>eCos</productname> configuration. If the repository
is used for several different configurations, however, and especially
if it is shared by multiple users, then making what may be experimental
changes to the master sources would be a bad idea. The build system provides
an alternative. It is possible to make a copy of the file in the
build tree, in other words copy <filename>mutex.cxx</filename> from
the <filename>kernel/<replaceable>&Version;</replaceable>/src/sync</filename> directory
in the component repository to <filename>kernel/<replaceable>&Version;</replaceable>/src/sync</filename> in
the build tree, and edit the file in the build tree. When <command>make</command> is
invoked it will pick up local copies of any of the sources in preference
to the master versions in the component repository. Once you have
finished modifying the <productname>eCos</productname> sources you can install the final version
back in the component repository. If the changes were temporary
in nature and only served to aid the debugging process, then you
can discard the modified version of the sources. </PARA>
<PARA>The situation is slightly more complicated for the header
files that a package may export, such as the C library&rsquo;s <filename>stdio.h</filename> header
file, which can be found in the directory <filename>language/c/libc/<replaceable>&Version;</replaceable>/include</filename>.
If such a header file is changed, either directly in the component
repository or after copying it to the build tree, then <command>make</command> must
be invoked at the top level of the build tree. In cases like this
it is not safe to rebuild just the C library because other packages
may depend on the contents of <filename>stdio.h</filename>. </PARA>
</SECT1>
<SECT1 id="modifying-the-memory-layout">
<TITLE>Modifying the Memory Layout</TITLE>
<PARA>Each <productname>eCos</productname> platform package is supplied with linker script
fragments which describe the location of memory regions on the evaluation
board and the location of memory sections within these regions.
The correct linker script fragment is selected and included in the
<productname>eCos</productname> linker script <!-- <index></index> --><filename>target.ld</filename> when
<productname>eCos</productname> is built.</PARA>
<PARA>It is not necessary to <!-- <index></index> -->modify the default memory
layouts in order to start development with <productname>eCos</productname>. However, it will
be necessary to edit a linker script fragment when the memory map
of the evaluation board is changed. For example, if additional memory
is added, the linker must be notified that the new memory is available
for use. As a minimum, this would involve modifying the length of
the corresponding memory region. Where the available memory is non-contiguous,
it may be necessary to declare a new memory region and reassign
certain linker output sections to the new region.</PARA>
<PARA>Linker script fragments and memory layout header files should
be <!-- <index></index> -->edited within the <productname>eCos</productname> install tree. They are
located at <filename>include/pkgconf/mlt_*.*</filename>.
Where multiple start-up types are in use, it will be necessary to
edit multiple linker script fragments and header files. The information
provided in the header file and the corresponding linker script
fragment must always match. A typical linker script fragment is
shown below:</PARA>
<EXAMPLE><!-- <index></index> -->
<TITLE><productname>eCos</productname> linker script fragment</TITLE>
<PROGRAMLISTING>MEMORY
{
 rom : ORIGIN = 0x40000000, LENGTH = 0x80000
 ram : ORIGIN = 0x48000000, LENGTH = 0x200000
}

SECTIONS
{
 SECTIONS_BEGIN
 SECTION_rom_vectors (rom, 0x40000000, LMA_EQ_VMA)
 SECTION_text (rom, ALIGN (0x1), LMA_EQ_VMA)
 SECTION_fini (rom, ALIGN (0x1), LMA_EQ_VMA)
 SECTION_rodata (rom, ALIGN (0x1), LMA_EQ_VMA)
 SECTION_rodata1 (rom, ALIGN (0x1), LMA_EQ_VMA)
 SECTION_fixup (rom, ALIGN (0x1), LMA_EQ_VMA)
 SECTION_gcc_except_table (rom, ALIGN (0x1), LMA_EQ_VMA)
 SECTION_data (ram, 0x48000000, FOLLOWING (.gcc_except_table))
 SECTION_bss (ram, ALIGN (0x4), LMA_EQ_VMA)
 SECTIONS_END
}</PROGRAMLISTING>
</EXAMPLE>
<PARA>The file consists of two blocks, the <literal>MEMORY</literal> block
contains lines describing the address (<literal>ORIGIN</literal>)
and the size (<literal>LENGTH</literal>) of each memory
region. The <literal>MEMORY</literal> block is followed
by the <literal>SECTIONS</literal> block which contains
lines describing each of the linker output sections. Each section
is represented by a macro call. The arguments of these macros are
ordered as follows: </PARA>
<ORDEREDLIST>
<LISTITEM>
<PARA>The memory region in which the section will finally
	      reside.</PARA>
</LISTITEM>
<LISTITEM>
<PARA>The final address (
<LITERAL>VMA</LITERAL>
) of the section. This is expressed using one of the following forms:</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM><EMPHASIS>n</EMPHASIS></TERM>
<LISTITEM>
<PARA>at the absolute address specified by the
		    unsigned integer <EMPHASIS>n</EMPHASIS></PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>ALIGN (<EMPHASIS>n</EMPHASIS>)</TERM>
<LISTITEM>
<PARA>following the final location of the previous section
		    with alignment to the next <EMPHASIS>n</EMPHASIS>-byte
		    boundary</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</LISTITEM>
<LISTITEM>
<PARA>The initial address (<LITERAL>LMA</LITERAL>)
	      of the section. This is expressed using one of the
	      following forms:</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>LMA_EQ_VMA</TERM>
<LISTITEM>
<PARA>the <LITERAL>LMA</LITERAL>
		    equals the <LITERAL>VMA</LITERAL> (no relocation)</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>AT (<EMPHASIS>n</EMPHASIS>)</TERM>
<LISTITEM>
<PARA>at the absolute address specified by the
		    unsigned integer <EMPHASIS>n</EMPHASIS></PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>FOLLOWING (.<EMPHASIS>name</EMPHASIS>)</TERM>
<LISTITEM>
<PARA>following the initial location of section
		    <EMPHASIS>name</EMPHASIS></PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</LISTITEM>
</ORDEREDLIST>
<PARA>In order to maintain compatibility with linker script
	  fragments and header files exported by the
	  <productname>eCos</productname> <APPLICATION>Configuration Tool</APPLICATION>, the use
	  of other expressions within these files is not
	  recommended.</PARA>
<PARA>Note that the names of the linker output sections will vary
between target architectures. A description of these sections can
be found in the specific <productname>GCC</productname> documentation for
your architecture.</PARA>
</SECT1>
</CHAPTER>
<CHAPTER id="managing-package-repository">
<TITLE>Managing the <!-- <index></index> -->Package Repository</TITLE>
<PARA>A source distribution of <productname>eCos</productname> consists of a number of
	packages, such as the kernel, the C library, and the
	&micro;ITRON subsystems. These are
	individually versioned in the tree structure of the source
	code, to support distribution on a per-package basis and to
	support third party packages whose versioning systems might be
	different. The <productname>eCos</productname> <application>Package
	  Administration Tool</application> is used to manage the
	installation and removal of packages from a variety of sources
	with potentially multiple versions.</PARA>
<PARA>The presence of the version information in the source tree
	structure might be a hindrance to the use of a separate source
	control system such as <EMPHASIS>CVS</EMPHASIS> or
	<EMPHASIS>SourceSafe</EMPHASIS>. To work
	in this way, you can rename all the version components to some
	common name (such as &ldquo;current&rdquo;) thus unifying the
	structure of source trees from distinct <productname>eCos</productname> releases.</PARA>
<PARA>The <productname>eCos</productname> build system will treat any such name as just another
version of the package(s), and support building in exactly the same
way. However, performing this rename invalidates any existing build
trees that referred to the versioned source tree, so do the rename
first, before any other work, and do a complete rebuild afterwards.</PARA>
<SECT1 id="package-installation">
<TITLE>Package Installation</TITLE>
<PARA>Package installation and removal is performed using the
	  <productname>eCos</productname> <application>Package Administration Tool</application>. This
	  tool is a Tcl script named
	<command>ecosadmin.tcl</command> which allows
	  the user to add new <productname>eCos</productname> packages and new versions of
	  existing packages to an <productname>eCos</productname> repository. Such packages must
	  be distributed as a single file in the <productname>eCos</productname> package
	  distribution format. Unwanted packages may also be removed
	  from the repository using this tool. A graphical version of
	  the tool is provided as part of the
	  <productname>eCos</productname> <application>Configuration Tool</application>.</PARA>
<SECT2>
<TITLE>Using the Administration Tool</TITLE> <PARA>The graphical
version of the <productname>eCos</productname> <application>Package
Administration Tool</application>, provided as part of the
<productname>eCos</productname> <application>Configuration
Tool</application>, provides functions equivalent to the command-line
version for those who prefer a Windows-based interface.</PARA>
<PARA>It may be invoked in one of two ways:</PARA>
<ITEMIZEDLIST>
<LISTITEM>
<PARA>from the <GUIMENU>start menu</GUIMENU> (by default
		<GUIMENUITEM>Start-&gt;Programs-&gt;
		  eCos-&gt;Package Administration
		  Tool</GUIMENUITEM>)</PARA>
<!--
<para>
XXXXX What is the Windows menu structure now? XXXXX
</para>
-->
            
</LISTITEM>
<LISTITEM>
<PARA>from the <productname>eCos</productname> <APPLICATION>Configuration
		  Tool</APPLICATION> via the
		<GUIMENUITEM>Tools-&gt;Administration</GUIMENUITEM>
		menu item</PARA>
</LISTITEM>
</ITEMIZEDLIST>
<PARA><GRAPHIC ENTITYREF="graphic31"></GRAPHIC></PARA>
<PARA>The main window of the tool displays the packages which are
currently installed in the form of a tree. The installed versions
of each package may be examined by expanding the tree.</PARA>
<PARA>Packages may be added to the <productname>eCos</productname> repository by clicking on
the <EMPHASIS>Add</EMPHASIS> button. The <productname>eCos</productname> package distribution
file to be added is then selected via a <EMPHASIS>File Open</EMPHASIS> dialog
box.</PARA>
<PARA>Packages may be removed by selecting a package in the tree
and then clicking on the <EMPHASIS>Remove</EMPHASIS> button. If
a package node is selected, all versions of the selected package
will be removed. If a package version node is selected, only the
selected version of the package will be removed.</PARA>
</SECT2>
<SECT2>
<TITLE>Using the command line</TITLE>
<PARA>The <command>ecosadmin.tcl</command>
	    script is located in the base of the <productname>eCos</productname> repository. Use
	    a command of the following form under versions of
	    UNIX:</PARA>
<SCREEN>$ tclsh ecosadmin.tcl &lt;command&gt;</SCREEN>
<PARA>Under Windows, a command of the following form may be used
at the Cygwin command line prompt:</PARA>
<SCREEN>$ cygtclsh80 ecosadmin.tcl &lt;command&gt;</SCREEN>
<PARA>The following commands are available:</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM><COMMAND>add &lt;file&gt;</COMMAND></TERM>
<LISTITEM><!-- <index></index> -->
<PARA>Adds the packages contained with the specified package distribution
file to the <productname>eCos</productname> repository and updates the package database accordingly.
By convention, <productname>eCos</productname> package distribution files are given the <filename>.epk</filename> suffix.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>remove &lt;package&gt; [ --version=&lt;version&gt; ]</COMMAND></TERM><!-- <index></index> -->
<LISTITEM>
<PARA>Removes the specified package from the <productname>eCos</productname>
		  repository and updates the package database
		  accordingly. Where the optional version qualifier is
		  used, only the specified version of the package is
		  removed.</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><COMMAND>list</COMMAND></TERM><!-- <index></index> -->
<LISTITEM>
<PARA>Produces a list of the packages which
		  are currently installed and their versions. The
		  available templates and hardware targets are also
		  listed.</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
<PARA>Note that is is possible to remove critical packages
	    such as the common HAL package using this tool. Users
	    should take care to avoid such errors since core <productname>eCos</productname>
	    packages may only be re-installed in the context of a
	    complete re-installation of <productname>eCos</productname>.</PARA>
</SECT2>
</SECT1>
<SECT1 id="package-structure">
<TITLE>Package Structure</TITLE>
<PARA>The files in an installed <productname>eCos</productname> source tree are organized in
a natural tree structure, grouping together files which work together
into <EMPHASIS>Packages</EMPHASIS>. For example, the kernel files
are all together in: </PARA>
<SIMPLELIST>
<MEMBER><FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/kernel/<replaceable>&Version;</replaceable>/include/</FILENAME></MEMBER>
<MEMBER>	    <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/kernel/<replaceable>&Version;</replaceable>/src/</FILENAME></MEMBER>
<MEMBER>	<FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/kernel/<replaceable>&Version;</replaceable>/tests/</FILENAME></MEMBER>
</SIMPLELIST>
<PARA>and &micro;ITRON compatibility layer files are in:
	</PARA>
<SIMPLELIST>
<MEMBER>	    <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/compat/uitron/<replaceable>&Version;</replaceable>/include/</FILENAME></MEMBER>
<MEMBER>	<FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/compat/uitron/<replaceable>&Version;</replaceable>/src/</FILENAME></MEMBER>
<MEMBER>	<FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/compat/uitron/<replaceable>&Version;</replaceable>/tests/</FILENAME></MEMBER>
</SIMPLELIST>
<PARA>The feature of these names which is of interest here is
	  the <replaceable>&Version;</replaceable> near the end. It may seem odd to place a version number deep in the
	  path, rather than having something like
	  <FILENAME><REPLACEABLE>BASE_DIR</REPLACEABLE>/<replaceable>&Version;</replaceable>/...everything...</FILENAME>
          or leaving it up to you to choose a different
	  install-place when a new release of the system arrives.
	</PARA>
<PARA>There is a rationale for this organization: as
	  indicated, the kernel and the
	  &micro;ITRON compatibility subsystem
	  are examples of software packages. For the first few
	  releases of <productname>eCos</productname>, all the packages will move along
	  in step, i.e. Release 1.3.x will feature Version
	  1.3.x of every package, and so forth. But in future,
	  especially when third party packages become available, it is
	  intended that the package be the unit of software
	  distribution, so it will be possible to build a system from
	  a selection of packages with different version numbers, and
	  even differing versioning <EMPHASIS>schemes</EMPHASIS>. A
	  Tcl script <command>ecosadmin.tcl</command> is
	  provided in the <productname>eCos</productname> repository to manage the installation
	  and removal of packages in this way.</PARA>
<PARA>Many users will have their own source code control system,
version control system or equivalent, and will want to use it with
<productname>eCos</productname> sources. In that case, since a new release of <productname>eCos</productname> comes with
different pathnames for all the source files, a bit of work is necessary
to import a new release into your source repository. </PARA>
<PARA>One way of handling the import is to rename all the version
parts to some common name, for example &ldquo;current&rdquo;,
and continue to work. &ldquo;current&rdquo; is suggested because <command>ecosconfig</command> recognizes
it and places it first in any list of versions. In the future, we
may provide a tool to help with this, or an option in the install
wizard. Alternatively, in a POSIX shell environment (Linux or Cygwin
on Windows) use the following command: </PARA>
<SCREEN>find . -name <replaceable>&Version;</replaceable> -type d -printf 'mv &percnt;p &percnt;h/current\n' | sh</SCREEN>
<PARA>Having carried out such a renaming operation, your
	  source tree will now look like this: </PARA>
<SCREEN><REPLACEABLE>BASE_DIR</REPLACEABLE>/kernel/current/include/
<REPLACEABLE>BASE_DIR</REPLACEABLE>/kernel/current/src/
<REPLACEABLE>BASE_DIR</REPLACEABLE>/kernel/current/tests/
	...
<REPLACEABLE>BASE_DIR</REPLACEABLE>/compat/uitron/current/include/
<REPLACEABLE>BASE_DIR</REPLACEABLE>/compat/uitron/current/src/
<REPLACEABLE>BASE_DIR</REPLACEABLE>/compat/uitron/current/tests/
	</SCREEN>
<PARA>which is a suitable format for import into your own
	  source code control system. When you get a subsequent
	  release of <productname>eCos</productname>, do the same thing and use your own source
	  code control system to manage the new source base, by
	  importing the new version from </PARA>
<SCREEN><REPLACEABLE>NEW_BASE_DIR</REPLACEABLE>/kernel/current/include/</SCREEN>
<PARA>and so on. </PARA>
<PARA>The <productname>eCos</productname> build tool will now offer only the
	  &ldquo;current&rdquo; version of each package; select this
	  for the packages you wish to use. </PARA>
<PARA>Making such a change has implications for any build
	  trees you already have in use. A configured build tree
	  contains information about the selected packages and their
	  selected versions. Changing the name of the
	  &ldquo;versioning&rdquo; folder in the source tree
	  invalidates this information, and in consequence it also
	  invalidates any local configuration options you have set up
	  in this build tree. So if you want to change the version
	  information in the source tree, do it first, before
	  investing any serious time in configuring and building your
	  system. When you create a new build tree to deal with the
	  new source layout, it will contain default settings for all
	  the configuration options, just like the old build tree did
	  before you configured it. You will need to redo that
	  configuration work in the new tree. </PARA>
<PARA>Moving source code around also invalidates debugging information
in any programs or libraries built from the old tree; these will
need to be rebuilt. </PARA>
</SECT1>
</CHAPTER>
</PART>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-namecase-general:t
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:("user-guide.sgml" "book" "part")
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->