Subversion Repositories openrisc

The following chapters contain information on running

The following chapters contain information on running

        ecosconfig (the command line tool that

        ecosconfig (the command line tool that

        manipulates configurations and constructs build trees) and on

        manipulates configurations and constructs build trees) and on

        managing a source repository across multiple versions of

        managing a source repository across multiple versions of

        eCos. 

        eCos. 

    eCos developers will generally use the graphical

    eCos developers will generally use the graphical

      Configuration Tool for configuring an eCos system and building

      Configuration Tool for configuring an eCos system and building

      the target library. However, some user prefer to use command

      the target library. However, some user prefer to use command

      line tools. These command line tools can also be used for batch

      line tools. These command line tools can also be used for batch

      operations on all platforms, for example as part of a nightly

      operations on all platforms, for example as part of a nightly

      rebuild and testing procedure.

      rebuild and testing procedure.

In the current release of the system the command line tools

In the current release of the system the command line tools

      do not provide exactly the same functionality as the graphical

      do not provide exactly the same functionality as the graphical

      tool. Most importantly, there is no facility to resolve

      tool. Most importantly, there is no facility to resolve

      configuration conflicts interactively.

      configuration conflicts interactively.

The eCos configuration system, both graphical and command

The eCos configuration system, both graphical and command

      line tools, are under constant development and enhancement.

      line tools, are under constant development and enhancement.

      Developers should note that the procedures described may change

      Developers should note that the procedures described may change

      considerably in future releases. 

      considerably in future releases. 

When building eCos there are three main directory trees to

When building eCos there are three main directory trees to

        consider: the source tree, the build tree, and the install

        consider: the source tree, the build tree, and the install

        tree.

        tree.

The source tree, also known as the component repository,

The source tree, also known as the component repository,

          is read-only. It is possible to use a single component

          is read-only. It is possible to use a single component

          repository for any number of different configurations, and

          repository for any number of different configurations, and

          it is also possible to share a component repository between

          it is also possible to share a component repository between

          multiple users by putting it on a network drive.

          multiple users by putting it on a network drive.

The build tree contains everything that is specific to a

The build tree contains everything that is specific to a

          particular configuration, including header and other files

          particular configuration, including header and other files

          that contain configuration data, and the object files that

          that contain configuration data, and the object files that

          result from compiling the system sources for this

          result from compiling the system sources for this

          configuration. 

          configuration. 

The install tree is usually located in the install subdirectory

The install tree is usually located in the install subdirectory

of the build tree. Once an eCos system has been built, the install

of the build tree. Once an eCos system has been built, the install

tree contains all the files needed for application development including

tree contains all the files needed for application development including

the header files and the target library. By making copies of the

the header files and the target library. By making copies of the

install tree after a build it is possible to separate application

install tree after a build it is possible to separate application

development and system configuration, which may be desirable for

development and system configuration, which may be desirable for

some organizations. 

some organizations. 

Generating a build tree is a non-trivial operation and

Generating a build tree is a non-trivial operation and

          should not be attempted manually. Instead, eCos is shipped

          should not be attempted manually. Instead, eCos is shipped

          with a tool called ecosconfig that should

          with a tool called ecosconfig that should

          be used to create a build tree.

          be used to create a build tree.

Usually ecosconfig will be

Usually ecosconfig will be

run inside the build tree itself. If you are creating a new build

run inside the build tree itself. If you are creating a new build

tree then typically you will create a new empty directory using

tree then typically you will create a new empty directory using

the mkdir command, cd into

the mkdir command, cd into

that directory, and then invoke ecosconfig to

that directory, and then invoke ecosconfig to

create a configuration. By default, the configuration is stored

create a configuration. By default, the configuration is stored

in a file ecos.ecc in the current

in a file ecos.ecc in the current

directory. The configuration may be modified by editing this file directly. ecosconfig itself

directory. The configuration may be modified by editing this file directly. ecosconfig itself

deals with a number of coarse-grained configuration options such

deals with a number of coarse-grained configuration options such

as the target platform and the packages that should be used.

as the target platform and the packages that should be used.

The ecosconfig tool is also

The ecosconfig tool is also

used subsequently to generate a build tree for a configuration.

used subsequently to generate a build tree for a configuration.

Once a build tree exists, it is possible to run ecosconfig again

Once a build tree exists, it is possible to run ecosconfig again

inside the same build tree. This will be necessary if your wish

inside the same build tree. This will be necessary if your wish

to change some of the configuration options.

to change some of the configuration options.

ecosconfig does not generate

ecosconfig does not generate

the top-level directory of the build tree; you must do this

the top-level directory of the build tree; you must do this

        yourself. 

        yourself. 

$ mkdir ecos-work

$ mkdir ecos-work

$ cd ecos-work

$ cd ecos-work

The next step is to run ecosconfig: 

The next step is to run ecosconfig: 

$ ecosconfig <qualifiers> <command>

$ ecosconfig <qualifiers> <command>

The available command line qualifiers for

The available command line qualifiers for

            ecosconfig are as follows. Multiple

            ecosconfig are as follows. Multiple

            qualifiers may be used on the command line:

            qualifiers may be used on the command line:

--help

--help

Provides basic usage guidelines for the

Provides basic usage guidelines for the

              available commands and qualifiers.

              available commands and qualifiers.

--config=<file>

--config=<file>

Specifies an eCos configuration save file for

