configuration.sgml

eCos操作系统源码

restore the configuration. Default values on the other hand are
entirely deterministic so there is no actual need for the values
to be listed in the savefile. However, the default value can be
very useful information so it is provided in a comment.</PARA>
<PARA>Occasionally the user will want to do some experimentation,
and temporarily switch an option from a user value back to a default
or inferred one to see what the effect would be. This could be achieved
by simply commenting out the user value. For instance, if the current
savefile contains:</PARA>
<SCREEN> 
cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT {     
# Flavor: bool     
user_value 1     
# The inferred value should not be edited directly.     
inferred_value 0     
# value_source user     
# Default value: 1     
... 
}; 

</SCREEN>
<PARA>then the inferred value could be restored by commenting out
or removing the <literal>user_value</literal> line:</PARA>
<SCREEN> 
cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT {     
# Flavor: bool     
# user_value 1     
# The inferred value should not be edited directly.     
inferred_value 0     
# value_source user     
# Default value: 1     
... 
}; 

</SCREEN>
<PARA>This is fine for simple values. However if the value is complicated
then there is a problem: commenting out the <LITERAL>user_value</LITERAL> line
or lines means that the user value becomes invisible to the configuration system,
so if the savefile is loaded and then regenerated the information
will be lost. An alternative approach is to keep the <LITERAL>user_value</LITERAL> but
explicitly set the <LITERAL>value_source</LITERAL> line,
for example:</PARA>
<SCREEN>

cdl_option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT {     
# Flavor: bool     
user_value 1     
# The inferred value should not be edited directly.     
inferred_value 0     
value_source inferred     
# Default value: 1     
... 
}; 

</SCREEN>
<PARA>In this case the configuration system will use the inferred
value for the purposes of dependency analysis etc., even though
a user value is present. To restore the user value the <LITERAL>value_source</LITERAL> line
can be commented out again. If there is no explicit <LITERAL>value_source</LITERAL> then
the configuration system will just use the highest priority one:
the user value if it exists; otherwise the inferred value if it
exists; otherwise the default value which always exists.</PARA>
<PARA>The default value for an option can be a simple constant,
or it can be an expression involving other options. In the latter
case the expression will be listed, together with the values for
all options referenced in the expression and the current result
of evaluating that expression. This is for informational purposes
only, the default value is always recalculated deterministically
when loading in a savefile.</PARA>
<SCREEN>

cdl_option CYGBLD_GLOBAL_COMMAND_PREFIX {     
# Flavor: data     
# No user value, uncomment the following line to provide one.     
# user_value arm-elf     
# value_source default     
# Default value:  CYGHWR_THUMB ? &ldquo;thumb-elf&rdquo; : &ldquo;arm-elf&rdquo;     
#     CYGHWR_THUMB == 0     
#   --&gt; arm-elf 
}; 

</SCREEN>
<PARA>For options with the data or booldata flavor, there are likely
to be constraints on the possible values. If the value is supposed
to be a number in a given range and a user value of &ldquo;<LITERAL>hello
world</LITERAL>&rdquo; is provided instead then there
are likely to be compile-time failures. Component developers can
specify constraints on the legal values, and these will be listed
in the savefile.</PARA>
<SCREEN> 
cdl_option X_TLOSS {     
# Flavor: data     
# No user value, uncomment the following line to provide one.     
# user_value 1.41484755040569E+16     
# value_source default     
# Default value: 1.41484755040569E+16     
# Legal values: 1 to 1e308 
};

</SCREEN>
<SCREEN>cdl_component CYGNUM_LIBM_COMPATIBILITY {     
# Flavor: booldata     
# No user value, uncomment the following line to provide one.     
# user_value 1 POSIX     
# value_source default     
# Default value: 1 POSIX     
# Legal values:  &ldquo;POSIX&rdquo; &ldquo;IEEE&rdquo; &ldquo;XOPEN&rdquo; &ldquo;SVID&rdquo;     
... 
};

