language.values.html

ecos源代码包

CLASS="APPLICATION"
>CDL</SPAN
> expressions will evaluate
to <TT
CLASS="LITERAL"
>0</TT
>. This is the same behavior as for inactive
options. The data part is not relevant. The <TT
CLASS="LITERAL"
>none</TT
>
and <TT
CLASS="LITERAL"
>data</TT
> flavors specify that the option is always
enabled, in which case this rule is not applicable.</P
></LI
><LI
><P
>If an option is enabled then any references to that option in <SPAN
CLASS="APPLICATION"
>CDL</SPAN
>
expressions will evaluate to the option's data part. For two of the
flavors, <TT
CLASS="LITERAL"
>none</TT
> and <TT
CLASS="LITERAL"
>bool</TT
>, this
data part is fixed to the constant <TT
CLASS="LITERAL"
>1</TT
> which
generally has the expected result.</P
></LI
><LI
><P
>If a component or package is disabled then all sub-components and
options immediately below it in the hierarchy are inactive. By a
process of recursion this will affect all the nodes in the subtree.</P
></LI
><LI
><P
>If an option is disabled then it can impose no constraints on the rest
of the configuration, in particular <SPAN
CLASS="PROPERTY"
>requires</SPAN
> and <SPAN
CLASS="PROPERTY"
>legal_values</SPAN
>
properties will be ignored. If an option is enabled then its
constraints should be satisfied, or the component framework will
report various conflicts. Note that the <SPAN
CLASS="PROPERTY"
>legal_values</SPAN
> constraint only
applies to the data part of the option's value, so it is only useful
with the <TT
CLASS="LITERAL"
>data</TT
> and <TT
CLASS="LITERAL"
>booldata</TT
>
flavors. Options with the <TT
CLASS="LITERAL"
>none</TT
> and
<TT
CLASS="LITERAL"
>data</TT
> flavors are always enabled so their
constraints always have to be satisfied (assuming the option is
active). </P
></LI
><LI
><P
>If an option is disabled then it has no direct consequences at
build-time: no <TT
CLASS="LITERAL"
>#define</TT
> will be generated, no files
will get compiled, and so on. If an option is active and enabled then
all the consequences take effect. The option name and data part are
used to generate the <TT
CLASS="LITERAL"
>#define</TT
> in the appropriate
configuration header file, subject to various properties such as
<SPAN
CLASS="PROPERTY"
>no_define</SPAN
>, but the data part has no other effects on the build
system. </P
></LI
></OL
><P
>By default all options and components have the <TT
CLASS="LITERAL"
>bool</TT
>
flavor: most options are boolean in nature, so making this the default
allows for slightly more compact <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> scripts. Packages have the
<TT
CLASS="LITERAL"
>booldata</TT
> flavor, where the data part always
corresponds to the version of the package that is loaded into the
configuration: changing this value corresponds to unloading the old
version and loading in a different one.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
><SPAN
CLASS="APPLICATION"
>CDL</SPAN
> Flavors: </B
>The concept of <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> flavors tends to result in various discussions
about why it is unnecessarily complicated, and would it not have been
easier to do&nbsp;&#8230; However there are very good reasons why CDL
works the way it does.</P
><P
>The first common suggestion is that there is no need to have separate
flavors <TT
CLASS="LITERAL"
>bool</TT
>, <TT
CLASS="LITERAL"
>data</TT
>, and so on. A
boolean option could just be handled as a data option with legal
values <TT
CLASS="LITERAL"
>0</TT
> and <TT
CLASS="LITERAL"
>1</TT
>. The counter
arguments are as follows:</P
><P
></P
><OL
TYPE="1"
><LI
><P
>It would actually make <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> scripts more verbose. By default all
options and components have the <TT
CLASS="LITERAL"
>bool</TT
> flavor, since
most options are boolean in nature. Without a <TT
CLASS="LITERAL"
>bool</TT
>
flavor it would be necessary to indicate explicitly what the legal
values are somehow, e.g. with a <SPAN
CLASS="PROPERTY"
>legal_values</SPAN
> property.</P
></LI
><LI
><P
>The boolean part of an option's value has a very different effect from
the data part. If an option is disabled then it has no consequences at
build time, and can impose no constraints. A <TT
CLASS="LITERAL"
>data</TT
>
option always has consequences and can impose constraints. To get the
desired effect it would be necessary to add <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> data indicating that
a value of <TT
CLASS="LITERAL"
>0</TT
> should be treated specially. Arguably
this could be made built-in default behavior, although that would
complicate options where <TT
CLASS="LITERAL"
>0</TT
> is a perfectly legal
number, for example
<TT
CLASS="VARNAME"
>CYGNUM_LIBC_TIME_STD_DEFAULT_OFFSET</TT
>. </P
></LI
><LI
><P
>There would no replacement for a <TT
CLASS="LITERAL"
>booldata</TT
> option
for which <TT
CLASS="LITERAL"
>0</TT
> is a valid value. Again some additional
<SPAN
CLASS="APPLICATION"
>CDL</SPAN
> syntax would be needed to express such a concept.</P
></LI
></OL
><P
>Although initially it may seem confusing that an option's value has
both a boolean and a data part, it is an accurate reflection of how
configuration options actually work. The various alternatives would
all make it harder to write <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> scripts.</P
><P
>The next common suggestion is that the data part of a value should be
typed in much the same way as C or C++ data types. For example it
should be possible to describe
<TT
CLASS="VARNAME"
>CYGNUM_LIBC_STDIO_BUFSIZE</TT
> as an integer value,
rather than imposing <SPAN
CLASS="PROPERTY"
>legal_values</SPAN
> constraints. Again there are very
good reasons why this approach was not taken:</P
><P
></P
><OL
TYPE="1"
><LI
><P
>The possible legal values for an integer are rarely correct for a
<SPAN
CLASS="APPLICATION"
>CDL</SPAN
> option. A constraint such as
<TT
CLASS="LITERAL"
>1&nbsp;to&nbsp;0x7fffffff</TT
> is a bit more accurate,
although if this option indicates a buffer size it is still not
particularly good&nbsp;&#8212; very few targets will have enough
memory for such a buffer. Forcing <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> writers to list the
<SPAN
CLASS="PROPERTY"
>legal_values</SPAN
> constraints explicitly should make them think a bit
more about what values are actually sensible. For example
<TT
CLASS="VARNAME"
>CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET</TT
> has legal
values in the range <TT
CLASS="LITERAL"
>-90000&nbsp;to&nbsp;90000</TT
>,
which helps the user to set a sensible value.</P
></LI
><LI
><P
>Not all options correspond to simple data types such as integers.
<TT
CLASS="VARNAME"
>CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE</TT
> is a C string,
and would have to be expressed using something like
<TT
CLASS="LITERAL"
>char&nbsp;[]</TT
>. This introduces plenty of
opportunities for confusion, especially since square brackets may get
processed by the <SPAN
CLASS="APPLICATION"
>Tcl</SPAN
> interpreter for command substitution.</P
></LI
><LI
><P
>Some configuration options can get very complicated indeed, for
example the default value of
<TT
CLASS="VARNAME"
>CYGDAT_UITRON_TASK_INITIALIZERS</TT
> is:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>CYG_UIT_TASK( "t1", 1, task1, &amp;stack1, CYGNUM_UITRON_STACK_SIZE ), \
CYG_UIT_TASK( "t2", 2, task2, &amp;stack2, CYGNUM_UITRON_STACK_SIZE ), \ 
CYG_UIT_TASK( "t3", 3, task3, &amp;stack3, CYGNUM_UITRON_STACK_SIZE ), \
CYG_UIT_TASK( "t4", 4, task4, &amp;stack4, CYGNUM_UITRON_STACK_SIZE )</PRE
></TD
></TR
></TABLE
><P
>This would require <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> knowing about C macros, structures, arrays,
static initializers, and so on. Adding such detailed knowledge about
the C language to the component framework is inappropriate.</P
></LI
><LI
><P
><SPAN
CLASS="APPLICATION"
>CDL</SPAN
> needs to be usable with languages other than C. At present this
includes C++, in future it may include languages such as Java. Each
language adds new data types and related complications, for example
C++ classes and inheritance. Making <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> support a union of all data
types in all possible languages is not sensible.</P
></LI
></OL
><P
>The <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> approach of treating all data as a sequence of characters,
possibly constrained by a <SPAN
CLASS="PROPERTY"
>legal_values</SPAN
> property or other means, has
the great advantage of simplicity. It also fits in with the <SPAN
CLASS="APPLICATION"
>Tcl</SPAN
>
language that underlies <SPAN
CLASS="APPLICATION"
>CDL</SPAN
>.</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="LANGUAGE.VALUES.VALUE.EXAMPLES">Some Examples</H3
><P
>The following excerpt from the C library's <SPAN
CLASS="APPLICATION"
>CDL</SPAN
> scripts can be used
to illustrate how values and flavors work in practice:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>cdl_component CYGPKG_LIBC_RAND {
    flavor        none
    compile       stdlib/rand.cxx

    cdl_option CYGSEM_LIBC_PER_THREAD_RAND {
        requires      CYGVAR_KERNEL_THREADS_DATA
        default_value 0
    }

    cdl_option CYGNUM_LIBC_RAND_SEED {
        flavor        data
        legal_values  0 to 0x7fffffff
        default_value 1
    }

    cdl_option CYGNUM_LIBC_RAND_TRACE_LEVEL {
        flavor        data
        legal_values  0 to 1
        default_value 0
    }
}</PRE
></TD
></TR
></TABLE
><P
>If the application does not require any C library functionality then
it is possible to have a configuration where the C library is not
loaded. This can be achieved by starting with the minimal template, or
by starting with another template such as the default one and then
explicitly unloading the C library package. If this package is not
loaded then any references to the <TT
CLASS="VARNAME"
>CYGPKG_LIBC_RAND</TT
>
component or any of its options will have a value of
<TT
CLASS="LITERAL"
>0</TT
> for the purposes of expression evaluation. No
<TT
CLASS="LITERAL"
>#define's</TT
> will be generated for the component or
any of its options, and the file <TT
CLASS="FILENAME"
>stdlib/rand.cxx</TT
>
will not get compiled. There is nothing special about the C library
here, exactly the same would apply for say a device driver that does
not correspond to any of the devices on the target hardware.</P
><P
>Assuming the C library is loaded, the next thing to consider is
whether or not the component and its options are active. The component
is layered immediately below the C library package itself, so if the
package is loaded then it is safe to assume that the package is also
enabled. Therefore the parent of <TT
CLASS="VARNAME"
>CYGPKG_LIBC_RAND</TT
>
is active and enabled, and in the absence of any <SPAN
CLASS="PROPERTY"
>active_if</SPAN
>
properties <TT
CLASS="VARNAME"
>CYGPKG_LIBC_RAND</TT
> will be active as well.</P
><P
>The component <TT
CLASS="VARNAME"
>CYGPKG_LIBC_RAND</TT
> has the flavor
<TT
CLASS="LITERAL"
>none</TT
>. This means the component cannot be disabled.
Therefore all the options in this component have an active and enabled
parent, and in the absence of any <SPAN
CLASS="PROPERTY"
>active_if</SPAN
> properties they are all
active as well.</P
><P
>The component's flavor <TT
CLASS="LITERAL"
>none</TT
> serves to group
together all of the configuration options related to random number
generation. This is particularly useful in the context of the
graphical configuration tool, but it also helps when it comes to
naming the options: all of the options begin with
<TT
CLASS="LITERAL"
>CYGxxx_LIBC_RAND</TT
>, giving a clear hint about both
the package and the component within that package. The flavor means
that the component is always enabled and has the value
<TT
CLASS="LITERAL"
>1</TT
> for the purposes of expression evaluation. There
will always be a single <TT
CLASS="LITERAL"
>#define</TT
> of the form:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define CYGPKG_LIBC_RAND 1</PRE
></TD
></TR
></TABLE
><P
>In addition the file <TT
CLASS="FILENAME"
>stdlib/rand.cxx</TT
> will always
get built. If the component had the default <TT
CLASS="LITERAL"
>bool</TT
>
flavor then users would be able to disable the whole component,
and one less file would need to be built. However random number
generation is relatively simple, so the impact on eCos build times are
small. Furthermore by default the code has no dependencies on other
parts of the system, so compiling the code has no unexpected side
effects. Even if it was possible to disable the component, the
sensible default for most applications would still leave it enabled.
The net result is that the flavor <TT
CLASS="LITERAL"
>none</TT
> is probably
the most sensible one for this component. For other components the
default <TT
CLASS="LITERAL"
>bool</TT
> flavor or one of the other flavors
might be more appropriate.</P
><P
>Next consider option <TT
CLASS="VARNAME"
>CYGSEM_LIBC_PER_THREAD_RAND</TT
>
which can be used to get a per-thread random number seed, possibly
useful if the application needs a consistent sequence of random
numbers. In the absence of a <SPAN
CLASS="PROPERTY"
>flavor</SPAN
> property this option will be
boolean, and the <SPAN
CLASS="PROPERTY"
>default_value</SPAN
> property means that it is disabled by
default&nbsp;&#8212; reasonable since few applications need this
particular functionality, and it does impose a constraint on the rest
of the system. If the option is left disabled then no
<TT
CLASS="LITERAL"
>#define</TT
> will be generated, and if there were any
<SPAN
CLASS="PROPERTY"
>compile</SPAN
> or similar properties these would not take effect. If the
option is enabled then a <TT
CLASS="LITERAL"
>#define</TT
> will be generated,
using the option's data part which is fixed at <TT
CLASS="LITERAL"
>1</TT
>:</P
><TABLE
BORDER="5"
BGCOLOR="#E0E0F0"
WIDTH="70%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>#define CYGSEM_LIBC_PER_THREAD_RAND 1</PRE
></TD