Specifies an eCos configuration save file for

                  use by the tool. By default, the file

                  use by the tool. By default, the file

                  ecos.ecc in the

                  ecos.ecc in the

                  current directory is used. Developers may prefer to

                  current directory is used. Developers may prefer to

                  use a common location for all their eCos

                  use a common location for all their eCos

                  configurations rather than keep the configuration

                  configurations rather than keep the configuration

                  information in the base of the build tree.

                  information in the base of the build tree.

--prefix=<dir>

--prefix=<dir>

Specifies an alternative location for the

Specifies an alternative location for the

                  install tree. By default, the install tree resides

                  install tree. By default, the install tree resides

                  inside the install

                  inside the install

                  directory in the build tree. Developers may prefer

                  directory in the build tree. Developers may prefer

                  to locate the build tree in a temporary file

                  to locate the build tree in a temporary file

                  hierarchy but keep the install tree in a more

                  hierarchy but keep the install tree in a more

                  permanent location.

                  permanent location.

--srcdir=<dir>

--srcdir=<dir>

Specifies the location of the component

Specifies the location of the component

                  repository. By default, the tool uses the location

                  repository. By default, the tool uses the location

                  specified in the

                  specified in the

                  ECOS_REPOSITORY

                  ECOS_REPOSITORY

                  environment variable. Developers may prefer to use

                  environment variable. Developers may prefer to use

                  of this qualifier if they are working with more than

                  of this qualifier if they are working with more than

                  one repository.

                  one repository.

--no-resolve

--no-resolve

Disables the implicit resolution of conflicts

Disables the implicit resolution of conflicts

                  while manipulating the configuration data.

                  while manipulating the configuration data.

                  developers may prefer to resolve conflicts by

                  developers may prefer to resolve conflicts by

                  editing the eCos configuration save file

                  editing the eCos configuration save file

                  manually.

                  manually.

--ignore-errors

--ignore-errors

-i

-i

By default, ecosconfig will exit with an error code if the current

By default, ecosconfig will exit with an error code if the current

configuration contains any conflicts, and it is not possible to

configuration contains any conflicts, and it is not possible to

generate or update a build tree for such configurations. This

generate or update a build tree for such configurations. This

qualifier causes ecosconfig to ignore such problems, and hence it is

qualifier causes ecosconfig to ignore such problems, and hence it is

possible to generate a build tree even if there are still

possible to generate a build tree even if there are still

conflicts. Of course, there are no guarantees that the resulting

conflicts. Of course, there are no guarantees that the resulting

system will actually do anything.

system will actually do anything.

--verbose

--verbose

-v

-v

Display more information.

Display more information.

--quiet

--quiet

-q

-q

Display less information.

Display less information.

The --config, --prefix and

The --config, --prefix and

--srcdir qualifiers can also be written with two arguments,

--srcdir qualifiers can also be written with two arguments,

for example:

for example:

ecosconfig --srcdir <dir> ...

ecosconfig --srcdir <dir> ...

This simplifies filename completion with some shells.

This simplifies filename completion with some shells.

The available commands for

The available commands for

            ecosconfig are as

            ecosconfig are as

            follows:

            follows:

list

list

Lists the available packages, targets and

Lists the available packages, targets and

                  templates as installed in the eCos repository.

                  templates as installed in the eCos repository.

                  Aliases and package versions are also

                  Aliases and package versions are also

                  reported.

                  reported.

new <target> [<template> [<version>]]

new <target> [<template> [<version>]]

Creates a new eCos configuration for

Creates a new eCos configuration for

                  the specified target hardware and saves it. A

                  the specified target hardware and saves it. A

                  software template may also be specified. By default,

                  software template may also be specified. By default,

                  the template named ‘default’ is used. If

                  the template named ‘default’ is used. If

                  the template version is not specified, the latest

                  the template version is not specified, the latest

                  version is used.

                  version is used.

target <target>

target <target>

Changes the target hardware selection

Changes the target hardware selection

                  for the eCos configuration. This has the effect of

                  for the eCos configuration. This has the effect of

                  unloading packages supporting the target selected

                  unloading packages supporting the target selected

                  previously and loading the packages which support

                  previously and loading the packages which support

                  the new hardware. This command will be used

                  the new hardware. This command will be used

                  typically when switching between a simulator and

                  typically when switching between a simulator and

                  real hardware.

                  real hardware.

template <template> [<version>]

template <template> [<version>]

Changes the template selection for the eCos

Changes the template selection for the eCos

                  configuration. This has the effect of unloading

                  configuration. This has the effect of unloading

                  packages specified by the template selected

                  packages specified by the template selected

                  previously and loading the packages specified by the

                  previously and loading the packages specified by the

                  new template. By default, the latest version of the

                  new template. By default, the latest version of the

                  specified template is used.

                  specified template is used.

remove <packages>

remove <packages>

Removes the specified packages from the eCos

Removes the specified packages from the eCos

                  configuration. This command will be used typically

                  configuration. This command will be used typically

                  when the template on which a configuration is based

                  when the template on which a configuration is based

                  contains packages which are not required.

                  contains packages which are not required.

add <packages>

add <packages>

Adds the specified packages to the eCos configuration. This

Adds the specified packages to the eCos configuration. This

command will be used typically when the template on which a

command will be used typically when the template on which a

configuration is based does not contain all the packages which are

configuration is based does not contain all the packages which are

required.For example, add-on packages provided by third parties will

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

