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. -->
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="CDL Language Specification"
23 HREF="reference.html"><LINK
26 HREF="ref.active-if.html"><LINK
29 HREF="ref.compile.html"></HEAD
40 SUMMARY="Header navigation table"
52 > Component Writer's Guide</TH
60 HREF="ref.active-if.html"
74 HREF="ref.compile.html"
85 NAME="REF.CALCULATED"><SPAN
99 > -- Used if the current option's value is not user-modifiable,
100 but is calculated using a suitable CDL expression.</DIV
102 CLASS="REFSYNOPSISDIV"
114 >cdl_option <name> {
115 calculated <expression>
130 >In some cases it is useful to have a configuration option whose value
131 cannot be modified directly by the user. This can be achieved using a
135 >, which takes a CDL expression as argument (see <A
136 HREF="language.values.html#LANGUAGE.EXPRESSION"
137 >the Section called <I
138 >Ordinary Expressions</I
140 > for a description of expression
141 syntax). The configuration system evaluates the expression when the
142 current package is loaded and whenever there is a change to any other
143 option referenced in the expression. The result depends on the
157 >Options with this flavor have no value, so the <SPAN
161 property is not applicable.</P
170 >If the expression evaluates to a non-zero result the option is
171 enabled, otherwise it is disabled.</P
180 >If the result of evaluating the expression is zero then the option is
181 disabled, otherwise the option is enabled and its value is the result.</P
190 >The value of the option is the result of evaluating the expression.</P
195 >There are a number of valid uses for calculated options, and there are
196 also many cases where some other CDL facility would be more
197 appropriate. Valid uses of calculated options include the following:</P
203 >On some target hardware a particular feature may be user-configurable,
204 while on other targets it is fixed. For example some processors can
205 operate in either big-endian or little-endian mode, while other
206 processors do not provide any choice. It is possible to have an
209 >CYGARC_BIGENDIAN</TT
210 > which is calculated in
211 some architectural HAL packages but user-modifiable in others.</P
215 >Calculated options can provide an alternative way for one package to
216 affect the behavior of another one. Suppose a package may provide two
217 possible implementations, a preferred one involving self-modifying
218 code and a slower alternative. If the system involves a ROM bootstrap
219 then the slower alternative must be used, but it would be
220 inappropriate to modify the startup option in every HAL to impose
221 constraints on this package. Instead it is possible to have a
222 calculated option whose value is
225 >{ CYG_HAL_STARTUP == "ROM" }</TT
227 and which has appropriate consequences. Arguably this is a spurious
228 example, and it should be a user choice whether or not to use
229 self-modifying code with a <SPAN
236 >, but that is for the component
241 >Sometimes it should be possible to perform a particular test at
242 compile-time, for example by using a C preprocessor
246 > construct. However the preprocessor has only
247 limited functionality, for example it cannot perform string
248 comparisons. CDL expressions are more powerful.</P
252 >Occasionally a particular sub-expression may occur multiple times in
253 a CDL script. If the sub-expression is sufficiently complex then it
254 may be worthwhile to have a calculated option whose value is the
255 sub-expression, and then reference that calculated option in the
256 appropriate places. </P
260 >Alternatives to using calculated options include the following:</P
267 HREF="language.interface.html"
270 calculated option intended as an abstraction mechanism. An interface
271 can be used to express the concept of <SPAN
278 >, as opposed to a specific one such as the bitmap scheduler.</P
282 >If a calculated option would serve only to add additional information
283 to a configuration header file, it may be possible to achieve the same
285 HREF="ref.define-proc.html"
291 property or one of the other properties related to header file
302 >If the first entry in a <SPAN
305 > expression is a negative
306 number, for example <TT
308 >calculated -1</TT
310 can be misinterpreted as an option instead of as part of the
311 expression. Currently the <SPAN
314 > property does not take any
315 options, but this may change in future. Option processing halts at the
319 >, so the desired value can be expressed
323 >calculated -- -1</TT
346 >Some of the CDL scripts in current <SPAN
349 > releases make excessive use
350 of calculated options. This is partly because the recommended
351 alternatives were not always available at the time the scripts were
352 written. It is also partly because there is still some missing
353 functionality, for example <SPAN
356 > properties cannot yet access
357 the configuration data so it may be necessary to use <SPAN
361 properties to access the data and perform the desired manipulation via
365 > expression. New scripts should use calculated options only in
366 accordance with the guidelines.</P
378 >For options with the booldata flavor the current CDL syntax does not
379 allow the enabled flag and the value to be calculated separately.
380 Functionality to permit this may be added in a future release.</P
390 >It has been suggested that having options which are not
391 user-modifiable is potentially confusing, and that a top-level
395 > command should be added to the
396 language instead of or in addition to the <SPAN
400 a change is under consideration. However because the value of a
401 calculated option can depend on other options, it is not necessarily
420 CLASS="PROGRAMLISTING"
421 ># A constant on some target hardware, perhaps user-modifiable on other
423 cdl_option CYGNUM_HAL_RTC_PERIOD {
424 display "Real-time clock period"
441 HREF="ref.default-value.html"
448 HREF="ref.flavor.html"
455 HREF="ref.legal-values.html"
467 SUMMARY="Footer navigation table"
478 HREF="ref.active-if.html"
487 HREF="cdl-guide.html"
496 HREF="ref.compile.html"
515 HREF="reference.html"