+++ /dev/null
-<!-- 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
->
\ No newline at end of file
projects / karo-tx-redboot.git / blobdiff