not be known to the standard templates, so they will have to be added

explicitly. 

explicitly. 

version <version> <packages>

version <version> <packages>

Selects the specified version of a

Selects the specified version of a

                  number of packages in the eCos configuration. By

                  number of packages in the eCos configuration. By

                  default, the most recent version of each package is

                  default, the most recent version of each package is

                  used. This command will be used typically when an

                  used. This command will be used typically when an

                  older version of a package is required.

                  older version of a package is required.

check

check

Presents the following information

Presents the following information

                  concerning the current configuration:

                  concerning the current configuration:

the selected target hardware

the selected target hardware

the selected template

the selected template

additional packages

additional packages

removed packages

removed packages

the selected version of packages

the selected version of packages

                      where this is not the most recent

                      where this is not the most recent

                      version

                      version

conflicts in the current configuration

conflicts in the current configuration

resolve

resolve

Resolves conflicts identified in the

Resolves conflicts identified in the

                  current eCos configuration by invoking an inference

                  current eCos configuration by invoking an inference

                  capability. Resolved conflicts are reported, but not

                  capability. Resolved conflicts are reported, but not

                  all conflicts may be resolvable. This command will

                  all conflicts may be resolvable. This command will

                  be used typically following manual editing of the

                  be used typically following manual editing of the

                  configuration.

                  configuration.

export <file>

export <file>

Exports a minimal eCos configuration

Exports a minimal eCos configuration

                  save file with the specified name. This file

                  save file with the specified name. This file

                  contains only those options which do not have their

                  contains only those options which do not have their

                  default value. Such files are used typically to

                  default value. Such files are used typically to

                  transfer option values from one configuration to

                  transfer option values from one configuration to

                  another.

                  another.

import <file>

import <file>

Imports a minimal eCos configuration

Imports a minimal eCos configuration

                  save file with the specified name. The values of

                  save file with the specified name. The values of

                  those options specified in the file are applied to

                  those options specified in the file are applied to

                  the current configuration.

                  the current configuration.

tree

tree

Generates a build tree based on the current eCos

Generates a build tree based on the current eCos

                  configuration. This command will be used typically

                  configuration. This command will be used typically

                  just before building eCos.Normally a build tree can

                  just before building eCos.Normally a build tree can

only be generated if if the configuration has no unresolved

only be generated if if the configuration has no unresolved

conflicts, but --ignore-errors can be used to override

conflicts, but --ignore-errors can be used to override

this.

this.

Configuration options are not completely independent. For example

Configuration options are not completely independent. For example

the C library's strtod() and atof()

the C library's strtod() and atof()

functions rely on the math library package to provide certain functionality. If the math library package is removed then the C

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 "requires" properties. If a constraint is not satisfied, then the configuration contains a conflict. For any given conflict there can

library can no longer provide these functions. Each package describes constraints like these in CDL "requires" 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

be several resolution options. For example, it would be possible to add the math library package back to the

configuration, or to disable the strtod() and atof() functions.

configuration, or to disable the strtod() and atof() functions.

The eCos configuration tools will report any conflicts in the current configuration. If there are any such conflicts

The eCos 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 eCos in such circumstances. In fact,

then the configuration is usually unsafe and it makes no sense to build and run eCos in such circumstances. In fact,

any attempt at building eCos is likely to fail. In exceptional cases it is possible to override this by using e.g. the

any attempt at building eCos is likely to fail. In exceptional cases it is possible to override this by using e.g. the

--ignore-errors qualifier with ecosconfig.

--ignore-errors qualifier with ecosconfig.

Many constraints are fairly simple in nature, and the configuration tools contain an inference engine which can

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

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 strtod() and atof(). All

inference engine can resolve the resulting conflict by disabling the configuration option for strtod() and atof(). All

such changes will be reported. Sometimes the inference engine cannot resolve a conflict, for example it is not

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

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.

not match the application's requirements.

A typical session involving conflicts would look something like this:

A typical session involving conflicts would look something like this:

$ ecosconfig new pid

$ ecosconfig new pid

This creates a new configuration with the default template. For most targets this will not result in any conflicts,

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.

because the default settings for the various options meet the requirements of the default template.

 For some targets

 For some targets

there may be conflicts and the inference engine would come into play.

there may be conflicts and the inference engine would come into play.

$ ecosconfig remove libm

$ ecosconfig remove libm

U CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, new inferred value 0

U CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, new inferred value 0

U CYGFUN_LIBC_strtod, new inferred value 0

U CYGFUN_LIBC_strtod, new inferred value 0

U CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, new inferred value 0

U CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, new inferred value 0

ecosconfig reports that this change caused three conflicts, all in the C library. The inference engine was able to

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. 

resolve all the conflicts and update the relevant configuration options accordingly. 

To suppress the inference engine --no-resolve can be used:

To suppress the inference engine --no-resolve can be used:

$ ecosconfig new pid

$ ecosconfig new pid

$ ecosconfig --no-resolve remove libm

$ ecosconfig --no-resolve remove libm

C CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, "requires" constraint not satisfied:      CYGPKG_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 CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, "requires" constraint not satisfied:      CYGPKG_LIBM

C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM

C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM

Three unresolved conflicts are reported.

Three unresolved conflicts are reported.

The check command can be used to get the current state of the

The check command can be used to get the current state of the

configuration, and the --verbose qualifier will provide additional information: 

