1 <!-- Copyright (C) 2003 Red Hat, Inc. -->
2 <!-- This material may be distributed only subject to the terms -->
3 <!-- and conditions set forth in the Open Publication License, v1.0 -->
4 <!-- or later (the latest version is presently available at -->
5 <!-- http://www.opencontent.org/openpub/). -->
6 <!-- Distribution of the work or derivative of the work in any -->
7 <!-- standard (paper) book form is prohibited unless prior -->
8 <!-- permission is obtained from the copyright holder. -->
12 >Values and Expressions</TITLE
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="The eCos Component Writer's Guide"
20 HREF="cdl-guide.html"><LINK
22 TITLE="The CDL Language"
23 HREF="language.html"><LINK
25 TITLE="An Introduction to Tcl"
26 HREF="language.tcl.html"><LINK
29 HREF="language.interface.html"></HEAD
40 SUMMARY="Header navigation table"
52 > Component Writer's Guide</TH
60 HREF="language.tcl.html"
68 >Chapter 3. The CDL Language</TD
74 HREF="language.interface.html"
88 NAME="LANGUAGE.VALUES">Values and Expressions</H1
90 >It is fairly reasonable to expect that enabling or disabling a
91 configuration option such as
94 >CYGVAR_KERNEL_THREADS_DATA</TT
95 > in some way affects its
102 >. This will have an effect on any
103 expressions that reference this option such as
106 >requires CYGVAR_KERNEL_THREADS_DATA</TT
108 also affect the consequences of that option: how it affects the build
109 process and what happens to any constraints that
112 >CYGVAR_KERNEL_THREADS_DATA</TT
113 > may impose (as opposed
114 to constraints on this option imposed by others).</P
116 >In a language like C the handling of variables is relatively
117 straightforward. If a variable <TT
121 an expression such as <TT
123 >if (x != 0)</TT
125 and that variable is not defined anywhere, then the code will fail to
126 build, typically with an unresolved error at link-time. Also in C
130 > does not live in any hierarchy, so its
131 value for the purposes of expression evaluation is not affected by
132 anything else. C variables also have a clear type such as
138 >long double</TT
144 > things are not so straightforward.</P
150 NAME="LANGUAGE.VALUES.VALUE">Option Values</H2
152 >There are four factors which go into an option's value:</P
159 >An option may or may not be loaded.</P
163 >If the option is loaded, it may or may not be active.</P
167 >Even if the option is active, it may or may not be enabled.</P
171 >If the option is loaded, active and enabled then it will have some
172 associated data which constitutes its value.</P
180 NAME="LANGUAGE.VALUES.VALUE.LOADED">Is the Option Loaded?</H3
182 >At any one time a configuration will contain only a subset of all
183 possible packages. In fact it is impossible to combine certain
184 packages in a single configuration. For example architectural HAL
185 packages should contain a set of options defining endianness, the
186 sizes of basic data types and so on (many of which will of course be
187 constant for any given architecture). Any attempt to load two
188 architectural HAL packages into a configuration will fail because of
189 the resulting name clash. Since <SPAN
192 > expressions can reference
193 options in other packages, and often need to do so, it is essential to
194 define the resulting behavior.</P
196 >One complication is that the component framework does not know about
197 every single option in every single package. Obviously it cannot know
198 about packages from arbitrary third parties which have not been
199 installed. Even for packages which have been installed, the current
200 repository database does not hold details of every option, only of the
201 packages themselves. If a <SPAN
204 > expression contains a reference to
207 >CYGSEM_KERNEL_SCHED_TIMESLICE</TT
209 component framework will only know about this option if the kernel
210 package is actually loaded into the current configuration. If the
211 package is not loaded then theoretically the framework might guess
212 that the option is somehow related to the kernel by examining the
213 option name but this would not be robust: the option could easily be
214 part of some other package that violates the naming convention.</P
216 >Assume that the user is building a minimal configuration which does
217 not contain the kernel package, but does have other packages which
218 contain the following constraints:</P
226 CLASS="PROGRAMLISTING"
227 > requires CYGPKG_KERNEL
228 requires CYGPKG_KERNEL_THREADS_DATA
229 requires !CYGSEM_KERNEL_SCHED_TIMESLICE</PRE
234 >Clearly the first constraint is not satisfied because the kernel is
235 not loaded. The second constraint is also not satisfied. The third
236 constraint is trivially satisfied: if there is no kernel then the
237 kernel's timeslicing support cannot possibly be enabled. </P
239 >Any options which are not in the current configuration are handled as
247 >Any references to that option will evaluate to <TT
253 >requires !CYGSEM_KERNEL_SCHED_TIMESLICE</TT
258 >requires CYGSEM_KERNEL_THREADS_DATA</TT
264 >An option that is not loaded has no consequences on the build process.
265 It cannot directly result in any <TT
269 configuration header file, nor in any files being compiled. This is
270 only reasonable: if the option is not loaded then the component
271 framework has no way of knowing about any <SPAN
275 properties. An option that is not loaded can have indirect
276 consequences by being referenced in <SPAN
283 >An option that is not loaded cannot impose any constraints on the rest
284 of the configuration. Again this is the only reasonable behavior: if
285 the option is not loaded then any associated <SPAN
292 > properties will not be known.</P
301 NAME="LANGUAGE.VALUES.VALUE.ACTIVE">Is the Option Active</H3
303 >The next issue to consider is whether or not a particular option is
304 active. Configuration options are organized in a hierarchy of
305 components and sub-components. For example the C library package
306 contains a component <TT
308 >CYGPKG_LIBC_STDIO</TT
310 all the options related to standard I/O. If a user disables the
311 component as a whole then all the options below it become inactive: it
312 makes no sense to disable all stdio functionality and then manipulate
315 >Inactive is not quite the same as disabled, although the effects are
316 similar. The value of an inactive option is preserved. If the user
317 modifies a buffer size option, then disables the whole stdio
318 component, the buffer size value remains in case the stdio component
319 is re-enabled later on. Some tools such as the graphical configuration
320 tool will treat inactive options specially, for example such options
321 may be grayed out.</P
323 >The active or inactive state of an option may affect other packages.
324 For example a package may use the <TT
328 function and require support for floating point conversions, a
329 constraint that is not satisfied if the relevant option is inactive.
330 It is necessary to define exactly what it means for an option to be
338 >An option is inactive if its parent is either inactive or disabled.
341 >CYGPKG_LIBC_STDIO</TT
343 all the options and sub-components become inactive; since
346 >CYGPKG_LIBC_STDIO_FLOATING_POINT</TT
350 >CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT</TT
356 >Options may also be inactive as a result of an <SPAN
360 This is useful if a particular option is only relevant if two or more
361 disjoint sets of conditions need to be satisfied, since the
362 hierarchical structure can only cope with at most one such set.</P
366 >If an option is inactive then any references to that option in <SPAN
370 expressions will evaluate to <TT
373 >. Hence a constraint
377 >requires CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT</TT
379 is not satisfied if the entire stdio component is disabled.</P
383 >An option that is inactive has no consequences on the build process.
387 > will be generated. Any <SPAN
391 similar properties will be ignored.</P
395 >An option that is inactive cannot impose any constraints on the rest
396 of the configuration. For example
399 >CYGSEM_LIBC_STDIO_PRINTF_FLOATING_POINT</TT
403 >requires CYGPKG_LIBM</TT
405 the stdio functionality is disabled then this constraint is ignored
406 (although of course there may be other packages which have a
419 NAME="LANGUAGE.VALUES.VALUE.ENABLED">Is the Option Enabled? What is the Data?</H3
421 >The majority of configuration options are boolean in nature, so the
422 user can either enable or disable some functionality. Some options are
423 different. For example <TT
425 >CYGNUM_LIBC_STDIO_BUFSIZE</TT
429 >CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE</TT
431 a string corresponding to a device name. A few options like
434 >CYGDAT_UITRON_TASK_EXTERNS</TT
439 > has to cope with this variety, and define the exact
440 behavior of the system in terms of constraints and build-time
446 > the value of an option consists of two parts. There is a
447 boolean part, controlling whether or not the option is enabled. There
448 is also a data part, providing additional information. For most
449 options one of these parts is fixed, as controlled by the option's
455 CLASS="INFORMALTABLE"
497 >, not modifiable</TD
517 >, not modifiable</TD
559 >The effects of the boolean and data parts are as follows:</P
566 >If an option is disabled, in other words if the boolean part is false,
567 then any references to that option in <SPAN
570 > expressions will evaluate
574 >. This is the same behavior as for inactive
575 options. The data part is not relevant. The <TT
582 > flavors specify that the option is always
583 enabled, in which case this rule is not applicable.</P
587 >If an option is enabled then any references to that option in <SPAN
591 expressions will evaluate to the option's data part. For two of the
599 data part is fixed to the constant <TT
603 generally has the expected result.</P
607 >If a component or package is disabled then all sub-components and
608 options immediately below it in the hierarchy are inactive. By a
609 process of recursion this will affect all the nodes in the subtree.</P
613 >If an option is disabled then it can impose no constraints on the rest
614 of the configuration, in particular <SPAN
621 properties will be ignored. If an option is enabled then its
622 constraints should be satisfied, or the component framework will
623 report various conflicts. Note that the <SPAN
627 applies to the data part of the option's value, so it is only useful
635 flavors. Options with the <TT
642 > flavors are always enabled so their
643 constraints always have to be satisfied (assuming the option is
648 >If an option is disabled then it has no direct consequences at
652 > will be generated, no files
653 will get compiled, and so on. If an option is active and enabled then
654 all the consequences take effect. The option name and data part are
655 used to generate the <TT
659 configuration header file, subject to various properties such as
663 >, but the data part has no other effects on the build
668 >By default all options and components have the <TT
672 flavor: most options are boolean in nature, so making this the default
673 allows for slightly more compact <SPAN
676 > scripts. Packages have the
680 > flavor, where the data part always
681 corresponds to the version of the package that is loaded into the
682 configuration: changing this value corresponds to unloading the old
683 version and loading in a different one.</P
694 >The concept of <SPAN
697 > flavors tends to result in various discussions
698 about why it is unnecessarily complicated, and would it not have been
699 easier to do … However there are very good reasons why CDL
700 works the way it does.</P
702 >The first common suggestion is that there is no need to have separate
710 boolean option could just be handled as a data option with legal
718 arguments are as follows:</P
725 >It would actually make <SPAN
728 > scripts more verbose. By default all
729 options and components have the <TT
733 most options are boolean in nature. Without a <TT
737 flavor it would be necessary to indicate explicitly what the legal
738 values are somehow, e.g. with a <SPAN
745 >The boolean part of an option's value has a very different effect from
746 the data part. If an option is disabled then it has no consequences at
747 build time, and can impose no constraints. A <TT
751 option always has consequences and can impose constraints. To get the
752 desired effect it would be necessary to add <SPAN
755 > data indicating that
759 > should be treated specially. Arguably
760 this could be made built-in default behavior, although that would
761 complicate options where <TT
764 > is a perfectly legal
768 >CYGNUM_LIBC_TIME_STD_DEFAULT_OFFSET</TT
773 >There would no replacement for a <TT
780 > is a valid value. Again some additional
784 > syntax would be needed to express such a concept.</P
788 >Although initially it may seem confusing that an option's value has
789 both a boolean and a data part, it is an accurate reflection of how
790 configuration options actually work. The various alternatives would
791 all make it harder to write <SPAN
796 >The next common suggestion is that the data part of a value should be
797 typed in much the same way as C or C++ data types. For example it
798 should be possible to describe
801 >CYGNUM_LIBC_STDIO_BUFSIZE</TT
802 > as an integer value,
803 rather than imposing <SPAN
806 > constraints. Again there are very
807 good reasons why this approach was not taken:</P
814 >The possible legal values for an integer are rarely correct for a
818 > option. A constraint such as
821 >1 to 0x7fffffff</TT
822 > is a bit more accurate,
823 although if this option indicates a buffer size it is still not
824 particularly good — very few targets will have enough
825 memory for such a buffer. Forcing <SPAN
828 > writers to list the
832 > constraints explicitly should make them think a bit
833 more about what values are actually sensible. For example
836 >CYGNUM_LIBC_TIME_DST_DEFAULT_OFFSET</TT
838 values in the range <TT
840 >-90000 to 90000</TT
842 which helps the user to set a sensible value.</P
846 >Not all options correspond to simple data types such as integers.
849 >CYGDAT_LIBC_STDIO_DEFAULT_CONSOLE</TT
851 and would have to be expressed using something like
855 >. This introduces plenty of
856 opportunities for confusion, especially since square brackets may get
857 processed by the <SPAN
860 > interpreter for command substitution.</P
864 >Some configuration options can get very complicated indeed, for
865 example the default value of
868 >CYGDAT_UITRON_TASK_INITIALIZERS</TT
877 CLASS="PROGRAMLISTING"
878 >CYG_UIT_TASK( "t1", 1, task1, &stack1, CYGNUM_UITRON_STACK_SIZE ), \
879 CYG_UIT_TASK( "t2", 2, task2, &stack2, CYGNUM_UITRON_STACK_SIZE ), \
880 CYG_UIT_TASK( "t3", 3, task3, &stack3, CYGNUM_UITRON_STACK_SIZE ), \
881 CYG_UIT_TASK( "t4", 4, task4, &stack4, CYGNUM_UITRON_STACK_SIZE )</PRE
886 >This would require <SPAN
889 > knowing about C macros, structures, arrays,
890 static initializers, and so on. Adding such detailed knowledge about
891 the C language to the component framework is inappropriate.</P
898 > needs to be usable with languages other than C. At present this
899 includes C++, in future it may include languages such as Java. Each
900 language adds new data types and related complications, for example
901 C++ classes and inheritance. Making <SPAN
904 > support a union of all data
905 types in all possible languages is not sensible.</P
912 > approach of treating all data as a sequence of characters,
913 possibly constrained by a <SPAN
916 > property or other means, has
917 the great advantage of simplicity. It also fits in with the <SPAN
921 language that underlies <SPAN
933 NAME="LANGUAGE.VALUES.VALUE.EXAMPLES">Some Examples</H3
935 >The following excerpt from the C library's <SPAN
938 > scripts can be used
939 to illustrate how values and flavors work in practice:</P
947 CLASS="PROGRAMLISTING"
948 >cdl_component CYGPKG_LIBC_RAND {
950 compile stdlib/rand.cxx
952 cdl_option CYGSEM_LIBC_PER_THREAD_RAND {
953 requires CYGVAR_KERNEL_THREADS_DATA
957 cdl_option CYGNUM_LIBC_RAND_SEED {
959 legal_values 0 to 0x7fffffff
963 cdl_option CYGNUM_LIBC_RAND_TRACE_LEVEL {
973 >If the application does not require any C library functionality then
974 it is possible to have a configuration where the C library is not
975 loaded. This can be achieved by starting with the minimal template, or
976 by starting with another template such as the default one and then
977 explicitly unloading the C library package. If this package is not
978 loaded then any references to the <TT
980 >CYGPKG_LIBC_RAND</TT
982 component or any of its options will have a value of
986 > for the purposes of expression evaluation. No
990 > will be generated for the component or
991 any of its options, and the file <TT
995 will not get compiled. There is nothing special about the C library
996 here, exactly the same would apply for say a device driver that does
997 not correspond to any of the devices on the target hardware.</P
999 >Assuming the C library is loaded, the next thing to consider is
1000 whether or not the component and its options are active. The component
1001 is layered immediately below the C library package itself, so if the
1002 package is loaded then it is safe to assume that the package is also
1003 enabled. Therefore the parent of <TT
1005 >CYGPKG_LIBC_RAND</TT
1007 is active and enabled, and in the absence of any <SPAN
1013 >CYGPKG_LIBC_RAND</TT
1014 > will be active as well.</P
1018 >CYGPKG_LIBC_RAND</TT
1023 >. This means the component cannot be disabled.
1024 Therefore all the options in this component have an active and enabled
1025 parent, and in the absence of any <SPAN
1028 > properties they are all
1031 >The component's flavor <TT
1035 together all of the configuration options related to random number
1036 generation. This is particularly useful in the context of the
1037 graphical configuration tool, but it also helps when it comes to
1038 naming the options: all of the options begin with
1041 >CYGxxx_LIBC_RAND</TT
1042 >, giving a clear hint about both
1043 the package and the component within that package. The flavor means
1044 that the component is always enabled and has the value
1048 > for the purposes of expression evaluation. There
1049 will always be a single <TT
1060 CLASS="PROGRAMLISTING"
1061 >#define CYGPKG_LIBC_RAND 1</PRE
1066 >In addition the file <TT
1068 >stdlib/rand.cxx</TT
1070 get built. If the component had the default <TT
1074 flavor then users would be able to disable the whole component,
1075 and one less file would need to be built. However random number
1076 generation is relatively simple, so the impact on eCos build times are
1077 small. Furthermore by default the code has no dependencies on other
1078 parts of the system, so compiling the code has no unexpected side
1079 effects. Even if it was possible to disable the component, the
1080 sensible default for most applications would still leave it enabled.
1081 The net result is that the flavor <TT
1085 the most sensible one for this component. For other components the
1089 > flavor or one of the other flavors
1090 might be more appropriate.</P
1092 >Next consider option <TT
1094 >CYGSEM_LIBC_PER_THREAD_RAND</TT
1096 which can be used to get a per-thread random number seed, possibly
1097 useful if the application needs a consistent sequence of random
1098 numbers. In the absence of a <SPAN
1101 > property this option will be
1102 boolean, and the <SPAN
1104 >default_value</SPAN
1105 > property means that it is disabled by
1106 default — reasonable since few applications need this
1107 particular functionality, and it does impose a constraint on the rest
1108 of the system. If the option is left disabled then no
1112 > will be generated, and if there were any
1116 > or similar properties these would not take effect. If the
1117 option is enabled then a <TT
1120 > will be generated,
1121 using the option's data part which is fixed at <TT
1132 CLASS="PROGRAMLISTING"
1133 >#define CYGSEM_LIBC_PER_THREAD_RAND 1</PRE
1140 >CYGSEM_LIBC_PER_THREAD_RAND</TT
1148 >CYGVAR_KERNEL_THREADS_DATA</TT
1149 >. If the C library option
1150 is enabled then the constraint should be satisfied, or else the
1151 configuration contains a conflict. If the configuration does not
1152 include the kernel package then
1155 >CYGVAR_KERNEL_THREADS_DATA</TT
1160 > and the constraint is not satisfied. Similarly if
1161 the option is inactive or disabled the constraint will not be
1166 >CYGNUM_LIBC_RAND_SEED</TT
1170 >CYGNUM_LIBC_RAND_TRACE_LEVEL</TT
1175 > flavor, so they are always enabled and the
1176 component framework will generate appropriate
1188 CLASS="PROGRAMLISTING"
1189 >#define CYGNUM_LIBC_RAND_SEED 1
1190 #define CYGNUM_LIBC_RAND_SEED_1
1191 #define CYGNUM_LIBC_RAND_TRACE_LEVEL 0
1192 #define CYGNUM_LIBC_RAND_TRACE_LEVEL_0</PRE
1197 >Neither option has a <SPAN
1200 > or similar property, but any such
1201 properties would take effect. Any references to these options in <SPAN
1205 expressions would evaluate to the data part, so a hypothetical
1206 constraint of the form
1209 >{ requires CYGNUM_LIBC_RAND_SEED > 42 }</TT
1211 would not be satisfied with the default values. Both options use a
1212 simple constant for the <SPAN
1214 >default_value</SPAN
1215 > expression. It would be
1216 possible to use a more complicated expression, for example the default
1219 >CYGNUM_LIBC_RAND_TRACE_LEVEL</TT
1221 determined from some global debugging option or from a debugging
1222 option that applies to the C library as a whole. Both options also
1226 > constraint, which must be satisfied since the
1227 options are active and enabled. </P
1241 >CYGNUM_LIBC_RAND_SEED</TT
1245 >CYGNUM_LIBC_RAND_TRACE_LEVEL</TT
1250 expression there is no easy way of distinguishing between the options
1251 being absent or having that particular value. This will be addressed
1252 by future enhancements to the expression syntax.</P
1262 NAME="LANGUAGE.EXPRESSION">Ordinary Expressions</H2
1264 >Expressions in <SPAN
1267 > follow a conventional syntax, for example:</P
1275 CLASS="PROGRAMLISTING"
1276 > default_value CYGGLO_CODESIZE > CYGGLO_SPEED
1277 default_value { (CYG_HAL_STARTUP == "RAM" &&
1278 !CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS &&
1279 !CYGINT_HAL_USE_ROM_MONITOR_UNSUPPORTED &&
1280 !CYGSEM_HAL_POWERPC_COPY_VECTORS) ? 1 : 0 }
1281 default_value { "\"/dev/ser0\"" }</PRE
1286 >However there is a complication in that the various arguments to a
1289 >default_value</SPAN
1290 > property will first get processed by a <SPAN
1294 interpreter, so special characters like quotes and square brackets may
1295 get processed. Such problems can be avoided by enclosing non-trivial
1296 expressions in braces, as in the second example above. The way
1297 expression parsing actually works is as follows:</P
1307 > interpreter splits the line or lines into a command and its
1308 arguments. In the first <SPAN
1310 >default_value</SPAN
1311 > expression above the command
1315 > and there are three arguments,
1318 >CYGGLO_CODESIZE</TT
1326 >. In the second and third examples
1327 there is just one argument, courtesy of the braces.</P
1331 >Next option processing takes place, so any initial arguments that
1332 begin with a hyphen will be interpreted as options. This can cause
1333 problems if the expression involves a negative number, so the
1334 special argument <TT
1337 > can be used to prevent option
1338 processing on the subsequent arguments.</P
1342 >All of the arguments are now concatenated, with a single space in
1343 between each one. Hence the following two expressions are equivalent,
1344 even though they will have been processed differently up to this point.</P
1352 CLASS="PROGRAMLISTING"
1353 > default_value CYGGLO_CODESIZE > CYGGLO_SPEED
1354 default_value {CYGGLO_CODESIZE > CYGGLO_SPEED}</PRE
1361 >The expression parsing code now has a single string to process.</P
1368 > expressions consist of four types of element: references to
1369 configuration options, constant strings, integers, and floating point
1370 numbers. These are combined using a conventional set of operators: the
1381 >; the arithmetic operators <TT
1398 >; the shift operators <TT
1405 >; the comparison operators
1426 >; the bitwise operators
1437 >; the logical operators <TT
1444 >; the string concatenation operator
1448 >; and the ternary conditional operator
1451 >A ? B : C</TT
1452 >. There is also support for
1453 some less widely available operators for logical equivalence and
1454 implication, and for a set of function-style operations. Bracketed
1455 sub-expressions are supported, and the operators have the usual
1458 CLASS="INFORMALTABLE"
1495 >references, constants</TD
1580 >arithmetic negation</TD
1600 >multiplicative arithmetic</TD
1620 >additive arithmetic and string concatenation</TD
1634 ><< >></TT
1654 ><= < > >=</TT
1800 >logical equivalance</TD
1820 >logical implication</TD
1848 >Function calls have the usual format of a name, an opening bracket,
1849 one or more arguments separated by commas, and a closing bracket. For
1858 CLASS="PROGRAMLISTING"
1859 > requires { !is_substr(CYGBLD_GLOBAL_CFLAGS, " -fno-rtti") }</PRE
1864 >Functions will differ in the number of arguments and may impose
1865 restrictions on some or all of their arguments. For example it may be
1866 necessary for the first argument to be a reference to a configuration
1867 option. The available functions are described in <A
1868 HREF="language.values.html#LANGUAGE.FUNCTIONS"
1869 >the Section called <I
1877 > operator evaluates to true if
1878 either the left hand side or the right hand side but not both evaluate
1879 to true The logical <TT
1882 > operator evaluates to true
1883 if both the left and right hand sides evaluate to true, or if both
1884 evaluate to false. The <TT
1887 > operator evaluates
1888 to true either if the left hand side is false or if the right hand
1889 side is true, in other words <TT
1891 >A implies B</TT
1893 has the same meaning as <TT
1895 >!A || B</TT
1897 example use would be:</P
1905 CLASS="PROGRAMLISTING"
1906 > requires { is_active(CYGNUM_LIBC_MAIN_DEFAULT_STACK_SIZE) implies
1907 (CYGNUM_LIBC_MAIN_DEFAULT_STACK_SIZE >= (16 * 1024)) }</PRE
1912 >This constraint would be satisfied if either the support for a main
1913 stack size is disabled, or if that stack is at least 16K. However if
1914 such a stack were in use but was too small, a conflict would be raised.</P
1919 > identifier in an expression, for example
1923 >, will be interpreted as a reference to
1924 a configuration option by that name. The option does not have to be
1925 loaded into the current configuration. When the component framework
1926 evaluates the expression it will substitute in a suitable value that
1927 depends on whether or not the option is loaded, active, and enabled.
1928 The exact rules are described in <A
1929 HREF="language.values.html#LANGUAGE.VALUES.VALUE"
1930 >the Section called <I
1935 >A constant string is any sequence of characters enclosed in quotes.
1936 Care has to be taken that these quotes are not stripped off by the
1940 > interpreter before the <SPAN
1943 > expression parser sees them.
1944 Consider the following:</P
1952 CLASS="PROGRAMLISTING"
1953 > default_value "RAM"</PRE
1958 >The quote marks will be stripped before the <SPAN
1962 sees the data, so the expression will be interpreted as a reference to
1963 a configuration option <TT
1966 >. There is unlikely to be
1967 such an option, so the actual default value will be
1971 >. Careful use of braces or other <SPAN
1975 mechanisms can be used to avoid such problems.</P
1978 String constants consist of the data inside the quotes. If the data
1979 itself needs to contain quote characters then appropriate quoting is
1980 again necessary, for example:</P
1988 CLASS="PROGRAMLISTING"
1989 > default_value { "\"/dev/ser0\"" }</PRE
1994 >An integer constant consists of a sequence of digits, optionally
1995 preceeded with the unary <TT
2002 operators. As usual the sequence <TT
2009 > can be used for hexadecimal data, and a leading
2013 > indicates octal data. Internally the component
2014 framework uses 64-bit arithmetic for integer data. If a constant is
2015 too large then double precision arithmetic will be used instead.
2016 Traditional syntax is also used for double precision numbers, for
2025 >Of course this is not completely accurate: <SPAN
2029 language, all data is treated as if it were a string. For example the
2030 following two lines are equivalent:</P
2038 CLASS="PROGRAMLISTING"
2039 > requires CYGNUM_UITRON_SEMAS > 10
2040 requires { CYGNUM_UITRON_SEMAS > "10" }</PRE
2045 >When an expression gets evaluated the operators will attempt
2046 appropriate conversions. The <TT
2050 operator can be used on either integer or double precision numbers, so
2051 it will begin by attempting a string to integer conversion of both
2052 operands. If that fails it will attempt string to double conversions.
2053 If that fails as well then the component framework will report a
2054 conflict, an evaluation exception. If the conversions from string to
2055 integer are successful then the result will be either the string
2063 can be converted to integers or doubles as required.</P
2065 >It is worth noting that the expression
2068 >CYGNUM_UITRON_SEMAS >10</TT
2073 > identifiers can never begin with a digit, so it is not possible
2077 > to be misinterpreted as a reference to an
2078 identifier instead of as a string.</P
2080 >Of course the implementation is slightly different again. The <SPAN
2084 language definition is such that all data is treated as if it were a
2085 string, with conversions to integer, double or boolean as and when
2086 required. The implementation is allowed to avoid conversions until
2087 they are necessary. For example, given
2090 >CYGNUM_UITRON_SEMAS > 10</TT
2092 expression parsing code will perform an immediate conversion from
2093 string to integer, storing the integer representation, and there is no
2094 need for a conversion by the comparison operator when the expression
2095 gets evaluated. Given
2098 >{ CYGNUM_UITRON_SEMAS > "10" }</TT
2100 the parsing code will store the string representation and a conversion
2101 happens the first time the expression is evaluated. All of this is an
2102 implementation detail, and does not affect the semantics of the
2105 >Different operators have different requirements, for example the
2106 bitwise or operator only makes sense if both operands have an integer
2107 representation. For operators which can work with either integer or
2108 double precision numbers, integer arithmetic will be preferred.</P
2110 >The following operators only accept integer operands:
2114 > (bitwise not), the shift operators
2122 bitwise operators <TT
2134 >The following operators will attempt integer arithmetic first, then
2135 double precision arithmetic: unary <TT
2139 the arithmetic operators <TT
2156 and the comparision operators <TT
2179 > operators will first attempt integer conversion
2180 and comparison. If that fails then double precision will be attempted
2181 (although arguably using these operators on double precision data is
2182 not sensible). As a last resort string comparison will be used.</P
2194 > all work with boolean data. Any string that can
2195 be converted to the integer <TT
2202 > is treated as false, as is the empty string or
2203 the constant string <TT
2207 interpreted as true. The result is either <TT
2216 >The conditional operator <TT
2220 its first operand as a boolean. It does not perform any processing on
2221 the second or third operands.</P
2223 >In practice it is rarely necessary to worry about any of these
2224 details. In nearly every case <SPAN
2227 > expressions just work as expected,
2228 and there is no need to understand the full details.</P
2236 >The current expression syntax does not meet all the needs of component
2237 writers. Some future enhancements will definitely be made, others are
2238 more controversial. The list includes the following:</P
2245 >An option's value is determined by several different factors: whether
2246 or not it is loaded, whether or not it is active, whether or not it is
2247 enabled, and the data part. Currently there is no way of querying
2248 these individually. This is very significant in the context of options
2256 flavors, because there is no way of distinguishing between the option
2257 being absent/inactive/disabled or it being enabled with a data field
2261 >. There should be unary operators that allow
2262 any of the factors to be checked.</P
2273 be used for string data. More string-related facilities are needed.</P
2277 >An implies operator would be useful for many goal expression, where
2280 >A implies B</TT
2289 >Similarly there is inadequate support for lists. On occasion it would
2290 be useful to write expressions involving say the list of implementors
2291 of a given CDL interface, for example a sensible default value could
2292 be the first implementor. Associated with this is a need for an
2293 indirection operator.</P
2297 >Arguably extending the basic <SPAN
2300 > expression syntax with lots of new
2301 operators is unnecessary, instead expressions should just support
2305 > command substitution and then component writers could escape
2309 > scripts for complicated operations. This has some major
2310 disadvantages. First, the inference engine would no longer have any
2311 sensible way of interpreting an expression to resolve a conflict.
2312 Second, the component framework's value propagation code keeps track
2313 of which options get referenced in which expressions and avoids
2314 unnecessary re-evaluation of expressions; if expressions can involve
2318 > code then there is no simple way to eliminate
2319 unnecessary recalculations, with a potentially major impact on
2332 >The current implementation of the component framework uses 64 bit
2333 arithmetic on all host platforms. Although this is adequate for
2334 current target architectures, it may cause problems in future. At some
2335 stage it is likely that an arbitrary precision integer arithmetic
2336 package will be used instead.</P
2345 NAME="LANGUAGE.FUNCTIONS">Functions</H2
2347 >CDL expressions can contain calls to a set of built-in functions
2348 using the usual syntax, for example;</P
2356 CLASS="PROGRAMLISTING"
2357 > requires { !is_substr(CYGBLD_GLOBAL_CFLAGS, "-fno-rtti") }</PRE
2362 >The available function calls are as follows:</P
2366 CLASS="VARIABLELIST"
2371 >get_data(option)</TT
2375 >This function can be used to obtain just the data part of a loaded
2376 configuration option, ignoring other factors such as whether or not
2377 the option is active and enabled. It takes a single argument which
2378 should be the name of a configuration option. If the specified option
2379 is not loaded in the current configuration then the function returns
2380 0, otherwise it returns the data part. Typically this function will
2381 only be used in conjunction with <TT
2388 > for fine-grained control over the
2389 various factors that make up an option's value.</P
2394 >is_active(option)</TT
2398 >This function can be used to determine whether or not a particular
2399 configuration option is active. It takes a single argument which
2400 should be the name of an option, and returns a boolean. If the
2401 specified option is not loaded then the function will return false.
2402 Otherwise it will consider the state of the option's parents and
2406 > properties, and return the option's current
2407 active state. A typical use might be:</P
2415 CLASS="PROGRAMLISTING"
2416 > requires { is_active(CYGNUM_LIBC_MAIN_DEFAULT_STACK_SIZE) implies
2417 (CYGNUM_LIBC_MAIN_DEFAULT_STACK_SIZE >= (16 * 1024)) }</PRE
2422 >In other words either the specified configuration option must be
2423 inactive, for example because the current application does not use
2424 any related C library or POSIX functionality, or the stack size must
2427 >The configuration system's inference engine can attempt to satisfy
2428 constraints involving <TT
2432 different ways, for example by enabling or disabling parent
2433 components, or by examining <SPAN
2436 > properties and manipulating
2437 terms in the associated expressions.</P
2442 >is_enabled(option)</TT
2446 >This function can be used to determine whether or not a particular
2447 configuration option is enabled. It takes a single argument which
2448 should be the name of an option, and returns a boolean. If the
2449 specified option is not loaded then the function will return false.
2450 Otherwise it will return the current boolean part of the option's
2451 value. The option's active or inactive state is ignored. Typically
2452 this function will be used in conjunction with
2460 > to provide fine-grained control over the
2461 various factors that make up an option's value.</P
2466 >is_loaded(option)</TT
2470 >This function can be used to determine whether or not a particular
2471 configuration option is loaded. It takes a single argument which
2472 should be the name of an option, and returns a boolean. If the
2473 argument is a package then the <TT
2477 provides little or no extra information, for example the following two
2478 constraints are usually equivalent:</P
2486 CLASS="PROGRAMLISTING"
2487 > requires { CYGPKG_KERNEL }
2488 requires { is_loaded(CYGPKG_KERNEL) }</PRE
2493 >However if the specified package is loaded but re-parented below a
2494 disabled component, or inactive as a result of an <SPAN
2498 property, then the first constraint would not be satisfied but the
2499 second constraint would. In other words the
2503 > makes it possible to consider in
2504 isolation one of the factors that are considered when CDL expressions
2507 >The configuration system's inference engine will not automatically
2508 load or unload packages to satisfy <TT
2517 >is_substr(haystack, needle)</TT
2521 >This can be used to check whether or not a particular string is
2522 present in another string. It is used mainly for manipulating compiler
2523 flags. The function takes two arguments, both of which can be
2524 arbitrary expressions, and returns a boolean.</P
2529 > has some understanding of word
2530 boundaries. If the second argument starts with a space character then
2531 that will match either a real space or the start of the string.
2532 Similarly if the second argument ends with a space character then that
2533 will match a real space or the end of the string. For example, all of
2534 the following conditions are satisfied:</P
2542 CLASS="PROGRAMLISTING"
2543 > is_substr("abracadabra", "abra")
2544 is_substr("abracadabra", " abra")
2545 is_substr("hocus pocus", " pocus")
2546 is_substr("abracadabra", "abra ")</PRE
2551 >The first is an exact match. The second is a match because the leading
2552 space matches the start of the string. The third is an exact match,
2553 with the leading space matching an actual space. The fourth is a match
2554 because the trailing space matches the end of the string. However, the
2555 following condition is not satisfied.</P
2563 CLASS="PROGRAMLISTING"
2564 > is_substr("abracadabra", " abra ")</PRE
2569 >This fails to match at the start of the string because the trailing
2570 space is not matched by either a real space or the end of the string.
2571 Similarly it fails to match at the end of the string.</P
2573 >If a constraint involving <TT
2577 satisfied and the first argument is a reference to a configuration
2578 option, the inference engine will attempt to modify that option's
2579 value. This can be achieved either by appending the second argument to
2580 the current value, or by removing all occurrences of that argument
2581 from the current value.</P
2589 CLASS="PROGRAMLISTING"
2590 > requires { !is_substr(CYGBLD_GLOBAL_CFLAGS, " -fno-rtti ") }
2591 requires { is_substr(CYGBLD_GLOBAL_CFLAGS, " -frtti ") }</PRE
2596 >When data is removed the leading and trailing spaces will be left. For
2597 example, given an initial value of
2600 >CYGBLD_GLOBAL_CFLAGS</TT
2604 >-g -fno-rtti -O2</TT
2605 > the result will be
2608 >-g -O2</TT
2614 >If exact matches are needed, the function
2618 > can be used instead.</P
2623 >is_xsubstr(haystack, needle)</TT
2627 >This function checks whether or not the pattern string is an exact
2628 substring of the string being searched. It is similar to
2632 > but uses exact matching only. In other
2633 words, leading or trailing spaces have to match exactly and will not
2634 match the beginning or end of the string being searched. The function
2635 takes two arguments, both of which can be arbitrary expressions, and
2636 returns a boolean. The difference between
2644 illustrated by the following examples:</P
2652 CLASS="PROGRAMLISTING"
2653 > cdl_option MAGIC {
2655 default_value { "abracadabra" }
2658 requires { is_substr(MAGIC, " abra") }
2659 requires { is_xsubstr(MAGIC, " abra") }</PRE
2664 >The first goal will be satisfied because the leading space in the
2665 pattern matches the beginning of the string. The second goal will not
2666 be satisfied initialy because there is no exact match, so the
2667 inference engine is likely to update the value of
2673 >abracadabra abra</TT
2675 does give an exact match.</P
2680 >version_cmp(A, B)</TT
2684 >This function is used primarily to check that a sufficiently recent
2686 HREF="package.versions.html"
2688 > of some other package
2689 is being used. It takes two arguments, both of which can be arbitrary
2690 expressions. In practice usually one of the arguments will be a
2691 reference to a package and the other will be a constant version
2692 string. The return value is -1 if the first argument is a more recent
2693 version then the second, 0 if the two arguments correspond to
2694 identical versions, and 1 if the first argument is an older version.
2695 For example the following constraint can be used to indicate that the
2696 current package depends on kernel functionality that only became
2697 available in version 1.3:</P
2705 CLASS="PROGRAMLISTING"
2706 > requires { version_cmp(CYGPKG_KERNEL, "v1.3") <= 0 }</PRE
2720 >At this time it is not possible to define new functions inside a CDL
2721 script. Instead functions can only be added at the C++ level, usually
2722 by extending libcdl itself. This is partly because there is more to
2723 CDL functions than simple evaluation: associated with most functions
2724 is support for the inference engine, so that if a constraint involving
2725 a function is not currently satisfied the system may be able to find a
2726 solution automatically.</P
2735 NAME="LANGUAGE.GOAL-EXPRESSION">Goal Expressions</H2
2737 >The arguments to certain properties, notably <SPAN
2744 >, constitute a goal expression. As with an ordinary
2745 expression, all of the arguments get combined and then the expression
2746 parser takes over. The same care has to be taken with constant strings
2747 and anything else that may get processed by the Tcl interpreter, so
2748 often a goal expression is enclosed entirely in braces and the
2749 expression parsing code sees just a single argument.</P
2751 >A goal expression is basically just a sequence of ordinary
2752 expressions, for example:</P
2760 CLASS="PROGRAMLISTING"
2761 > requires { CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS
2762 !CYGDBG_HAL_DEBUG_GDB_BREAK_SUPPORT
2763 !CYGDBG_HAL_DEBUG_GDB_CTRLC_SUPPORT }</PRE
2768 >This consists of three separate expressions, all of which should
2769 evaluate to a non-zero result. The same expression could be written
2778 CLASS="PROGRAMLISTING"
2779 > requires { CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS &&
2780 !CYGDBG_HAL_DEBUG_GDB_BREAK_SUPPORT &&
2781 !CYGDBG_HAL_DEBUG_GDB_CTRLC_SUPPORT }</PRE
2786 >Alternatively the following would have much the same effect:</P
2794 CLASS="PROGRAMLISTING"
2795 > requires CYGDBG_HAL_DEBUG_GDB_INCLUDE_STUBS
2796 requires !CYGDBG_HAL_DEBUG_GDB_BREAK_SUPPORT
2797 requires !CYGDBG_HAL_DEBUG_GDB_CTRLC_SUPPORT</PRE
2802 >Selecting between these alternatives is largely a stylistic choice.
2803 The first is slightly more concise than the others. The second is more
2804 likely to appeal to mathematical purists. The third is more amenable
2805 to cutting and pasting.</P
2807 >The result of evaluating a goal expression is a boolean. If any part
2808 of the goal expression evaluates to the integer <TT
2812 or an equivalent string then the result is false, otherwise it is
2815 >The term “goal expression” relates to the component
2816 framework's inference engine: it is a description of a goal that
2817 should be satisfied for a conflict-free configuration. If a <SPAN
2821 constraint is not satisfied then the inference engine will examine the
2822 goal expression: if there is some way of changing the configuration
2823 that does not introduce new conflicts and that will cause the goal
2824 expression to evaluate to true, the conflict can be resolved.</P
2826 >The inference engine works with one conflict and hence one goal
2827 expression at a time. This means that there can be slightly different
2828 behavior if a constraint is specified using a single <SPAN
2832 property or several different ones. Given the above example, suppose
2833 that none of the three conditions are satisfied. If a single goal
2834 expression is used then the inference engine might be able to satisfy
2835 only two of the three parts, but since the conflict as a whole cannot
2836 be resolved no part of the solution will be applied. Instead the user
2837 will have to resolve the entire conflict. If three separate goal
2838 expressions are used then the inference engine might well find
2839 solutions to two of them, leaving less work for the user. On the other
2840 hand, if a single goal expression is used then the inference engine
2841 has a bit more information to work with, and it might well find a
2842 solution to the entire conflict where it would be unable to find
2843 separate solutions for the three parts. Things can get very
2844 complicated, and in general component writers should not worry about
2845 the subtleties of the inference engine and how to manipulate its
2848 >It is possible to write ambiguous goal expressions, for example:</P
2856 CLASS="PROGRAMLISTING"
2857 > requires CYGNUM_LIBC_RAND_SEED -CYGNUM_LIBC_RAND_TRACE_LEVEL > 5</PRE
2862 >This could be parsed in two ways:</P
2870 CLASS="PROGRAMLISTING"
2871 > requires ((CYGNUM_LIBC_RAND_SEED - CYGNUM_LIBC_RAND_TRACE_LEVEL) > 5)
2872 requires CYGNUM_LIBC_RAND_SEED && ((-CYGNUM_LIBC_RAND_TRACE_LEVEL) > 5)</PRE
2877 >The goal expression parsing code will always use the largest ordinary
2878 expression for each goal, so the first interpretation will be used.
2879 In such cases it is a good idea to use brackets and avoid possible
2887 NAME="LANGUAGE.LIST-EXPRESSION">List Expressions</H2
2889 >The arguments to the <SPAN
2892 > property constitute a goal
2893 expression. As with an ordinary and goal expressions, all of the
2894 arguments get combined and then the expression parser takes over. The
2895 same care has to be taken with constant strings and anything else that
2896 may get processed by the Tcl interpreter, so often a list expression
2897 is enclosed entirely in braces and the expression parsing code sees
2898 just a single argument.</P
2900 >Most list expressions take one of two forms:</P
2908 CLASS="PROGRAMLISTING"
2909 > legal_values <expr1> <expr2> <expr3> ...
2910 legal_values <expr1> to <expr2></PRE
2922 ordinary expressions. Often these will be constants or references to
2923 calculated options in the architectural HAL package, but it is
2924 possible to use arbitrary expressions when necessary. The first syntax
2925 indicates a list of possible values, which need not be numerical. The
2926 second syntax indicates a numerical range: both sides of the
2930 > must evaluate to a numerical value; if either
2931 side involves a floating point number then any floating point number
2932 in that range is legal; otherwise only integer values are legal;
2933 ranges are inclusive, so <TT
2936 > is a valid value given a
2939 >1 to </TT
2944 > does not evaluate to a numerical
2945 value then this will result in a run-time conflict. The following
2946 examples illustrate these possibilities:</P
2954 CLASS="PROGRAMLISTING"
2955 > legal_values { "red" "green" "blue" }
2956 legal_values 1 2 4 8 16
2957 legal_values 1 to CYGARC_MAXINT
2958 legal_values 1.0 to 2.0</PRE
2963 >It is possible to combine the two syntaxes, for example:</P
2971 CLASS="PROGRAMLISTING"
2972 > legal_values 1 2 4 to CYGARC_MAXINT -1024 -20.0 to -10</PRE
2977 >This indicates three legal values <TT
2990 >4 to CYGARC_MAXINT</TT
2992 floating point range <TT
2994 >-20.0 to -10.0</TT
2996 practice such list expressions are rarely useful.</P
3001 > is not reserved, so it is
3002 possible to have a configuration option with that name (although it
3003 violates every naming convention). Using that option in a list
3004 expression may however give unexpected results.</P
3006 >The graphical configuration tool uses the <SPAN
3010 expression to determine how best to let users manipulate the option's
3011 value. Different widgets will be appropriate for different lists, so
3014 >{ "red" "green" "blue" }</TT
3016 involve a pull-down option menu, and
3019 >1 to 16</TT
3020 > could involve a spinner. The
3021 exact way in which <SPAN
3024 > lists get mapped on to GUI widgets
3025 is not defined and is subject to change at any time.</P
3027 >As with goal expressions, list expressions can be ambiguous. Consider
3028 the following hypothetical example:</P
3036 CLASS="PROGRAMLISTING"
3037 > legal_values CYGNUM_LIBC_RAND_SEED -CYGNUM_LIBC_RAND_TRACE_LEVEL</PRE
3042 >This could be parsed in two ways:</P
3050 CLASS="PROGRAMLISTING"
3051 > legal_values (CYGNUM_LIBC_RAND_SEED - CYGNUM_LIBC_RAND_TRACE_LEVEL)
3052 legal_values (CYGNUM_LIBC_RAND_SEED) (-CYGNUM_LIBC_RAND_TRACE_LEVEL)</PRE
3057 >Both are legal. The list expression parsing code will always use the
3058 largest ordinary expression for each element, so the first
3059 interpretation will be used. In cases like this it is a good idea to
3060 use brackets and avoid possible confusion.</P
3068 SUMMARY="Footer navigation table"
3079 HREF="language.tcl.html"
3088 HREF="cdl-guide.html"
3097 HREF="language.interface.html"
3107 >An Introduction to Tcl</TD
3113 HREF="language.html"
projects / karo-tx-redboot.git / blob