</SCREEN>
<PARA>In some cases the legal values list may be an expression involving
other options. If so then the current values of the referenced options
will be listed, together with the result of evaluating the list
expression, just as for default value expressions.</PARA>
<PARA>If an illegal value is provided then this will result in a
conflict, listed in the conflicts section of the savefile. For more
complicated options a simple legal values list is not sufficient
to allow the current value to be validated, and the configuration
system will be unable to flag conflicts. This issue will be addressed in
future releases of the configuration system.</PARA>
<PARA>Following the value-related fields for a given option, any <EMPHASIS>requires</EMPHASIS> constraints belonging
to this option will be listed. These constraints are only effective
if the option is active and, for bool and booldata flavors, enabled.
If some aspect of <productname>eCos</productname> functionality is inactive or disabled then
it cannot impose any constraints on the rest of the system. As usual,
the full expression will be listed followed by the current values
of all options that are referenced and the result of evaluating
the expression:</PARA>
<SCREEN>

cdl_option CYGSEM_LIBC_TIME_TIME_WORKING {     
...     
# Requires: CYGPKG_DEVICES_WALLCLOCK     
#     CYGPKG_DEVICES_WALLCLOCK == current     
#   --&gt; 1 
};

</SCREEN>
<PARA>When modifying the value of an option it is useful to know
not only what constraints the option imposes on the rest of the
system but also what other options in the system depend in some
way on this one. The savefile provides this information:</PARA>
<SCREEN>cdl_option CYGFUN_KERNEL_THREADS_TIMER {     
...     
# The following properties are affected by this value     
# option CYGMFN_KERNEL_SYNCH_CONDVAR_TIMED_WAIT     
#     Requires: CYGFUN_KERNEL_THREADS_TIMER     
# option CYGIMP_UITRON_STRICT_CONFORMANCE     
#     Requires: CYGFUN_KERNEL_THREADS_TIMER     
# option CYGSEM_LIBC_TIME_CLOCK_WORKING     
#     Requires: CYGFUN_KERNEL_THREADS_TIMER 
}; 

</SCREEN>
</SECT2>
<SECT2>
<TITLE>Tcl Syntax</TITLE>
<PARA><productname>eCos</productname> savefiles are implemented as Tcl scripts, and are read
in by running the data through a standard Tcl interpreter that has
been extended with a small number of additional commands such as <LITERAL>cdl_option</LITERAL> and <LITERAL>cdl_configuration</LITERAL>.
In many cases this is an implementation detail that can be safely
ignored while editing a savefile: simply replacing a <LITERAL>1</LITERAL> with
a <LITERAL>0</LITERAL> to disable some functionality
is not going to affect whether or not the savefile is still a valid
Tcl script and can be processed by a Tcl interpreter. However, there
are more complicated cases where an understanding of Tcl syntax
is at least desirable, for example:</PARA>
<SCREEN>

cdl_option CYGDAT_UITRON_MEMPOOLVAR_EXTERNS {
     # Flavor: data
     user_value \
      &ldquo;static char vpool1\[ 2000 \], \\
      vpool2\[ 2000 \], \\
       vpool3\[ 2000 \];&rdquo;     
# value_source default     
# Default value: \
     #     &ldquo;static char vpool1\[ 2000 \], \\
     #      vpool2\[ 2000 \], \\
    #      vpool3\[ 2000 \];&rdquo; 
};

</SCREEN>
<PARA>The backslash at the end of the <LITERAL>user_value</LITERAL> line
is processed by the Tcl interpreter as a line continuation character.
The quote marks around the user data are also interpreted by the
Tcl interpreter and serve to turn the entire data field into a single
argument. The backslashes preceding the opening and closing square
brackets prevent the Tcl interpreter from treating these characters
specially, otherwise there would be an attempt at <EMPHASIS>command
substitution</EMPHASIS> as described below. The double backslashes
at the end of each line of the data will be turned into a single
backslash by the Tcl interpreter, rather than escaping the newline
character, so that the actual data seen by the configuration system
is:</PARA>
<SCREEN>

static char vpool1[ 2000 ], \
      vpool2[ 2000 ], \
      vpool3[ 2000 ];