configuration, and the --verbose qualifier will provide additional information: 

$ ecosconfig --srcdir /home/bartv/ecc/ecc --verbose check

$ ecosconfig --srcdir /home/bartv/ecc/ecc --verbose check

Target: pid

Target: pid

Template: default

Template: default

Removed:

Removed:

 CYGPKG_LIBM

 CYGPKG_LIBM

3 conflict(s):

3 conflict(s):

C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM

C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM

 Possible solution:

 Possible solution:

    CYGFUN_LIBC_strtod -> 0

    CYGFUN_LIBC_strtod -> 0

    CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT -> 0

    CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT -> 0

C CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, "requires" constraint not satisfied:      CYGPKG_LIBM

C CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, "requires" constraint not satisfied:      CYGPKG_LIBM

 Possible solution:

 Possible solution:

    CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT -> 0

    CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT -> 0

C CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, "requires" constraint not satisfied:      CYGPKG_LIBM

C CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, "requires" constraint not satisfied:      CYGPKG_LIBM

 Possible solution:

 Possible solution:

    CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT -> 0

    CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT -> 0

If the proposed solutions are acceptable, the resolve command can be used to apply them:

If the proposed solutions are acceptable, the resolve command can be used to apply them:

$ ecosconfig resolve

$ ecosconfig resolve

U CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, new inferred value 0

U CYGSEM_LIBC_STDIO_SCANF_FLOATING_POINT, new inferred value 0

U CYGFUN_LIBC_strtod, new inferred value 0

U CYGFUN_LIBC_strtod, new inferred value 0

U CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, new inferred value 0

U CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT, new inferred value 0

The current configuration is again conflict-free and it is possible to generate a build tree. The --quiet qualifier can

The current configuration is again conflict-free and it is possible to generate a build tree. The --quiet qualifier can

be used to suppress the change messages, if desired.

be used to suppress the change messages, if desired.

When changing individual configuration options by editing the ecos.ecc file (as described below), the resulting

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

system should be checked and any problems should be resolved. For example, if CYGFUN_LIBC_strtod is

explicitly enabled in the savefile:

explicitly enabled in the savefile:

$ edit ecos.ecc

$ edit ecos.ecc

$ ecosconfig check

$ ecosconfig check

Target: pid

Target: pid

Template: default

Template: default

Removed:

Removed:

    CYGPKG_LIBM

    CYGPKG_LIBM

1 conflict(s):

1 conflict(s):

C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM

C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM

$ ecosconfig resolve

$ ecosconfig resolve

C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM

C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM

In this case the inference engine cannot resolve the conflict automatically because that would involve changing a

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:

user setting. Any attempt to generate a build tree will fail:

$ ecosconfig --srcdir /home/bartv/ecc/ecc tree

$ ecosconfig --srcdir /home/bartv/ecc/ecc tree

C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM

C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM

Unable to generate build tree, this configuration still contains conflicts.

Unable to generate build tree, this configuration still contains conflicts.

Either resolve the conflicts or use --ignore-errors

Either resolve the conflicts or use --ignore-errors

It is still possible to generate a build tree:

It is still possible to generate a build tree:

$ ecosconfig --srcdir /home/bartv/ecc/ecc --ignore-errors tree

$ ecosconfig --srcdir /home/bartv/ecc/ecc --ignore-errors tree

C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM

C CYGFUN_LIBC_strtod, "requires" constraint not satisfied: CYGPKG_LIBM

$ make

$ make

In this case eCos will fail to build. In other cases of unresolved conflicts eCos may build, but may not run. In

In this case eCos will fail to build. In other cases of unresolved conflicts eCos may build, but may not run. In

general all conflicts should be resolved by editing the ecos.ecc file, by letting the inference engine make appropriate

general all conflicts should be resolved by editing the ecos.ecc file, by letting the inference engine make appropriate

changes, or by other means, before any attempt is made to build or run eCos.

changes, or by other means, before any attempt is made to build or run eCos.

Once a build tree has been generated with

Once a build tree has been generated with

          ecosconfig, building eCos is straightforward:

          -->building eCos is straightforward:

$ make

$ make

The build tree contains the subdirectories, makefiles,

The build tree contains the subdirectories, makefiles,

          and everything else that is needed to generate the default

          and everything else that is needed to generate the default

          configuration for the selected architecture and platform.

          configuration for the selected architecture and platform.

          The only requirement is that the tools needed for that

          The only requirement is that the tools needed for that

          architecture, for example

          architecture, for example

          powerpc-eabi-g++,

          powerpc-eabi-g++,

          are available using the standard search path. If this is not

          are available using the standard search path. If this is not

          the case then the make will

          the case then the make will

          fail with an error message. If you have a multiprocessor

          fail with an error message. If you have a multiprocessor

          system then it may be more efficient to use:

          system then it may be more efficient to use:

$ make -j n

$ make -j n

where n is equal to the

where n is equal to the

          number of processors on your system.

          number of processors on your system.

Once the make process

Once the make process

          has completed, the install tree will contain the header

          has completed, the install tree will contain the header

          files and the target library that are needed for application

          files and the target library that are needed for application

          development. 

          development. 

It is also possible to build the system’s test cases

It is also possible to build the system’s test cases

for the current configuration:

for the current configuration:

$ make tests

$ make tests

The resulting test executables will end up in a

The resulting test executables will end up in a

          tests subdirectory of the

          tests subdirectory of the

          install tree. 

          install tree. 

