diff options
Diffstat (limited to 'ecos/doc/sgml/user-guide/configuration.sgml')
| -rw-r--r-- | ecos/doc/sgml/user-guide/configuration.sgml | 2021 |
1 files changed, 2021 insertions, 0 deletions
diff --git a/ecos/doc/sgml/user-guide/configuration.sgml b/ecos/doc/sgml/user-guide/configuration.sgml new file mode 100644 index 0000000..c06fa89 --- /dev/null +++ b/ecos/doc/sgml/user-guide/configuration.sgml @@ -0,0 +1,2021 @@ +<!-- {{{ 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 <qualifiers> <command></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=<file></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=<dir></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=<dir></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><dir></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 <target> [<template> [<version>]]</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 ‘default’ is used. If + the template version is not specified, the latest + version is used.</PARA> +</LISTITEM> +</VARLISTENTRY> +<VARLISTENTRY> +<TERM><COMMAND>target <target></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 <template> [<version>]</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 <packages></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 <packages></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 <version> <packages></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 <file></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 <file></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’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 — 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 µITRON + compatibility package relies almost entirely on + functionality provided by the kernel package, and it would + not make sense to try to build µ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 µ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 “#” 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 ““ ; + +# 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’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 ... +# > +cdl_component CYGPKG_KERNEL_EXCEPTIONS ... +# > +cdl_option CYGSEM_KERNEL_EXCEPTIONS_DECODE ... +cdl_option CYGSEM_KERNEL_EXCEPTIONS_GLOBAL ... +# < +cdl_component CYGPKG_KERNEL_SCHED ... +# > +cdl_option CYGSEM_KERNEL_SCHED_MLQUEUE ... +cdl_option CYGSEM_KERNEL_SCHED_BITMAP ... +# < +# < + </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><type> <name> { + <data> +};</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 +# --> 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’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’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 +# --> 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: “POSIX” “IEEE” “XOPEN” “SVID” +... +}; + +</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: “POSIX” “IEEE” “XOPEN” “SVID” +... +}; + +</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: “POSIX” “IEEE” “XOPEN” “SVID” +... +}; + +</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 \ +# “CYG_UIT_MEMPOOLVAR( vpool1, 2000 ), \\ +# CYG_UIT_MEMPOOLVAR( vpool2, 2000 ), \\ +# CYG_UIT_MEMPOOLVAR( vpool3, 2000 ),” +# value_source default +# Default value: \ +# “CYG_UIT_MEMPOOLVAR( vpool1, 2000 ), \\ +# CYG_UIT_MEMPOOLVAR( vpool2, 2000 ), \\ +# CYG_UIT_MEMPOOLVAR( vpool3, 2000 ),” +}; + +</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 \ +“CYG_UIT_MEMPOOLVAR( vpool1, 4000 ), \\ +CYG_UIT_MEMPOOLVAR( vpool2, 4000 ),” +# value_source default +# Default value: \ +# “CYG_UIT_MEMPOOLVAR( vpool1, 2000 ), \\ +# CYG_UIT_MEMPOOLVAR( vpool2, 2000 ), \\ +# CYG_UIT_MEMPOOLVAR( vpool3, 2000 ),” +}; + +</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’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 ? “thumb-elf” : “arm-elf” +# CYGHWR_THUMB == 0 +# --> 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 “<LITERAL>hello +world</LITERAL>” 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: “POSIX” “IEEE” “XOPEN” “SVID” +... +}; + +</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 +# --> 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 \ + “static char vpool1\[ 2000 \], \\ + vpool2\[ 2000 \], \\ + vpool3\[ 2000 \];” +# value_source default +# Default value: \ + # “static char vpool1\[ 2000 \], \\ + # vpool2\[ 2000 \], \\ + # vpool3\[ 2000 \];” +}; + +</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 µ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’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 “Hello world”</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 “\”/dev/ttydiag\”” +# value_source default +# Default value: “\”/dev/ttydiag\”” +}; + +</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 “/dev/ttydiag” +# value_source default +# Default value: “\”/dev/ttydiag\”” +}; + +</SCREEN> +<PARA>then the Tcl interpreter would remove the quote marks when +the savefile is read back in, so the option’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 “Hello\nworld\n” +puts \ +“Hello +world +“</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 “The answer is [expr 6 * 9]”</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 “The answer is 54”</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 \ +“static char fpool1[ 2000 ], +fpool2[ 2000 ];” + ... +}; +</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 \ +“static char fpool1\[ 2000 \], +fpool2\[ 2000 \];” + ... +}; </PROGRAMLISTING> +<PARA>Similarly the <literal>$</literal> character +is used in Tcl scripts to perform variable substitution:</PARA> +<PROGRAMLISTING>set x [expr 6 * 9] +puts “The answer is $x” </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 “\$ “ + ... +};</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 <name> { + ... +};</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 “Hello” # 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 “Hello”; # 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’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 + µ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 “current”) 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->Programs-> + eCos->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->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 <command></SCREEN> +<PARA>Under Windows, a command of the following form may be used +at the Cygwin command line prompt:</PARA> +<SCREEN>$ cygtclsh80 ecosadmin.tcl <command></SCREEN> +<PARA>The following commands are available:</PARA> +<VARIABLELIST> +<VARLISTENTRY> +<TERM><COMMAND>add <file></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 <package> [ --version=<version> ]</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 µ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 + µ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 “current”, +and continue to work. “current” 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 %p %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 + “current” 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 + “versioning” 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: +--> |