doc/html/cdl-guide/ref.cdl-interface.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 >cdl_interface</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="cdl_package"
  26 HREF="ref.cdl-package.html"><LINK
  27 REL="NEXT"
  28 TITLE="active_if"
  29 HREF="ref.active-if.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.cdl-package.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.active-if.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.CDL-INTERFACE"><TT
  86 CLASS="LITERAL"
  87 >cdl_interface</TT
  88 ></H1
  89 ><DIV
  90 CLASS="REFNAMEDIV"
  91 ><A
  92 NAME="AEN3484"
  93 ></A
  94 ><H2
  95 >Name</H2
  96 >Command <TT
  97 CLASS="LITERAL"
  98 >cdl_interface</TT
  99 >&nbsp;--&nbsp;Define an interface, functionality that can be provided by
 100 a number of different implementations.</DIV
 101 ><DIV
 102 CLASS="REFSYNOPSISDIV"
 103 ><A
 104 NAME="AEN3488"><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_interface &lt;name&gt; {
 115     &#8230;
 116 }</PRE
 117 ></TD
 118 ></TR
 119 ></TABLE
 120 ></DIV
 121 ><DIV
 122 CLASS="REFSECT1"
 123 ><A
 124 NAME="AEN3490"
 125 ></A
 126 ><H2
 127 >Description</H2
 128 ><P
 129 >An interface is a special type of calculated configuration option.
 130 It provides an abstraction mechanism that is often useful in <SPAN
 131 CLASS="APPLICATION"
 132 >CDL</SPAN
 133 >
 134 expressions. As an example, suppose that some package relies on the
 135 presence of code that implements the standard kernel scheduling
 136 interface. However the requirement is no more stringent than this, so
 137 the constraint can be satisfied by the mlqueue scheduler, the bitmap
 138 scheduler, or any additional schedulers that may get implemented in
 139 future. A first attempt at expressing the dependency might be:</P
 140 ><TABLE
 141 BORDER="5"
 142 BGCOLOR="#E0E0F0"
 143 WIDTH="70%"
 144 ><TR
 145 ><TD
 146 ><PRE
 147 CLASS="PROGRAMLISTING"
 148 >    requires CYGSEM_KERNEL_SCHED_MLQUEUE || CYGSEM_KERNEL_SCHED_BITMAP</PRE
 149 ></TD
 150 ></TR
 151 ></TABLE
 152 ><P
 153 >This constraint is limited, it may need to be changed if a new
 154 scheduler were to be added to the system. Interfaces provide a way of
 155 expressing more general relationships:</P
 156 ><TABLE
 157 BORDER="5"
 158 BGCOLOR="#E0E0F0"
 159 WIDTH="70%"
 160 ><TR
 161 ><TD
 162 ><PRE
 163 CLASS="PROGRAMLISTING"
 164 >    requires CYGINT_KERNEL_SCHEDULER</PRE
 165 ></TD
 166 ></TR
 167 ></TABLE
 168 ><P
 169 >The interface <TT
 170 CLASS="LITERAL"
 171 >CYGINT_KERNEL_SCHEDULER</TT
 172 > is
 173 <SPAN
 174 CLASS="emphasis"
 175 ><I
 176 CLASS="EMPHASIS"
 177 >implemented</I
 178 ></SPAN
 179 > by both the mlqueue and bitmap
 180 schedulers, and may be implemented by future schedulers as well. The
 181 value of an interface is the number of implementors that are active
 182 and enabled, so in a typical configuration only one scheduler will be
 183 in use and the value of the interface will be <TT
 184 CLASS="LITERAL"
 185 >1</TT
 186 >. If
 187 all schedulers are disabled then the interface will have a value
 188 <TT
 189 CLASS="LITERAL"
 190 >0</TT
 191 > and the <SPAN
 192 CLASS="PROPERTY"
 193 >requires</SPAN
 194 > constraint will not be
 195 satisfied.</P
 196 ><P
 197 >Some component writers may prefer to use the first <SPAN
 198 CLASS="PROPERTY"
 199 >requires</SPAN
 200 >
 201 constraint on the grounds that the code will only have been tested
 202 with the mlqueue and bitmap schedulers and cannot be guaranteed to
 203 work with any new schedulers. Other component writers may take a more
 204 optimistic view and assume that their code will work with any
 205 scheduler until proven otherwise.</P
 206 ><P
 207 >Interfaces must be defined in CDL scripts, just like options,
 208 components and packages. This involves the command <TT
 209 CLASS="LITERAL"
 210 >cdl_interface</TT
 211 >
 212 which takes two arguments, a name and a body. The name must be a valid
 213 C preprocessor identifier: a sequence of upper or lower case letters,
 214 digits or underscores, starting with a non-digit character;
 215 identifiers beginning with an underscore should normally be avoided
 216 because they may clash with system packages or with identifiers
 217 reserved for use by the compiler. Within a single configuration, names
 218 must be unique. If a configuration contained two packages which
 219 defined the same entity <TT
 220 CLASS="LITERAL"
 221 >CYGIMP_SOME_OPTION</TT
 222 >, any
 223 references to that entity in a <SPAN
 224 CLASS="PROPERTY"
 225 >requires</SPAN
 226 > property or any other
 227 expression would be ambiguous. It is possible for a given name to be
 228 used by two different packages if those packages should never be
 229 loaded into a single configuration. For example, architectural HAL
 230 packages are allowed to re-use names because a single configuration
 231 cannot target two different architectures. For a recommended naming
 232 convention see <A
 233 HREF="package.contents.html"
 234 >the Section called <I
 235 >Package Contents and Layout</I
 236 > in Chapter 2</A
 237 >.</P
 238 ><P
 239 >The second argument to <TT
 240 CLASS="LITERAL"
 241 >cdl_interface</TT
 242 > is a body of properties,
 243 typically surrounded by braces so that the Tcl interpreter treats it
 244 as a single argument. This body will be processed by a recursive
 245 invocation of the Tcl interpreter, extended with additional commands
 246 for the various properties that are allowed inside a <TT
 247 CLASS="LITERAL"
 248 >cdl_interface</TT
 249 >.
 250 The valid properties are a subset of those for a <TT
 251 CLASS="LITERAL"
 252 >cdl_option</TT
 253 >.</P
 254 ><P
 255 ></P
 256 ><DIV
 257 CLASS="VARIABLELIST"
 258 ><DL
 259 ><DT
 260 ><A
 261 HREF="ref.active-if.html"
 262 ><SPAN
 263 CLASS="PROPERTY"
 264 >active_if</SPAN
 265 ></A
 266 ></DT
 267 ><DD
 268 ><P
 269 >Allow additional control over the active state of this interface.</P
 270 ></DD
 271 ><DT
 272 ><A
 273 HREF="ref.compile.html"
 274 ><SPAN
 275 CLASS="PROPERTY"
 276 >compile</SPAN
 277 ></A
 278 ></DT
 279 ><DD
 280 ><P
 281 >List the source files that should be built if this interface is active.</P
 282 ></DD
 283 ><DT
 284 ><A
 285 HREF="ref.define.html"
 286 ><SPAN
 287 CLASS="PROPERTY"
 288 >define</SPAN
 289 ></A
 290 ></DT
 291 ><DD
 292 ><P
 293 >Specify additional <TT
 294 CLASS="LITERAL"
 295 >#define</TT
 296 > symbols that should go
 297 into the owning package's configuration header file.</P
 298 ></DD
 299 ><DT
 300 ><A
 301 HREF="ref.define-format.html"
 302 ><SPAN
 303 CLASS="PROPERTY"
 304 >define_format</SPAN
 305 ></A
 306 ></DT
 307 ><DD
 308 ><P
 309 >Control how the interface's value will appear in the configuration header
 310 file.</P
 311 ></DD
 312 ><DT
 313 ><A
 314 HREF="ref.define-proc.html"
 315 ><SPAN
 316 CLASS="PROPERTY"
 317 >define_proc</SPAN
 318 ></A
 319 ></DT
 320 ><DD
 321 ><P
 322 >Use a fragment of Tcl code to output additional data to
 323 configuration header files.</P
 324 ></DD
 325 ><DT
 326 ><A
 327 HREF="ref.description.html"
 328 ><SPAN
 329 CLASS="PROPERTY"
 330 >description</SPAN
 331 ></A
 332 ></DT
 333 ><DD
 334 ><P
 335 >Provide a textual description for this interface.</P
 336 ></DD
 337 ><DT
 338 ><A
 339 HREF="ref.display.html"
 340 ><SPAN
 341 CLASS="PROPERTY"
 342 >display</SPAN
 343 ></A
 344 ></DT
 345 ><DD
 346 ><P
 347 >Provide a short string describing this interface.</P
 348 ></DD
 349 ><DT
 350 ><A
 351 HREF="ref.doc.html"
 352 ><SPAN
 353 CLASS="PROPERTY"
 354 >doc</SPAN
 355 ></A
 356 ></DT
 357 ><DD
 358 ><P
 359 >The location of on-line documentation for this interface.</P
 360 ></DD
 361 ><DT
 362 ><A
 363 HREF="ref.flavor.html"
 364 ><SPAN
 365 CLASS="PROPERTY"
 366 >flavor</SPAN
 367 ></A
 368 ></DT
 369 ><DD
 370 ><P
 371 >Interfaces have the <TT
 372 CLASS="LITERAL"
 373 >data</TT
 374 > flavor by default, but
 375 they can also be given the <TT
 376 CLASS="LITERAL"
 377 >bool</TT
 378 > or
 379 <TT
 380 CLASS="LITERAL"
 381 >booldata</TT
 382 > flavor when necessary. A
 383 <TT
 384 CLASS="LITERAL"
 385 >bool</TT
 386 > interface is disabled if there are no active
 387 and enabled implementors, otherwise it is enabled. A
 388 <TT
 389 CLASS="LITERAL"
 390 >booldata</TT
 391 > interface is also disabled if there are no
 392 active and enabled implementors, otherwise it is enabled and the data
 393 is a number corresponding to the number of these implementors.</P
 394 ></DD
 395 ><DT
 396 ><A
 397 HREF="ref.if-define.html"
 398 ><SPAN
 399 CLASS="PROPERTY"
 400 >if_define</SPAN
 401 ></A
 402 ></DT
 403 ><DD
 404 ><P
 405 >Output a common preprocessor construct to a configuration header file. </P
 406 ></DD
 407 ><DT
 408 ><A
 409 HREF="ref.implements.html"
 410 ><SPAN
 411 CLASS="PROPERTY"
 412 >implements</SPAN
 413 ></A
 414 ></DT
 415 ><DD
 416 ><P
 417 >If this interface is active it provides one instance of a more general
 418 interface. </P
 419 ></DD
 420 ><DT
 421 ><A
 422 HREF="ref.legal-values.html"
 423 ><SPAN
 424 CLASS="PROPERTY"
 425 >legal_values</SPAN
 426 ></A
 427 ></DT
 428 ><DD
 429 ><P
 430 >Interfaces always have a small numerical value. The <SPAN
 431 CLASS="PROPERTY"
 432 >legal_values</SPAN
 433 > can
 434 be used to apply additional constraints such as an upper limit.</P
 435 ></DD
 436 ><DT
 437 ><A
 438 HREF="ref.make.html"
 439 ><SPAN
 440 CLASS="PROPERTY"
 441 >make</SPAN
 442 ></A
 443 ></DT
 444 ><DD
 445 ><P
 446 >An additional custom build step associated with this option, resulting
 447 in a target that should not go directly into a library.</P
 448 ></DD
 449 ><DT
 450 ><A
 451 HREF="ref.make-object.html"
 452 ><SPAN
 453 CLASS="PROPERTY"
 454 >make_object</SPAN
 455 ></A
 456 ></DT
 457 ><DD
 458 ><P
 459 >An additional custom build step associated with this option, resulting
 460 in an object file that should go into a library.</P
 461 ></DD
 462 ><DT
 463 ><A
 464 HREF="ref.no-define.html"
 465 ><SPAN
 466 CLASS="PROPERTY"
 467 >no_define</SPAN
 468 ></A
 469 ></DT
 470 ><DD
 471 ><P
 472 >Suppress the normal generation of a preprocessor
 473 <TT
 474 CLASS="LITERAL"
 475 >#define</TT
 476 > symbol in a configuration header file.</P
 477 ></DD
 478 ><DT
 479 ><A
 480 HREF="ref.parent.html"
 481 ><SPAN
 482 CLASS="PROPERTY"
 483 >parent</SPAN
 484 ></A
 485 ></DT
 486 ><DD
 487 ><P
 488 >Control the location of this option in the configuration hierarchy. </P
 489 ></DD
 490 ><DT
 491 ><A
 492 HREF="ref.requires.html"
 493 ><SPAN
 494 CLASS="PROPERTY"
 495 >requires</SPAN
 496 ></A
 497 ></DT
 498 ><DD
 499 ><P
 500 >List constraints that the configuration should satisfy if this option is
 501 active and enabled.</P
 502 ></DD
 503 ></DL
 504 ></DIV
 505 ><P
 506 >A number of properties are not applicable to interfaces:</P
 507 ><P
 508 ></P
 509 ><DIV
 510 CLASS="VARIABLELIST"
 511 ><DL
 512 ><DT
 513 ><A
 514 HREF="ref.calculated.html"
 515 ><SPAN
 516 CLASS="PROPERTY"
 517 >calculated</SPAN
 518 ></A
 519 ></DT
 520 ><DD
 521 ><P
 522 >Interfaces are always calculated, based on the number of active and
 523 enabled entities that implement the interface.</P
 524 ></DD
 525 ><DT
 526 ><A
 527 HREF="ref.default-value.html"
 528 ><SPAN
 529 CLASS="PROPERTY"
 530 >default_value</SPAN
 531 ></A
 532 ></DT
 533 ><DD
 534 ><P
 535 >Interface values are calculated so a <SPAN
 536 CLASS="PROPERTY"
 537 >default_value</SPAN
 538 > property would be
 539 meaningless.</P
 540 ></DD
 541 ></DL
 542 ></DIV
 543 ><P
 544 >Interfaces are not containers, so they cannot hold other entities such
 545 as options or components.</P
 546 ><P
 547 >A commonly used constraint on interface values takes the form:</P
 548 ><TABLE
 549 BORDER="5"
 550 BGCOLOR="#E0E0F0"
 551 WIDTH="70%"
 552 ><TR
 553 ><TD
 554 ><PRE
 555 CLASS="PROGRAMLISTING"
 556 >    requires CYGINT_KERNEL_SCHEDULER == 1</PRE
 557 ></TD
 558 ></TR
 559 ></TABLE
 560 ><P
 561 >This constraint specifies that there can be only one scheduler in the
 562 system. In some circumstances it is possible for the configuration
 563 tools to detect this pattern and act accordingly, so for example
 564 enabling the bitmap scheduler would automatically disable the mlqueue
 565 scheduler.</P
 566 ></DIV
 567 ><DIV
 568 CLASS="REFSECT1"
 569 ><A
 570 NAME="AEN3644"
 571 ></A
 572 ><H2
 573 >Example</H2
 574 ><TABLE
 575 BORDER="5"
 576 BGCOLOR="#E0E0F0"
 577 WIDTH="70%"
 578 ><TR
 579 ><TD
 580 ><PRE
 581 CLASS="PROGRAMLISTING"
 582 >cdl_interface CYGINT_KERNEL_SCHEDULER {
 583     display  "Number of schedulers in this configuration"
 584     requires 1 == CYGINT_KERNEL_SCHEDULER
 585 }</PRE
 586 ></TD
 587 ></TR
 588 ></TABLE
 589 ></DIV
 590 ><DIV
 591 CLASS="REFSECT1"
 592 ><A
 593 NAME="AEN3647"
 594 ></A
 595 ><H2
 596 >See Also</H2
 597 ><P
 598 >Property <A
 599 HREF="ref.implements.html"
 600 ><SPAN
 601 CLASS="PROPERTY"
 602 >implements</SPAN
 603 ></A
 604 >,
 605 command <A
 606 HREF="ref.cdl-option.html"
 607 ><TT
 608 CLASS="LITERAL"
 609 >cdl_option</TT
 610 ></A
 611 >.
 612 command <A
 613 HREF="ref.cdl-component.html"
 614 ><TT
 615 CLASS="LITERAL"
 616 >cdl_component</TT
 617 ></A
 618 >,
 619 command <A
 620 HREF="ref.cdl-package.html"
 621 ><TT
 622 CLASS="LITERAL"
 623 >cdl_package</TT
 624 ></A
 625 >.</P
 626 ></DIV
 627 ><DIV
 628 CLASS="NAVFOOTER"
 629 ><HR
 630 ALIGN="LEFT"
 631 WIDTH="100%"><TABLE
 632 SUMMARY="Footer navigation table"
 633 WIDTH="100%"
 634 BORDER="0"
 635 CELLPADDING="0"
 636 CELLSPACING="0"
 637 ><TR
 638 ><TD
 639 WIDTH="33%"
 640 ALIGN="left"
 641 VALIGN="top"
 642 ><A
 643 HREF="ref.cdl-package.html"
 644 ACCESSKEY="P"
 645 >Prev</A
 646 ></TD
 647 ><TD
 648 WIDTH="34%"
 649 ALIGN="center"
 650 VALIGN="top"
 651 ><A
 652 HREF="cdl-guide.html"
 653 ACCESSKEY="H"
 654 >Home</A
 655 ></TD
 656 ><TD
 657 WIDTH="33%"
 658 ALIGN="right"
 659 VALIGN="top"
 660 ><A
 661 HREF="ref.active-if.html"
 662 ACCESSKEY="N"
 663 >Next</A
 664 ></TD
 665 ></TR
 666 ><TR
 667 ><TD
 668 WIDTH="33%"
 669 ALIGN="left"
 670 VALIGN="top"
 671 ><TT
 672 CLASS="LITERAL"
 673 >cdl_package</TT
 674 ></TD
 675 ><TD
 676 WIDTH="34%"
 677 ALIGN="center"
 678 VALIGN="top"
 679 ><A
 680 HREF="reference.html"
 681 ACCESSKEY="U"
 682 >Up</A
 683 ></TD
 684 ><TD
 685 WIDTH="33%"
 686 ALIGN="right"
 687 VALIGN="top"
 688 ><SPAN
 689 CLASS="PROPERTY"
 690 >active_if</SPAN
 691 ></TD
 692 ></TR
 693 ></TABLE
 694 ></DIV
 695 ></BODY
 696 ></HTML
 697 >