If disk space is scarce then it is possible to make the copy

If disk space is scarce then it is possible to make the copy

of the install tree for application development purposes, and then

of the install tree for application development purposes, and then

use: 

use: 

$ make clean

$ make clean

The build tree will now use up a minimum of disk space — the

The build tree will now use up a minimum of disk space — the

bulk of what is left consists of configuration header files that

bulk of what is left consists of configuration header files that

you may have edited and hence should not be deleted automatically.

you may have edited and hence should not be deleted automatically.

However, it is possible to rebuild the system at any time without

However, it is possible to rebuild the system at any time without

re-invoking ecosconfig, just by

re-invoking ecosconfig, just by

running make again. 

running make again. 

Under exceptional circumstances it may be necessary to run make

Under exceptional circumstances it may be necessary to run make

clean for other reasons, such as when a new release

clean for other reasons, such as when a new release

of the toolchain is installed. The toolchain includes a number of

of the toolchain is installed. The toolchain includes a number of

header files which are closely tied to the compiler, for example limits.h,

header files which are closely tied to the compiler, for example limits.h,

and these header files are not and should not be duplicated by eCos.

and these header files are not and should not be duplicated by eCos.

The makefiles perform header file dependency analysis, so that when

The makefiles perform header file dependency analysis, so that when

a header file is changed all affected sources will be rebuilt during

a header file is changed all affected sources will be rebuilt during

the next make. This is very useful

the next make. This is very useful

when the configuration header files are changed, but it also means

when the configuration header files are changed, but it also means

that a build tree containing information about the locations of

that a build tree containing information about the locations of

header files must be rebuilt. If a new version of the toolchain

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 installed and the old version is removed then this location information

is no longer accurate, and make will

is no longer accurate, and make will

complain that certain dependencies cannot be satisfied. Under such circumstances

complain that certain dependencies cannot be satisfied. Under such circumstances

it is necessary to do a make clean first. 

it is necessary to do a make clean first. 

eCos is a component architecture. The system comes as a

eCos is a component architecture. The system comes as a

          number of packages which can be

          number of packages which can be

          enabled or disabled as required, and new packages can be

          enabled or disabled as required, and new packages can be

          added as they become available. Unfortunately, the packages

          added as they become available. Unfortunately, the packages

          are not completely independent: for example the µITRON

          are not completely independent: for example the µITRON

          compatibility package relies almost entirely on

          compatibility package relies almost entirely on

          functionality provided by the kernel package, and it would

          functionality provided by the kernel package, and it would

          not make sense to try to build µITRON if the kernel

          not make sense to try to build µITRON if the kernel

          was disabled. The C library has fewer dependencies: some

          was disabled. The C library has fewer dependencies: some

          parts of the C library rely on kernel functionality, but it

          parts of the C library rely on kernel functionality, but it

          is possible to disable these parts and thus build a system

          is possible to disable these parts and thus build a system

          that has the C library but no kernel. The

          that has the C library but no kernel. The

        ecosconfig tool has the capability of

        ecosconfig tool has the capability of

            checking that all the dependencies are satisfied, but it

            checking that all the dependencies are satisfied, but it

            may still be possible to produce configurations that will

            may still be possible to produce configurations that will

            not build or (conceivably) that will build but not run.

            not build or (conceivably) that will build but not run.

            Developers should be aware of this and take appropriate

            Developers should be aware of this and take appropriate

            care.

            care.

By default, ecosconfig will

By default, ecosconfig will

include all packages that are appropriate for the specified hardware

include all packages that are appropriate for the specified hardware

in the configuration. The common HAL package and

in the configuration. The common HAL package and

the eCos infrastructure must be present in every configuration. In

the eCos infrastructure must be present in every configuration. In

addition, it is always necessary to have one architectural HAL package

addition, it is always necessary to have one architectural HAL package

and one platform HAL package. Other packages are optional, and can

and one platform HAL package. Other packages are optional, and can

be added or removed from a configuration as required.

be added or removed from a configuration as required.

The application may not require all of the packages; for example,

The application may not require all of the packages; for example,

it might not need the µITRON compatibility

it might not need the µITRON compatibility

package, or the floating point support provided by the math library.

package, or the floating point support provided by the math library.

There is a slight overhead when eCos is built because the packages

There is a slight overhead when eCos is built because the packages

will get compiled, and there is also a small disk space penalty.

will get compiled, and there is also a small disk space penalty.

However, any unused facilities will get stripped out at link-time,

However, any unused facilities will get stripped out at link-time,

so having redundant packages will not affect the final executable. 

so having redundant packages will not affect the final executable. 

Coarse-grained configuration of

Coarse-grained configuration of

          an eCos system means making configuration changes using the

          an eCos system means making configuration changes using the

          ecosconfig tool. These changes

          ecosconfig tool. These changes

          include: 

          include: 

switching to different target hardware

switching to different target hardware

switching to a different template

switching to a different template

adding or removing a package

adding or removing a package

changing the version of a package

changing the version of a package

Whenever ecosconfig generates or

Whenever ecosconfig generates or

          updates an eCos configuration, it generates a configuration

          updates an eCos configuration, it generates a configuration

          save file.

          save file.

Suppose that the configuration was first created using

Suppose that the configuration was first created using

          the following command line: 

          the following command line: 

$ ecosconfig new stdeval1

$ ecosconfig new stdeval1

