doc/html/cdl-guide/ref.calculated.html

   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.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >calculated</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="The eCos Component Writer's Guide"
  20 HREF="cdl-guide.html"><LINK
  21 REL="UP"
  22 TITLE="CDL Language Specification"
  23 HREF="reference.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="active_if"
  26 HREF="ref.active-if.html"><LINK
  27 REL="NEXT"
  28 TITLE="compile"
  29 HREF="ref.compile.html"></HEAD
  30 ><BODY
  31 CLASS="REFENTRY"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >The <SPAN
  50 CLASS="APPLICATION"
  51 >eCos</SPAN
  52 > Component Writer's Guide</TH
  53 ></TR
  54 ><TR
  55 ><TD
  56 WIDTH="10%"
  57 ALIGN="left"
  58 VALIGN="bottom"
  59 ><A
  60 HREF="ref.active-if.html"
  61 ACCESSKEY="P"
  62 >Prev</A
  63 ></TD
  64 ><TD
  65 WIDTH="80%"
  66 ALIGN="center"
  67 VALIGN="bottom"
  68 ></TD
  69 ><TD
  70 WIDTH="10%"
  71 ALIGN="right"
  72 VALIGN="bottom"
  73 ><A
  74 HREF="ref.compile.html"
  75 ACCESSKEY="N"
  76 >Next</A
  77 ></TD
  78 ></TR
  79 ></TABLE
  80 ><HR
  81 ALIGN="LEFT"
  82 WIDTH="100%"></DIV
  83 ><H1
  84 ><A
  85 NAME="REF.CALCULATED"><SPAN
  86 CLASS="PROPERTY"
  87 >calculated</SPAN
  88 ></H1
  89 ><DIV
  90 CLASS="REFNAMEDIV"
  91 ><A
  92 NAME="AEN3722"
  93 ></A
  94 ><H2
  95 >Name</H2
  96 >Property <SPAN
  97 CLASS="PROPERTY"
  98 >calculated</SPAN
  99 >&nbsp;--&nbsp;Used if the current option's value is not user-modifiable,
 100 but is calculated using a suitable CDL expression.</DIV
 101 ><DIV
 102 CLASS="REFSYNOPSISDIV"
 103 ><A
 104 NAME="AEN3726"><H2
 105 >Synopsis</H2
 106 ><TABLE
 107 BORDER="5"
 108 BGCOLOR="#E0E0F0"
 109 WIDTH="70%"
 110 ><TR
 111 ><TD
 112 ><PRE
 113 CLASS="SYNOPSIS"
 114 >cdl_option &lt;name&gt; {
 115     calculated &lt;expression&gt;
 116     &#8230;
 117 }</PRE
 118 ></TD
 119 ></TR
 120 ></TABLE
 121 ></DIV
 122 ><DIV
 123 CLASS="REFSECT1"
 124 ><A
 125 NAME="AEN3728"
 126 ></A
 127 ><H2
 128 >Description</H2
 129 ><P
 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
 132 <SPAN
 133 CLASS="PROPERTY"
 134 >calculated</SPAN
 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
 139 > in Chapter 3</A
 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
 144 option's flavor:</P
 145 ><P
 146 ></P
 147 ><DIV
 148 CLASS="VARIABLELIST"
 149 ><DL
 150 ><DT
 151 ><TT
 152 CLASS="LITERAL"
 153 >flavor none</TT
 154 ></DT
 155 ><DD
 156 ><P
 157 >Options with this flavor have no value, so the <SPAN
 158 CLASS="PROPERTY"
 159 >calculated</SPAN
 160 >
 161 property is not applicable.</P
 162 ></DD
 163 ><DT
 164 ><TT
 165 CLASS="LITERAL"
 166 >flavor bool</TT
 167 ></DT
 168 ><DD
 169 ><P
 170 >If the expression evaluates to a non-zero result the option is
 171 enabled, otherwise it is disabled.</P
 172 ></DD
 173 ><DT
 174 ><TT
 175 CLASS="LITERAL"
 176 >flavor booldata</TT
 177 ></DT
 178 ><DD
 179 ><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
 182 ></DD
 183 ><DT
 184 ><TT
 185 CLASS="LITERAL"
 186 >flavor data</TT
 187 ></DT
 188 ><DD
 189 ><P
 190 >The value of the option is the result of evaluating the expression.</P
 191 ></DD
 192 ></DL
 193 ></DIV
 194 ><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
 198 ><P
 199 ></P
 200 ><UL
 201 ><LI
 202 ><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
 207 option <TT
 208 CLASS="LITERAL"
 209 >CYGARC_BIGENDIAN</TT
 210 > which is calculated in
 211 some architectural HAL packages but user-modifiable in others.</P
 212 ></LI
 213 ><LI
 214 ><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
 223 <TT
 224 CLASS="LITERAL"
 225 >{&nbsp;CYG_HAL_STARTUP&nbsp;==&nbsp;"ROM"&nbsp;}</TT
 226 >,
 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
 230 CLASS="PROPERTY"
 231 >default_value</SPAN
 232 > based on
 233 <TT
 234 CLASS="LITERAL"
 235 >CYG_HAL_STARTUP</TT
 236 >, but that is for the component
 237 writer to decide.</P
 238 ></LI
 239 ><LI
 240 ><P
 241 >Sometimes it should be possible to perform a particular test at
 242 compile-time, for example by using a C preprocessor
 243 <TT
 244 CLASS="LITERAL"
 245 >#if</TT
 246 > construct. However the preprocessor has only
 247 limited functionality, for example it cannot perform string
 248 comparisons. CDL expressions are more powerful.</P
 249 ></LI
 250 ><LI
 251 ><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
 257 ></LI
 258 ></UL
 259 ><P
 260 >Alternatives to using calculated options include the following:</P
 261 ><P
 262 ></P
 263 ><UL
 264 ><LI
 265 ><P
 266 >CDL <A
 267 HREF="language.interface.html"
 268 >interfaces</A
 269 > are a form of
 270 calculated option intended as an abstraction mechanism. An interface
 271 can be used to express the concept of <SPAN
 272 CLASS="emphasis"
 273 ><I
 274 CLASS="EMPHASIS"
 275 >any
 276 scheduler</I
 277 ></SPAN
 278 >, as opposed to a specific one such as the bitmap scheduler.</P
 279 ></LI
 280 ><LI
 281 ><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
 284 effect using a <A
 285 HREF="ref.define-proc.html"
 286 ><SPAN
 287 CLASS="PROPERTY"
 288 >define_proc</SPAN
 289 ></A
 290 >
 291 property or one of the other properties related to header file
 292 generation.</P
 293 ></LI
 294 ></UL
 295 ><DIV
 296 CLASS="TIP"
 297 ><BLOCKQUOTE
 298 CLASS="TIP"
 299 ><P
 300 ><B
 301 >Tip: </B
 302 >If the first entry in a <SPAN
 303 CLASS="PROPERTY"
 304 >calculated</SPAN
 305 > expression is a negative
 306 number, for example <TT
 307 CLASS="LITERAL"
 308 >calculated&nbsp;-1</TT
 309 > then this
 310 can be misinterpreted as an option instead of as part of the
 311 expression. Currently the <SPAN
 312 CLASS="PROPERTY"
 313 >calculated</SPAN
 314 > property does not take any
 315 options, but this may change in future. Option processing halts at the
 316 sequence <TT
 317 CLASS="LITERAL"
 318 >--</TT
 319 >, so the desired value can be expressed
 320 safely using
 321 <TT
 322 CLASS="LITERAL"
 323 >calculated&nbsp;--&nbsp;-1</TT
 324 ></P
 325 ></BLOCKQUOTE
 326 ></DIV
 327 ><DIV
 328 CLASS="WARNING"
 329 ><P
 330 ></P
 331 ><TABLE
 332 CLASS="WARNING"
 333 BORDER="1"
 334 WIDTH="100%"
 335 ><TR
 336 ><TD
 337 ALIGN="CENTER"
 338 ><B
 339 >Warning</B
 340 ></TD
 341 ></TR
 342 ><TR
 343 ><TD
 344 ALIGN="LEFT"
 345 ><P
 346 >Some of the CDL scripts in current <SPAN
 347 CLASS="APPLICATION"
 348 >eCos</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
 354 CLASS="PROPERTY"
 355 >define_proc</SPAN
 356 > properties cannot yet access
 357 the configuration data so it may be necessary to use <SPAN
 358 CLASS="PROPERTY"
 359 >calculated</SPAN
 360 >
 361 properties to access the data and perform the desired manipulation via
 362 a <SPAN
 363 CLASS="APPLICATION"
 364 >CDL</SPAN
 365 > expression. New scripts should use calculated options only in
 366 accordance with the guidelines.</P
 367 ></TD
 368 ></TR
 369 ></TABLE
 370 ></DIV
 371 ><DIV
 372 CLASS="NOTE"
 373 ><BLOCKQUOTE
 374 CLASS="NOTE"
 375 ><P
 376 ><B
 377 >Note: </B
 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
 381 ></BLOCKQUOTE
 382 ></DIV
 383 ><DIV
 384 CLASS="NOTE"
 385 ><BLOCKQUOTE
 386 CLASS="NOTE"
 387 ><P
 388 ><B
 389 >Note: </B
 390 >It has been suggested that having options which are not
 391 user-modifiable is potentially confusing, and that a top-level
 392 <TT
 393 CLASS="LITERAL"
 394 >cdl_constant</TT
 395 > command should be added to the
 396 language instead of or in addition to the <SPAN
 397 CLASS="PROPERTY"
 398 >calculated</SPAN
 399 > property. Such
 400 a change is under consideration. However because the value of a
 401 calculated option can depend on other options, it is not necessarily
 402 constant.</P
 403 ></BLOCKQUOTE
 404 ></DIV
 405 ></DIV
 406 ><DIV
 407 CLASS="REFSECT1"
 408 ><A
 409 NAME="AEN3799"
 410 ></A
 411 ><H2
 412 >Example</H2
 413 ><TABLE
 414 BORDER="5"
 415 BGCOLOR="#E0E0F0"
 416 WIDTH="70%"
 417 ><TR
 418 ><TD
 419 ><PRE
 420 CLASS="PROGRAMLISTING"
 421 ># A constant on some target hardware, perhaps user-modifiable on other
 422 # targets.
 423 cdl_option CYGNUM_HAL_RTC_PERIOD {
 424     display       "Real-time clock period"
 425     flavor        data
 426     calculated    12500
 427 }</PRE
 428 ></TD
 429 ></TR
 430 ></TABLE
 431 ></DIV
 432 ><DIV
 433 CLASS="REFSECT1"
 434 ><A
 435 NAME="AEN3802"
 436 ></A
 437 ><H2
 438 >See Also</H2
 439 ><P
 440 >Properties <A
 441 HREF="ref.default-value.html"
 442 ><SPAN
 443 CLASS="PROPERTY"
 444 >default_value</SPAN
 445 ></A
 446 >,
 447 <A
 448 HREF="ref.flavor.html"
 449 ><SPAN
 450 CLASS="PROPERTY"
 451 >flavor</SPAN
 452 ></A
 453 > and
 454 <A
 455 HREF="ref.legal-values.html"
 456 ><SPAN
 457 CLASS="PROPERTY"
 458 >legal_values</SPAN
 459 ></A
 460 >,</P
 461 ></DIV
 462 ><DIV
 463 CLASS="NAVFOOTER"
 464 ><HR
 465 ALIGN="LEFT"
 466 WIDTH="100%"><TABLE
 467 SUMMARY="Footer navigation table"
 468 WIDTH="100%"
 469 BORDER="0"
 470 CELLPADDING="0"
 471 CELLSPACING="0"
 472 ><TR
 473 ><TD
 474 WIDTH="33%"
 475 ALIGN="left"
 476 VALIGN="top"
 477 ><A
 478 HREF="ref.active-if.html"
 479 ACCESSKEY="P"
 480 >Prev</A
 481 ></TD
 482 ><TD
 483 WIDTH="34%"
 484 ALIGN="center"
 485 VALIGN="top"
 486 ><A
 487 HREF="cdl-guide.html"
 488 ACCESSKEY="H"
 489 >Home</A
 490 ></TD
 491 ><TD
 492 WIDTH="33%"
 493 ALIGN="right"
 494 VALIGN="top"
 495 ><A
 496 HREF="ref.compile.html"
 497 ACCESSKEY="N"
 498 >Next</A
 499 ></TD
 500 ></TR
 501 ><TR
 502 ><TD
 503 WIDTH="33%"
 504 ALIGN="left"
 505 VALIGN="top"
 506 ><SPAN
 507 CLASS="PROPERTY"
 508 >active_if</SPAN
 509 ></TD
 510 ><TD
 511 WIDTH="34%"
 512 ALIGN="center"
 513 VALIGN="top"
 514 ><A
 515 HREF="reference.html"
 516 ACCESSKEY="U"
 517 >Up</A
 518 ></TD
 519 ><TD
 520 WIDTH="33%"
 521 ALIGN="right"
 522 VALIGN="top"
 523 ><SPAN
 524 CLASS="PROPERTY"
 525 >compile</SPAN
 526 ></TD
 527 ></TR
 528 ></TABLE
 529 ></DIV
 530 ></BODY
 531 ></HTML
 532 >