configuration.sgml

eCos操作系统源码

<PARA>switching to a different template</PARA>
</LISTITEM>
<LISTITEM>
<PARA>adding or removing a package</PARA>
</LISTITEM>
<LISTITEM>
<PARA>changing the version of a package</PARA>
</LISTITEM>
</ORDEREDLIST>
<PARA>Whenever <COMMAND>ecosconfig</COMMAND> generates or
	  updates an <productname>eCos</productname> configuration, it generates a configuration
	  save file.</PARA>
<PARA>Suppose that the configuration was first created using
	  the following command line: </PARA>
<SCREEN>$ ecosconfig new stdeval1</SCREEN>
<PARA>To change the target hardware to the Cogent CMA28x
	  PowerPC board, the following command would be needed:
	</PARA>
<SCREEN>$ ecosconfig target cma28x</SCREEN>
<PARA>To switch to the PowerPC simulator instead: </PARA>
<SCREEN>$ ecosconfig target psim</SCREEN>
<PARA>As the hardware changes, hardware-related packages such as
the HAL packages and device drivers will be added to and removed
from the configuration as appropriate. </PARA>
<PARA>To remove any package from the current configuration, use
the <COMMAND>remove</COMMAND> command: </PARA>
<SCREEN>$ ecosconfig remove uitron</SCREEN>
<PARA>You can disable multiple packages using multiple arguments,
for example: </PARA>
<SCREEN>$ ecosconfig remove uitron libm</SCREEN>
<PARA>If this turns out to have been a mistake then you can
	  re-enable one or more packages with the
	  <COMMAND>add</COMMAND> command: </PARA>
<SCREEN>$ ecosconfig add libm</SCREEN>
<PARA>Changing the desired version for a package is also
	  straightforward:</PARA>
<SCREEN>$ ecosconfig version v2_1 kernel</SCREEN>
<PARA>It is necessary to regenerate the build tree and header
	  files following any changes to the configuration before
	  rebuilding <productname>eCos</productname>:</PARA>
<SCREEN>$ ecosconfig tree</SCREEN>
</SECT1>
<SECT1 id="fine-grained-configuration">
<TITLE>Fine-grained Configuration</TITLE>
<PARA><COMMAND>ecosconfig</COMMAND> only provides
	  coarse-grained control over the configuration: the hardware,
	  the template and the packages that should be built. Unlike
	  the Configuration Tool,
	  <COMMAND>ecosconfig</COMMAND> does not provide
	  any facilities for manipulating finer-grained <!--
	  <index></index> -->configuration options such as how many
	  priority levels the scheduler should support. There are
	  hundreds of these options, and manipulating them by means of
	  command line arguments would not be sensible. </PARA>
<PARA>In the current system fine-grained configuration options may
be manipulated by manual editing of the configuration file. When
a file has been edited in this way, the <COMMAND>ecosconfig</COMMAND> tool
should be used to check the configuration for any conflicts which
may have been introduced:</PARA>
<SCREEN>$ ecosconfig check</SCREEN>
<PARA>The <COMMAND>check</COMMAND> command will list
all conflicts and will also rewrite the configuration file, propagating
any changes which affect other options. The user may choose to resolve
the conflicts either by re-editing the configuration file manually
or by invoking the inference engine using the <COMMAND>resolve</COMMAND> command:</PARA>
<SCREEN>$ ecosconfig resolve</SCREEN>
<PARA>The  <COMMAND>resolve</COMMAND> command will
list all conflicts which can be resolved and save the resulting changes
to the configuration.</PARA>
<PARA>It is necessary to regenerate the build tree and header files
following any changes to the configuration before rebuilding <productname>eCos</productname>:</PARA>
<SCREEN>$ ecosconfig tree</SCREEN>
<PARA>All the configuration options and their descriptions are listed
in the <citetitle><productname>eCos</productname> Reference Manual</citetitle>. </PARA>
</SECT1>
<SECT1 id="editing-an-ecos-savefile">
<TITLE>Editing an <productname>eCos</productname> Savefile</TITLE>
<PARA>The <productname>eCos</productname> configuration information is held in a single
	  savefile, typically <FILENAME>ecos.ecc</FILENAME>, which can
	  be generated by either the GUI configuration tool or by the
	  command line <command>ecosconfig</command> tool. The file
	  normally exists at the top level of the build tree. It is a
	  text file, allowing the various configurations options to be
	  edited inside a suitable text editor or by other programs or
	  scripts, as well as in the GUI config tool.</PARA>
<PARA>An <productname>eCos</productname> savefile is actually a script in the <EMPHASIS>Tcl</EMPHASIS> programming
language, so any modifications to the file need to preserve Tcl
syntax. For most configuration options, any modifications will be
trivial and there is no need to worry about Tcl syntax. For example,
changing a 1 to a 0 to disable an option.  For more complicated
options, for example<literal> CYGDAT_UITRON_TASK_EXTERNS</literal>,
which involves some lines of C code, more care has
to be taken. If an edited savefile is no longer a valid Tcl script
then the configuration tools will be unable to read back the data
for further processing, for example to generate a build tree. An
outline of Tcl syntax is given below. One point worth noting here
is that a line that begins with a &ldquo;#&rdquo; is
usually a comment, and the bulk of an <productname>eCos</productname> savefile actually consists
of such comments, to make it easier to edit.</PARA>
<SECT2>
<TITLE>Header</TITLE>
<PARA>An <productname>eCos</productname> savefile begins with a header, which typically
	    looks something like this:</PARA>
<SCREEN># eCos saved configuration
# ---- commands -------------------------------------------------------- 
# This section contains information about the savefile format. 
# It should not be edited. Any modifications made to this section 
# may make it impossible for the configuration tools to read 
# the savefile.

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

cdl_configuration eCos {     
description &ldquo;&ldquo; ;         

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