To change the target hardware to the Cogent CMA28x

To change the target hardware to the Cogent CMA28x

          PowerPC board, the following command would be needed:

          PowerPC board, the following command would be needed:

$ ecosconfig target cma28x

$ ecosconfig target cma28x

To switch to the PowerPC simulator instead: 

To switch to the PowerPC simulator instead: 

$ ecosconfig target psim

$ ecosconfig target psim

As the hardware changes, hardware-related packages such as

As the hardware changes, hardware-related packages such as

the HAL packages and device drivers will be added to and removed

the HAL packages and device drivers will be added to and removed

from the configuration as appropriate. 

from the configuration as appropriate. 

To remove any package from the current configuration, use

To remove any package from the current configuration, use

the remove command: 

the remove command: 

$ ecosconfig remove uitron

$ ecosconfig remove uitron

You can disable multiple packages using multiple arguments,

You can disable multiple packages using multiple arguments,

for example: 

for example: 

$ ecosconfig remove uitron libm

$ ecosconfig remove uitron libm

If this turns out to have been a mistake then you can

If this turns out to have been a mistake then you can

          re-enable one or more packages with the

          re-enable one or more packages with the

          add command: 

          add command: 

$ ecosconfig add libm

$ ecosconfig add libm

Changing the desired version for a package is also

Changing the desired version for a package is also

          straightforward:

          straightforward:

$ ecosconfig version v2_1 kernel

$ ecosconfig version v2_1 kernel

It is necessary to regenerate the build tree and header

It is necessary to regenerate the build tree and header

          files following any changes to the configuration before

          files following any changes to the configuration before

          rebuilding eCos:

          rebuilding eCos:

$ ecosconfig tree

$ ecosconfig tree

ecosconfig only provides

ecosconfig only provides

          coarse-grained control over the configuration: the hardware,

          coarse-grained control over the configuration: the hardware,

          the template and the packages that should be built. Unlike

          the template and the packages that should be built. Unlike

          the Configuration Tool,

          the Configuration Tool,

          ecosconfig does not provide

          ecosconfig does not provide

          any facilities for manipulating finer-grained configuration options such as how many

           -->configuration options such as how many

          priority levels the scheduler should support. There are

          priority levels the scheduler should support. There are

          hundreds of these options, and manipulating them by means of

          hundreds of these options, and manipulating them by means of

          command line arguments would not be sensible. 

          command line arguments would not be sensible. 

In the current system fine-grained configuration options may

In the current system fine-grained configuration options may

be manipulated by manual editing of the configuration file. When

be manipulated by manual editing of the configuration file. When

a file has been edited in this way, the ecosconfig tool

a file has been edited in this way, the ecosconfig tool

should be used to check the configuration for any conflicts which

should be used to check the configuration for any conflicts which

may have been introduced:

may have been introduced:

$ ecosconfig check

$ ecosconfig check

The check command will list

The check command will list

all conflicts and will also rewrite the configuration file, propagating

all conflicts and will also rewrite the configuration file, propagating

any changes which affect other options. The user may choose to resolve

any changes which affect other options. The user may choose to resolve

the conflicts either by re-editing the configuration file manually

the conflicts either by re-editing the configuration file manually

or by invoking the inference engine using the resolve command:

or by invoking the inference engine using the resolve command:

$ ecosconfig resolve

$ ecosconfig resolve

The  resolve command will

The  resolve command will

list all conflicts which can be resolved and save the resulting changes

list all conflicts which can be resolved and save the resulting changes

to the configuration.

to the configuration.

It is necessary to regenerate the build tree and header files

It is necessary to regenerate the build tree and header files

following any changes to the configuration before rebuilding eCos:

following any changes to the configuration before rebuilding eCos:

$ ecosconfig tree

$ ecosconfig tree

All the configuration options and their descriptions are listed

All the configuration options and their descriptions are listed

in the eCos Reference Manual. 

in the eCos Reference Manual. 

The eCos configuration information is held in a single

The eCos configuration information is held in a single

          savefile, typically ecos.ecc, which can

          savefile, typically ecos.ecc, which can

          be generated by either the GUI configuration tool or by the

          be generated by either the GUI configuration tool or by the

          command line ecosconfig tool. The file

          command line ecosconfig tool. The file

          normally exists at the top level of the build tree. It is a

          normally exists at the top level of the build tree. It is a

          text file, allowing the various configurations options to be

          text file, allowing the various configurations options to be

          edited inside a suitable text editor or by other programs or

          edited inside a suitable text editor or by other programs or

          scripts, as well as in the GUI config tool.

          scripts, as well as in the GUI config tool.

An eCos savefile is actually a script in the Tcl programming

An eCos savefile is actually a script in the Tcl programming

language, so any modifications to the file need to preserve Tcl

language, so any modifications to the file need to preserve Tcl

syntax. For most configuration options, any modifications will be

syntax. For most configuration options, any modifications will be

trivial and there is no need to worry about Tcl syntax. For example,

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

changing a 1 to a 0 to disable an option.  For more complicated

options, for example CYGDAT_UITRON_TASK_EXTERNS,

options, for example CYGDAT_UITRON_TASK_EXTERNS,

which involves some lines of C code, more care has

which involves some lines of C code, more care has

to be taken. If an edited savefile is no longer a valid Tcl script

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

then the configuration tools will be unable to read back the data

for further processing, for example to generate a build tree. An

