URL
https://opencores.org/ocsvn/openrisc/openrisc/trunk
Subversion Repositories openrisc
[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [user-guide/] [editing-an-ecos-savefile.html] - Rev 174
Compare with Previous | Blame | View Log
<!-- Copyright (C) 2003 Red Hat, 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 is obtained from the copyright holder. -->
<HTML
><HEAD
><TITLE
>Editing an eCos Savefile</TITLE
><meta name="MSSmartTagsPreventParsing" content="TRUE">
<META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="eCos User Guide"
HREF="ecos-user-guide.html"><LINK
REL="UP"
TITLE="Manual Configuration"
HREF="manual-configuration.html"><LINK
REL="PREVIOUS"
TITLE="Fine-grained Configuration"
HREF="fine-grained-configuration.html"><LINK
REL="NEXT"
TITLE="Editing the Sources"
HREF="editing-the-sources.html"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>eCos User Guide</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="fine-grained-configuration.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 28. Manual Configuration</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="editing-the-sources.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="EDITING-AN-ECOS-SAVEFILE">Editing an <SPAN
CLASS="PRODUCTNAME"
>eCos</SPAN
> Savefile</H1
><P
>The <SPAN
CLASS="PRODUCTNAME"
>eCos</SPAN
> configuration information is held in a single
savefile, typically <TT
CLASS="FILENAME"
>ecos.ecc</TT
>, which can
be generated by either the GUI configuration tool or by the
command line <B
CLASS="COMMAND"
>ecosconfig</B
> 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.</P
><P
>An <SPAN
CLASS="PRODUCTNAME"
>eCos</SPAN
> savefile is actually a script in the <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Tcl</I
></SPAN
> 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<TT
CLASS="LITERAL"
> CYGDAT_UITRON_TASK_EXTERNS</TT
>,
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 <SPAN
CLASS="PRODUCTNAME"
>eCos</SPAN
> savefile actually consists
of such comments, to make it easier to edit.</P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN2721">Header</H2
><P
>An <SPAN
CLASS="PRODUCTNAME"
>eCos</SPAN
> savefile begins with a header, which typically
looks something like this:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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 };
</PRE
></TD
></TR
></TABLE
><P
>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.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN2727">Toplevel Section</H2
><P
>The header is followed by a section that defines the
configuration as a whole. A typical example would
be:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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 ;
};
</PRE
></TD
></TR
></TABLE
><P
>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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>$ ecosconfig remove CYGPKG_LIBM</PRE
></TD
></TR
></TABLE
><P
>There are two fields which can be edited. Configurations have
a name; in this case <SPAN
CLASS="PRODUCTNAME"
>eCos</SPAN
>. 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.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN2735">Conflicts Section</H2
><P
>The toplevel section is followed by details of all the
conflicts (if any) in the configuration, for
example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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
</PRE
></TD
></TR
></TABLE
><P
>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 <TT
CLASS="LITERAL"
>CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET</TT
> 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 <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>requires</I
></SPAN
> 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 <TT
CLASS="LITERAL"
>CYGFUN_KERNEL_THREADS_TIMER</TT
>,
or disabling <TT
CLASS="LITERAL"
>CYGSEM_LIBC_TIME_CLOCK_WORKING</TT
>.
Both of these options will be listed later on in the file.</P
><P
>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 <TT
CLASS="LITERAL"
>CYGSEM_LIBC_TIME_CLOCK_WORKING</TT
>,
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.</P
><P
>It is not absolutely required that a configuration be conflict-free
before generating a build tree and building <SPAN
CLASS="PRODUCTNAME"
>eCos</SPAN
>. It is up to the
developers of each component to decide what would happen if an attempt
is made to build <SPAN
CLASS="PRODUCTNAME"
>eCos</SPAN
> 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.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN2749">Data Section</H2
><P
>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.</P
><P
>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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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 ...
# <
# <
</PRE
></TD
></TR
></TABLE
><P
>This corresponds to the following hierarchy:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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
</PRE
></TD
></TR
></TABLE
><P
>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 <SPAN
CLASS="PRODUCTNAME"
>eCos</SPAN
> savefiles. The information is not used by the
configuration tools themselves since they obtain the
hierarchy from the original CDL scripts.</P
><P
>Each configurable entity is preceded by a comment, of
the following form:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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 {
...
};
</PRE
></TD
></TR
></TABLE
><P
>This provides a short textual alias
<TT
CLASS="LITERAL"
>Kernel schedulers</TT
> 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.</P
><P
>Each configurable entity takes the form:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="SCREEN"
><type> <name> {
<data>
};</PRE
></TD
></TR
></TABLE
><P
>Configurable entities may not be active. This can be either
because the parent is disabled or inactive, or because there are
one or more <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>active_if</I
></SPAN
> properties. Modifying
the value of an inactive entity has no effect on the configuration,
so this information is provided first:</P
><P
></P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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
...
}; </PRE
></TD
></TR
></TABLE
><P
>For <TT
CLASS="LITERAL"
>CYGIMP_IDLE_THREAD_YIELD</TT
> 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.</P
><P
>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.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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.
...
}; </PRE
></TD
></TR
></TABLE
><P
>The version of a package can be changed using e.g.: </P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="SCREEN"
>$ ecosconfig version 1.3 CYGPKG_KERNEL</PRE
></TD
></TR
></TABLE
><P
>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.</P
><P
>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.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="SCREEN"
> cdl_component CYGPKG_HAL_COMMON_INTERRUPTS {
# There is no associated value.
}; </PRE
></TD
></TR
></TABLE
><P
>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 <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>requires</I
></SPAN
> constraint.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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
}; </PRE
></TD
></TR
></TABLE
><P
>A special type of calculated value is the <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>interface</I
></SPAN
>.
The value of an interface is the number of active and enabled options
which <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>implement</I
></SPAN
> 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. </P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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 </PRE
></TD
></TR
></TABLE
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="SCREEN"
># The following properties are affected by this value
# interface CYGINT_KERNEL_SCHEDULER
# Requires: 1 == CYGINT_KERNEL_SCHEDULER
}; </PRE
></TD
></TR
></TABLE
><P
>If the configurable entity is modifiable then there will be
lines like the following:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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
...
}; </PRE
></TD
></TR
></TABLE
><P
>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.</P
><P
>In the above example the user has not modified this particular
option, as indicated by the comment and by the commented-out <TT
CLASS="LITERAL"
>user_value</TT
> line.
To disable this option the file should be edited to:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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
...
} </PRE
></TD
></TR
></TABLE
><P
>The comment preceding the <TT
CLASS="LITERAL"
>user_value
0</TT
> 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.</P
><P
>Much the same process should be used for options with the
data flavor, for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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
}; </PRE
></TD
></TR
></TABLE
><P
>can be changed to:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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 }; </PRE
></TD
></TR
></TABLE
><P
>Note that the original text provides the default value in
the <TT
CLASS="LITERAL"
>user_value</TT
> comment,
on the assumption that the desired new value is likely to be similar
to the default value. The <TT
CLASS="LITERAL"
>value_source</TT
> comment
does not need to be updated, it will be fixed up if the savefile
is fed back into the configuration system and regenerated.</P
><P
>For options with the booldata flavor, the <TT
CLASS="LITERAL"
>user_value</TT
> line
needs take two arguments. The first argument is for the boolean
part, the second for the data part. For example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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”
...
}; </PRE
></TD
></TR
></TABLE
><P
>could be changed to:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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”
...
}; </PRE
></TD
></TR
></TABLE
><P
>or alternatively, if the whole component should be disabled,
to:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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”
...
}; </PRE
></TD
></TR
></TABLE
><P
>Some options take values that span multiple lines. An example
would be:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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 ),”
}; </PRE
></TD
></TR
></TABLE
><P
>Setting a user value for this option involves uncommenting
and modifying all relevant lines, for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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 ),”
}; </PRE
></TD
></TR
></TABLE
><P
>In such cases appropriate care has to be taken to preserve
Tcl syntax, as discussed below.</P
><P
>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 <TT
CLASS="LITERAL"
>default</TT
>. If a
configuration involves conflicts and the configuration
system’s inference engine is allowed to resolve these
automatically then it may provide an
<TT
CLASS="LITERAL"
>inferred</TT
> value instead, for
example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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
...
}; </PRE
></TD
></TR
></TABLE
><P
>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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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
...
}; </PRE
></TD
></TR
></TABLE
><P
>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.</P
><P
>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.</P
><P
>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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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
...
}; </PRE
></TD
></TR
></TABLE
><P
>then the inferred value could be restored by commenting out
or removing the <TT
CLASS="LITERAL"
>user_value</TT
> line:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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
...
}; </PRE
></TD
></TR
></TABLE
><P
>This is fine for simple values. However if the value is complicated
then there is a problem: commenting out the <TT
CLASS="LITERAL"
>user_value</TT
> 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 <TT
CLASS="LITERAL"
>user_value</TT
> but
explicitly set the <TT
CLASS="LITERAL"
>value_source</TT
> line,
for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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
...
}; </PRE
></TD
></TR
></TABLE
><P
>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 <TT
CLASS="LITERAL"
>value_source</TT
> line
can be commented out again. If there is no explicit <TT
CLASS="LITERAL"
>value_source</TT
> 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.</P
><P
>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.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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
}; </PRE
></TD
></TR
></TABLE
><P
>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 “<TT
CLASS="LITERAL"
>hello
world</TT
>” 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.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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
}; </PRE
></TD
></TR
></TABLE
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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”
...
}; </PRE
></TD
></TR
></TABLE
><P
>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.</P
><P
>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.</P
><P
>Following the value-related fields for a given option, any <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>requires</I
></SPAN
> 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 <SPAN
CLASS="PRODUCTNAME"
>eCos</SPAN
> 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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="SCREEN"
> cdl_option CYGSEM_LIBC_TIME_TIME_WORKING {
...
# Requires: CYGPKG_DEVICES_WALLCLOCK
# CYGPKG_DEVICES_WALLCLOCK == current
# --> 1
}; </PRE
></TD
></TR
></TABLE
><P
>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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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
}; </PRE
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN2847">Tcl Syntax</H2
><P
><SPAN
CLASS="PRODUCTNAME"
>eCos</SPAN
> 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 <TT
CLASS="LITERAL"
>cdl_option</TT
> and <TT
CLASS="LITERAL"
>cdl_configuration</TT
>.
In many cases this is an implementation detail that can be safely
ignored while editing a savefile: simply replacing a <TT
CLASS="LITERAL"
>1</TT
> with
a <TT
CLASS="LITERAL"
>0</TT
> 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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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 \];”
}; </PRE
></TD
></TR
></TABLE
><P
>The backslash at the end of the <TT
CLASS="LITERAL"
>user_value</TT
> 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 <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>command
substitution</I
></SPAN
> 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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="SCREEN"
> static char vpool1[ 2000 ], \
vpool2[ 2000 ], \
vpool3[ 2000 ]; </PRE
></TD
></TR
></TABLE
><P
>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 <B
CLASS="COMMAND"
>cdl_option</B
> 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 <TT
CLASS="LITERAL"
>$</TT
> characters then
these would have to be treated specially as well, via a backslash escape.</P
><P
>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.</P
><P
>When the Tcl interpreter is passed some data such as <TT
CLASS="LITERAL"
>puts
Hello</TT
>, 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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="SCREEN"
>puts Hello
set x 42 </PRE
></TD
></TR
></TABLE
><P
>will result in two separate commands being executed. The first
command is <TT
CLASS="LITERAL"
>puts</TT
> and is passed a
single argument, <TT
CLASS="LITERAL"
>Hello</TT
>. The second
command is <TT
CLASS="LITERAL"
>set</TT
> and is passed two
arguments, <TT
CLASS="LITERAL"
>x</TT
> and <TT
CLASS="LITERAL"
>42</TT
>.
The intervening newline character serves to terminate the first
command, and a semi-colon separator could be used instead: </P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>puts Hello;set x 42</PRE
></TD
></TR
></TABLE
><P
>Any white space surrounding the semicolon is just ignored
because it does not serve to separate arguments.</P
><P
>Now consider the following:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="SCREEN"
>set x Hello world</PRE
></TD
></TR
></TABLE
><P
>This is not valid Tcl. It is an attempt to invoke the <TT
CLASS="LITERAL"
>set</TT
> command
with three arguments: <TT
CLASS="LITERAL"
>x</TT
>, <TT
CLASS="LITERAL"
>Hello</TT
>,
and <TT
CLASS="LITERAL"
>world</TT
>. The <TT
CLASS="LITERAL"
>set</TT
> only
takes two arguments, a variable name and a value, so it is necessary
to combine the data into a single argument by quoting:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>set x “Hello world”</PRE
></TD
></TR
></TABLE
><P
>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 <TT
CLASS="LITERAL"
>set</TT
> command
is just <TT
CLASS="LITERAL"
>Hello world</TT
> without the
quote characters. This can be significant in the context of <SPAN
CLASS="PRODUCTNAME"
>eCos</SPAN
> savefiles.
For instance, consider the following configuration option:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="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\””
}; </PRE
></TD
></TR
></TABLE
><P
>The desired value of the configuration option should be a
valid C string, complete with quote characters. If the savefile
was edited to: </P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="SCREEN"
> cdl_option CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE {
# Flavor: data
user_value “/dev/ttydiag”
# value_source default
# Default value: “\”/dev/ttydiag\””
}; </PRE
></TD
></TR
></TABLE
><P
>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 <TT
CLASS="LITERAL"
>#define</TT
> would
be generated in the configuration header file:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE /dev/ttydiag </PRE
></TD
></TR
></TABLE
><P
>This is likely to cause a compile-time failure when building
<SPAN
CLASS="PRODUCTNAME"
>eCos</SPAN
>.</P
><P
>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 <SPAN
CLASS="PRODUCTNAME"
>eCos</SPAN
> savefiles, for instance, in the <TT
CLASS="LITERAL"
>CYGDAT_UITRON_MEMPOOLVAR_EXTERNS</TT
> example
mentioned earlier. Newline or semicolon characters do not terminate
the current command in such cases.</P
><P
>The Tcl interpreter supports much the same forms of backslash
substitution as other common programming languages. Some backslash
sequences such as <TT
CLASS="LITERAL"
>\n</TT
> will
be replaced by the appropriate character. The sequence <TT
CLASS="LITERAL"
>\\</TT
> 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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>puts “Hello\nworld\n”
puts \
“Hello
world
“</PRE
></TD
></TR
></TABLE
><P
>In addition to quote and backslash characters, the Tcl interpreter
treats square brackets, the <TT
CLASS="LITERAL"
>$</TT
> character,
and braces specially. Square brackets are used for command substitution,
for example:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>puts “The answer is [expr 6 * 9]”</PRE
></TD
></TR
></TABLE
><P
>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 <TT
CLASS="LITERAL"
>expr 6 * 9</TT
>,
yielding a result of 54, and then the Tcl interpreter will execute
<TT
CLASS="LITERAL"
>puts “The answer is 54”</TT
>. 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.</P
><P
>Command line substitution is very unlikely to prove useful
in the context of an <SPAN
CLASS="PRODUCTNAME"
>eCos</SPAN
> 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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> cdl_option CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS {
...
user_value \
“static char fpool1[ 2000 ],
fpool2[ 2000 ];”
...
};</PRE
></TD
></TR
></TABLE
><P
>The Tcl interpreter will interpret the square brackets as
an attempt at command substitution and hence it will attempt to
execute the command <TT
CLASS="LITERAL"
>2000</TT
> 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:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
> cdl_option CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS {
...
user_value \
“static char fpool1\[ 2000 \],
fpool2\[ 2000 \];”
...
}; </PRE
></TD
></TR
></TABLE
><P
>Similarly the <TT
CLASS="LITERAL"
>$</TT
> character
is used in Tcl scripts to perform variable substitution:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>set x [expr 6 * 9]
puts “The answer is $x” </PRE
></TD
></TR
></TABLE
><P
>Variable substitution, like command substitution, is very
unlikely to prove useful in the context of an <SPAN
CLASS="PRODUCTNAME"
>eCos</SPAN
> savefile. Should
it be necessary to have a <TT
CLASS="LITERAL"
>$</TT
> character
in configuration data then again a backslash escape needs to be
used.</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_option FOODAT_MONITOR_PROMPT {
...
user_value “\$ “
...
};</PRE
></TD
></TR
></TABLE
><P
>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 <TT
CLASS="LITERAL"
>CYGDAT_UITRON_MEMPOOL_EXTERNFIXED_EXTERNS</TT
> value
could be written as:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_option CYGDAT_UITRON_MEMPOOLFIXED_EXTERNS {
...
user_value \
{static char fpool1[ 2000 ],
fpool2[ 2000 ];}
...
};</PRE
></TD
></TR
></TABLE
><P
>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.</P
><P
>At this stage it is worth noting that the basic format of
each configuration option in the savefile makes use of braces:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_option <name> {
...
};</PRE
></TD
></TR
></TABLE
><P
>The configuration system extends the Tcl language with a small
number of additional commands such as <TT
CLASS="LITERAL"
>cdl_option</TT
>.
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 <TT
CLASS="LITERAL"
>user_value</TT
> and <TT
CLASS="LITERAL"
>value_source</TT
>.
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.</P
><P
>Comments in Tcl scripts are introduced by a hash character <TT
CLASS="LITERAL"
>#</TT
>.
However, a hash character only introduces a comment if it occurs
where a command is expected. Consider the following:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
># This is a comment
puts “Hello” # world </PRE
></TD
></TR
></TABLE
><P
>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 <TT
CLASS="LITERAL"
>puts</TT
> command with
three arguments: <TT
CLASS="LITERAL"
>Hello</TT
>, <TT
CLASS="LITERAL"
>#</TT
> and <TT
CLASS="LITERAL"
>world</TT
>.
These are not valid arguments for the <TT
CLASS="LITERAL"
>puts</TT
> command
so an error will be raised.</P
><P
>If the second line was rewritten as:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>puts “Hello”; # world</PRE
></TD
></TR
></TABLE
><P
>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.</P
><P
>This handling of comments can lead to subtle behaviour. Consider
the following:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_option WHATEVER {
# This is a comment }
user_value 42
...
}</PRE
></TD
></TR
></TABLE
><P
>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 <TT
CLASS="LITERAL"
>cdl_option</TT
> is <TT
CLASS="LITERAL"
>\n # This is a comment</TT
> . 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 <TT
CLASS="LITERAL"
>user_value</TT
>. 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.</P
><P
>This should be sufficient information about Tcl to allow for
safe editing of <SPAN
CLASS="PRODUCTNAME"
>eCos</SPAN
> savefiles. Further information is available
from a wide variety of sources, for example the book <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Tcl
and the Tk Toolkit </I
></SPAN
>by John K Ousterhout.</P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="fine-grained-configuration.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="ecos-user-guide.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="editing-the-sources.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Fine-grained Configuration</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="manual-configuration.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Editing the Sources</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>