</SCREEN>
<PARA>This is of course the data that should end up in the &micro;ITRON
configuration header file. The opening and closing braces surrounding
the entire body of the option data are also significant and cause
this body to be passed as a single argument to the <command>cdl_option</command> command.
The closing semicolon is optional in this example, but provides
a small amount of additional robustness if the savefile is edited
such that it is no longer a valid Tcl script. If the data contained
any <LITERAL>$</LITERAL> characters then
these would have to be treated specially as well, via a backslash escape.</PARA>
<PARA>In spite of what all the above might seem to suggest, Tcl
is actually a very simple yet powerful scripting language: the syntax
is defined by just eleven rules. On occasion this simplicity means
that Tcl&rsquo;s behaviour is subtly different from other languages,
which can confuse newcomers.</PARA>
<PARA>When the Tcl interpreter is passed some data such as <LITERAL>puts
Hello</LITERAL>, it splits this data into a command and its
arguments. The command will be terminated by a newline or by a semicolon,
unless one of the quoting mechanisms is used. The command and each
of its arguments are separated by white space. So in the following
example:</PARA>
<SCREEN>puts Hello 
set x 42 </SCREEN>
<PARA>will result in two separate commands being executed. The first
command is <LITERAL>puts</LITERAL> and is passed a
single argument, <LITERAL>Hello</LITERAL>. The second
command is <LITERAL>set</LITERAL> and is passed two
arguments, <LITERAL>x</LITERAL> and <LITERAL>42</LITERAL>.
The intervening newline character serves to terminate the first
command, and a semi-colon separator could be used instead: </PARA>
<programlisting>puts Hello;set x 42</programlisting>
<PARA>Any white space surrounding the semicolon is just ignored
because it does not serve to separate arguments.</PARA>
<PARA>Now consider the following:</PARA>
<SCREEN>set x Hello world</SCREEN>
<PARA>This is not valid Tcl. It is an attempt to invoke the <LITERAL>set</LITERAL> command
with three arguments: <LITERAL>x</LITERAL>, <LITERAL>Hello</LITERAL>,
and <LITERAL>world</LITERAL>. The <LITERAL>set</LITERAL> only
takes two arguments, a variable name and a value, so it is necessary
to combine the data into a single argument by quoting:</PARA>
<PROGRAMLISTING>set x &ldquo;Hello world&rdquo;</PROGRAMLISTING>
<PARA>When the Tcl interpreter encounters the first quote character
it treats all subsequent data up to but not including the closing
quote as part of the current argument. The quote marks are removed
by the interpreter, so the second argument passed to the <LITERAL>set</LITERAL> command
is just <LITERAL>Hello world</LITERAL> without the
quote characters. This can be significant in the context of <productname>eCos</productname> savefiles.
For instance, consider the following configuration option:</PARA>
<SCREEN>

cdl_option CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE {     
# Flavor: data     
# No user value, uncomment the following line to provide one.     
# user_value &ldquo;\&rdquo;/dev/ttydiag\&rdquo;&rdquo;     
# value_source default     
# Default value: &ldquo;\&rdquo;/dev/ttydiag\&rdquo;&rdquo; 
}; 

</SCREEN>
<PARA>The desired value of the configuration option should be a
valid C string, complete with quote characters. If the savefile
was edited to: </PARA>
<SCREEN>

cdl_option CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE {     
# Flavor: data     
user_value &ldquo;/dev/ttydiag&rdquo;     
# value_source default     
# Default value: &ldquo;\&rdquo;/dev/ttydiag\&rdquo;&rdquo; 
}; 

</SCREEN>
<PARA>then the Tcl interpreter would remove the quote marks when
the savefile is read back in, so the option&rsquo;s value would
not have any quote marks and would not be a valid C string. The
configuration system is not yet able to perform the required validation
so the following <LITERAL>#define</LITERAL> would
be generated in the configuration header file:</PARA>
<PROGRAMLISTING>#define CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE /dev/ttydiag </PROGRAMLISTING>
<PARA>This is likely to cause a compile-time failure when building
<productname>eCos</productname>.</PARA>
<PARA>A quoted argument continues until the closing quote character
is encountered, which means that it can span multiple lines. This
can also be encountered in <productname>eCos</productname> savefiles, for instance, in the <literal>CYGDAT_UITRON_MEMPOOLVAR_EXTERNS</literal> example
mentioned earlier. Newline or semicolon characters do not terminate
the current command in such cases.</PARA>
<PARA>The Tcl interpreter supports much the same forms of backslash
substitution as other common programming languages. Some backslash
sequences su