for further processing, for example to generate a build tree. An

outline of Tcl syntax is given below. One point worth noting here

outline of Tcl syntax is given below. One point worth noting here

is that a line that begins with a “#” is

is that a line that begins with a “#” is

usually a comment, and the bulk of an eCos savefile actually consists

usually a comment, and the bulk of an eCos savefile actually consists

of such comments, to make it easier to edit.

of such comments, to make it easier to edit.

An eCos savefile begins with a header, which typically

An eCos savefile begins with a header, which typically

            looks something like this:

            looks something like this:

# eCos saved configuration

# eCos saved configuration

# ---- commands --------------------------------------------------------

# ---- commands --------------------------------------------------------

# This section contains information about the savefile format.

# This section contains information about the savefile format.

# It should not be edited. Any modifications made to this section

# It should not be edited. Any modifications made to this section

# may make it impossible for the configuration tools to read

# may make it impossible for the configuration tools to read

# the savefile.

# the savefile.

cdl_savefile_version 1;

cdl_savefile_version 1;

cdl_savefile_command cdl_savefile_version {};

cdl_savefile_command cdl_savefile_version {};

cdl_savefile_command cdl_savefile_command {};

cdl_savefile_command cdl_savefile_command {};

cdl_savefile_command

cdl_savefile_command

cdl_configuration { description hardware template package };

cdl_configuration { description hardware template package };

cdl_savefile_command cdl_package { value_source user_value wizard_value inferred_value };

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_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_option { value_source user_value wizard_value inferred_value };

cdl_savefile_command cdl_interface { value_source user_value wizard_value inferred_value };

cdl_savefile_command cdl_interface { value_source user_value wizard_value inferred_value };

This section of the savefile is intended for use by the

This section of the savefile is intended for use by the

        configuration system, and should not be edited. If this

        configuration system, and should not be edited. If this

        section is edited then the various configuration tools may no

        section is edited then the various configuration tools may no

        longer be able to read in the modified savefile.

        longer be able to read in the modified savefile.

The header is followed by a section that defines the

The header is followed by a section that defines the

            configuration as a whole. A typical example would

            configuration as a whole. A typical example would

            be:

            be:

# ---- toplevel --------------------------------------------------------

# ---- toplevel --------------------------------------------------------

# This section defines the toplevel configuration object. The only

# This section defines the toplevel configuration object. The only

# values that can be changed are the name of the configuration and

# values that can be changed are the name of the configuration and

# the description field. It is not possible to modify the target,

# the description field. It is not possible to modify the target,

# the template or the set of packages simply by editing the lines

# the template or the set of packages simply by editing the lines

# below because these changes have wide-ranging effects. Instead

# below because these changes have wide-ranging effects. Instead

# the appropriate tools should be used to make such modifications.

# the appropriate tools should be used to make such modifications.

cdl_configuration eCos {

cdl_configuration eCos {

description ““ ;

description ““ ;

# These fields should not be modified.

# These fields should not be modified.

hardware    pid ;

hardware    pid ;

template    uitron ;

template    uitron ;

package -hardware CYGPKG_HAL_ARM current ;

package -hardware CYGPKG_HAL_ARM current ;

package -hardware CYGPKG_HAL_ARM_PID current ;

package -hardware CYGPKG_HAL_ARM_PID current ;

package -hardware CYGPKG_IO_SERIAL current ;

package -hardware CYGPKG_IO_SERIAL current ;

package -template CYGPKG_HAL current ;

package -template CYGPKG_HAL current ;

package -template CYGPKG_IO current ;

package -template CYGPKG_IO current ;

package -template CYGPKG_INFRA current ;

package -template CYGPKG_INFRA current ;

package -template CYGPKG_KERNEL current ;

package -template CYGPKG_KERNEL current ;

package -template CYGPKG_UITRON current ;

package -template CYGPKG_UITRON current ;

package -template CYGPKG_LIBC current ;

package -template CYGPKG_LIBC current ;

package -template CYGPKG_LIBM current ;

package -template CYGPKG_LIBM current ;

package -template CYGPKG_DEVICES_WALLCLOCK current ;

package -template CYGPKG_DEVICES_WALLCLOCK current ;

package -template CYGPKG_ERROR current ;

package -template CYGPKG_ERROR current ;

};

};

This section allows the configuration tools to reload the

This section allows the configuration tools to reload the

various packages that make up the configuration. Most of the information

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

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

to remove an existing one then the appropriate tools should be used

for this, for example:

for this, for example:

$ ecosconfig remove CYGPKG_LIBM

$ ecosconfig remove CYGPKG_LIBM

There are two fields which can be edited. Configurations have

There are two fields which can be edited. Configurations have

a name; in this case eCos. They can also have a description, which

a name; in this case eCos. They can also have a description, which

is some arbitrary text. The configuration tools do not make use

is some arbitrary text. The configuration tools do not make use

of these fields, they exist so that users can store additional information

of these fields, they exist so that users can store additional information

about a configuration.

about a configuration.

The toplevel section is followed by details of all the

The toplevel section is followed by details of all the

            conflicts (if any) in the configuration, for

            conflicts (if any) in the configuration, for

            example:

            example:

# ---- conflicts -------------------------------------------------------

# ---- conflicts -------------------------------------------------------

# There are 2 conflicts.

# There are 2 conflicts.

#

#

# option CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET

# option CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET

#   Property LegalValues

#   Property LegalValues

#   Illegal current value 100000

#   Illegal current value 100000

#   Legal values are: -90000 to 90000

#   Legal values are: -90000 to 90000

#

#

# option CYGSEM_LIBC_TIME_CLOCK_WORKING

# option CYGSEM_LIBC_TIME_CLOCK_WORKING

#   Property Requires

#   Property Requires

#   Requires constraint not satisfied: CYGFUN_KERNEL_THREADS_TIMER

#   Requires constraint not satisfied: CYGFUN_KERNEL_THREADS_TIMER

When editing a configuration you may end up with something

When editing a configuration you may end up with something

that is invalid. Any problems in the configuration will be reported

that is invalid. Any problems in the configuration will be reported

in the conflicts section. In this case there are two conflicts.

in the conflicts section. In this case there are two conflicts.

The option CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET has

The option CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET has

been given an illegal value: typically this would be fixed by searching

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

for the definition of that option later on in the savefile and modifying

the value. The second conflict is more interesting, an unsatisfied requires constraint.

the value. The second conflict is more interesting, an unsatisfied requires constraint.

Configuration options are not independent: disabling some functionality

Configuration options are not independent: disabling some functionality

in, say, the kernel, can have an impact elsewhere; in this case

in, say, the kernel, can have an impact elsewhere; in this case

the C library. The various dependencies between the options are

the C library. The various dependencies between the options are

specified by the component developers and checked by the configuration

specified by the component developers and checked by the configuration

system. In this case there are two obvious ways in which the conflict could

system. In this case there are two obvious ways in which the conflict could

be resolved: re-enabling CYGFUN_KERNEL_THREADS_TIMER,

be resolved: re-enabling CYGFUN_KERNEL_THREADS_TIMER,

or disabling CYGSEM_LIBC_TIME_CLOCK_WORKING.

or disabling CYGSEM_LIBC_TIME_CLOCK_WORKING.

Both of these options will be listed later on in the file.

Both of these options will be listed later on in the file.

Some care has to be taken when modifying configuration options,

Some care has to be taken when modifying configuration options,

to avoid introducing new conflict. For instance it is possible that

to avoid introducing new conflict. For instance it is possible that

there might be other options in the system which have a dependency

there might be other options in the system which have a dependency

on CYGSEM_LIBC_TIME_CLOCK_WORKING,

on CYGSEM_LIBC_TIME_CLOCK_WORKING,

so disabling that option may not be the best way to resolve the

so disabling that option may not be the best way to resolve the

conflict. Details of all such dependencies are provided in the appropriate

conflict. Details of all such dependencies are provided in the appropriate

places in the savefile.

places in the savefile.

It is not absolutely required that a configuration be conflict-free

It is not absolutely required that a configuration be conflict-free

before generating a build tree and building eCos. It is up to the

before generating a build tree and building eCos. It is up to the

developers of each component to decide what would happen if an attempt

developers of each component to decide what would happen if an attempt

is made to build eCos while there are still conflicts. In serious

is made to build eCos while there are still conflicts. In serious

cases there is likely to be a compile-time failure, or possibly

cases there is likely to be a compile-time failure, or possibly

a link-time failure. In less serious cases the system may build

a link-time failure. In less serious cases the system may build

happily and the application can be linked with the resulting library,

happily and the application can be linked with the resulting library,

but the component may not quite function as intended - although

but the component may not quite function as intended - although

it may still be good enough for the specific needs of the application.

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

It is also possible that everything builds and links, but once in

a while the system will unaccountably crash. Using a configuration

a while the system will unaccountably crash. Using a configuration

that still has conflicts is done entirely at the user’s

that still has conflicts is done entirely at the user’s

risk.

risk.

The bulk of the savefile lists the various packages,

The bulk of the savefile lists the various packages,

            components, and options, including their values and the

            components, and options, including their values and the

            various dependencies. A number of global options come

            various dependencies. A number of global options come

            first, especially those related to the build process such

            first, especially those related to the build process such

            as compiler flags. These are followed by the various

            as compiler flags. These are followed by the various

            packages, and the components and options within those

            packages, and the components and options within those

            packages, in order.

            packages, in order.

Packages, components and options are organized in a

Packages, components and options are organized in a

            hierarchy. If a particular component is disabled then all

            hierarchy. If a particular component is disabled then all

            options and sub-components below it will be inactive: any

            options and sub-components below it will be inactive: any

            changes made to these will have no effect. The savefile

            changes made to these will have no effect. The savefile

            contains information about the hierarchy in the form of

            contains information about the hierarchy in the form of

            comments, for example:

            comments, for example:

cdl_package CYGPKG_KERNEL ...

cdl_package CYGPKG_KERNEL ...

# >

# >

cdl_component CYGPKG_KERNEL_EXCEPTIONS ...

cdl_component CYGPKG_KERNEL_EXCEPTIONS ...

# >

# >

cdl_option CYGSEM_KERNEL_EXCEPTIONS_DECODE ...

cdl_option CYGSEM_KERNEL_EXCEPTIONS_DECODE ...

cdl_option CYGSEM_KERNEL_EXCEPTIONS_GLOBAL ...

cdl_option CYGSEM_KERNEL_EXCEPTIONS_GLOBAL ...

# <

# <

cdl_component CYGPKG_KERNEL_SCHED ...

cdl_component CYGPKG_KERNEL_SCHED ...

# >