doc/html/cdl-guide/language.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 >Interfaces</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="The CDL Language"
  23 HREF="language.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Values and Expressions"
  26 HREF="language.values.html"><LINK
  27 REL="NEXT"
  28 TITLE="Updating the ecos.db database"
  29 HREF="language.database.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  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="language.values.html"
  61 ACCESSKEY="P"
  62 >Prev</A
  63 ></TD
  64 ><TD
  65 WIDTH="80%"
  66 ALIGN="center"
  67 VALIGN="bottom"
  68 >Chapter 3. The CDL Language</TD
  69 ><TD
  70 WIDTH="10%"
  71 ALIGN="right"
  72 VALIGN="bottom"
  73 ><A
  74 HREF="language.database.html"
  75 ACCESSKEY="N"
  76 >Next</A
  77 ></TD
  78 ></TR
  79 ></TABLE
  80 ><HR
  81 ALIGN="LEFT"
  82 WIDTH="100%"></DIV
  83 ><DIV
  84 CLASS="SECT1"
  85 ><H1
  86 CLASS="SECT1"
  87 ><A
  88 NAME="LANGUAGE.INTERFACE">Interfaces</H1
  89 ><P
  90 >For many configurability requirements, options provide sufficient
  91 expressive power. However there are times when a higher level of
  92 abstraction is appropriate. As an example, suppose that some package
  93 relies on the presence of code that implements the standard kernel
  94 scheduling interface. However the requirement is no more stringent
  95 than this, so the constraint can be satisfied by the mlqueue
  96 scheduler, the bitmap scheduler, or any additional schedulers that may
  97 get implemented in future. A first attempt at expressing the
  98 dependency might be:</P
  99 ><TABLE
 100 BORDER="5"
 101 BGCOLOR="#E0E0F0"
 102 WIDTH="70%"
 103 ><TR
 104 ><TD
 105 ><PRE
 106 CLASS="PROGRAMLISTING"
 107 >    requires CYGSEM_KERNEL_SCHED_MLQUEUE || CYGSEM_KERNEL_SCHED_BITMAP</PRE
 108 ></TD
 109 ></TR
 110 ></TABLE
 111 ><P
 112 >This constraint will work with the current release, but it is limited.
 113 Suppose there is a new release of the kernel which adds another
 114 scheduler such as a deadline scheduler, or suppose that there is a new
 115 third party package which adds such a scheduler. The package
 116 containing the limited constraint would now have to be updated and
 117 another release made, with possible knock-on effects.</P
 118 ><P
 119 ><SPAN
 120 CLASS="APPLICATION"
 121 >CDL</SPAN
 122 > interfaces provide an abstraction mechanism: constraints can be
 123 expressed in terms of an abstract concept, for example
 124 &#8220;scheduler&#8221;, rather than specific implementations such as
 125 <TT
 126 CLASS="VARNAME"
 127 >CYGSEM_KERNEL_SCHED_MLQUEUE</TT
 128 > and
 129 <TT
 130 CLASS="VARNAME"
 131 >CYGSEM_KERNEL_SCHED_BITMAP</TT
 132 >. Basically an interface
 133 is a calculated configuration option:</P
 134 ><TABLE
 135 BORDER="5"
 136 BGCOLOR="#E0E0F0"
 137 WIDTH="70%"
 138 ><TR
 139 ><TD
 140 ><PRE
 141 CLASS="PROGRAMLISTING"
 142 >cdl_interface CYGINT_KERNEL_SCHEDULER {
 143     display  "Number of schedulers in this configuration"
 144     &#8230;
 145 }</PRE
 146 ></TD
 147 ></TR
 148 ></TABLE
 149 ><P
 150 >The individual schedulers can then implement this interface:</P
 151 ><TABLE
 152 BORDER="5"
 153 BGCOLOR="#E0E0F0"
 154 WIDTH="70%"
 155 ><TR
 156 ><TD
 157 ><PRE
 158 CLASS="PROGRAMLISTING"
 159 >cdl_option CYGSEM_KERNEL_SCHED_MLQUEUE {
 160     display       "Multi-level queue scheduler"
 161     default_value 1
 162     implements    CYGINT_KERNEL_SCHEDULER
 163     &#8230;
 164 }
 165
 166 cdl_option CYGSEM_KERNEL_SCHED_BITMAP {
 167     display       "Bitmap scheduler"
 168     default_value 0
 169     implements    CYGINT_KERNEL_SCHEDULER
 170     &#8230;
 171 }</PRE
 172 ></TD
 173 ></TR
 174 ></TABLE
 175 ><P
 176 >Future schedulers can also implement this interface. The value of an
 177 interface, for the purposes of expression evaluation, is the number of
 178 active and enabled options which implement this interface. Packages
 179 which rely on the presence of a scheduler can impose constraints such
 180 as:</P
 181 ><TABLE
 182 BORDER="5"
 183 BGCOLOR="#E0E0F0"
 184 WIDTH="70%"
 185 ><TR
 186 ><TD
 187 ><PRE
 188 CLASS="PROGRAMLISTING"
 189 >    requires CYGINT_KERNEL_SCHEDULER</PRE
 190 ></TD
 191 ></TR
 192 ></TABLE
 193 ><P
 194 >If none of the schedulers are enabled, or if the kernel package is not
 195 loaded, then <TT
 196 CLASS="VARNAME"
 197 >CYGINT_KERNEL_SCHEDULER</TT
 198 > will evaluate
 199 to <TT
 200 CLASS="LITERAL"
 201 >0</TT
 202 >. If at least one scheduler is active and
 203 enabled then the constraint will be satisfied.</P
 204 ><P
 205 >Because interfaces have a calculated value determined by the
 206 implementors, the <SPAN
 207 CLASS="PROPERTY"
 208 >default_value</SPAN
 209 > and <SPAN
 210 CLASS="PROPERTY"
 211 >calculated</SPAN
 212 > properties are not
 213 applicable and should not appear in the body of a <TT
 214 CLASS="LITERAL"
 215 >cdl_interface</TT
 216 >
 217 command. Interfaces have the <TT
 218 CLASS="LITERAL"
 219 >data</TT
 220 > flavor by
 221 default, but the <TT
 222 CLASS="LITERAL"
 223 >bool</TT
 224 > and
 225 <TT
 226 CLASS="LITERAL"
 227 >booldata</TT
 228 > flavors may be specified instead. A
 229 <TT
 230 CLASS="LITERAL"
 231 >bool</TT
 232 > interface is disabled if there are no active
 233 and enabled implementors, otherwise it is enabled. A
 234 <TT
 235 CLASS="LITERAL"
 236 >booldata</TT
 237 > interface is disabled if there are no
 238 active and enabled implementors, otherwise it is enabled and has a
 239 value corresponding to the number of these implementors. Other
 240 properties such as <SPAN
 241 CLASS="PROPERTY"
 242 >requires</SPAN
 243 > and <SPAN
 244 CLASS="PROPERTY"
 245 >compile</SPAN
 246 > can be used as normal.</P
 247 ><P
 248 >Some component writers will not want to use interfaces in this way.
 249 The reasoning is that their code will only have been tested with the
 250 existing schedulers, so the <SPAN
 251 CLASS="PROPERTY"
 252 >requires</SPAN
 253 > constraint needs to be
 254 expressed in terms of those schedulers; it is possible that the
 255 component will still work with a new scheduler, but there are no
 256 guarantees. Other component writers may take a more optimistic view
 257 and assume that their code will work with any scheduler until proven
 258 otherwise. It is up to individual component writers to decide which
 259 approach is most appropriate in any given case.</P
 260 ><P
 261 >One common use for interfaces is to describe the hardware
 262 functionality provided by a given target. For example the <SPAN
 263 CLASS="APPLICATION"
 264 >CDL</SPAN
 265 >
 266 scripts for a TCP/IP package might want to know whether or not the
 267 target hardware has an ethernet interface. Generally it is not
 268 necessary for the TCP/IP stack to know exactly which ethernet hardware
 269 is present, since there should be a device driver which implements the
 270 appropriate functionality. In <SPAN
 271 CLASS="APPLICATION"
 272 >CDL</SPAN
 273 > terms the device drivers should
 274 implement an interface <TT
 275 CLASS="VARNAME"
 276 >CYGHWR_NET_DRIVERS</TT
 277 >, and the
 278 <SPAN
 279 CLASS="APPLICATION"
 280 >CDL</SPAN
 281 > scripts for the TCP/IP stack can use this in appropriate
 282 expressions. </P
 283 ><DIV
 284 CLASS="NOTE"
 285 ><BLOCKQUOTE
 286 CLASS="NOTE"
 287 ><P
 288 ><B
 289 >Note: </B
 290 >Using the term <SPAN
 291 CLASS="emphasis"
 292 ><I
 293 CLASS="EMPHASIS"
 294 >interface</I
 295 ></SPAN
 296 > for this concept is
 297 sometimes confusing, since the term has various other meanings as
 298 well. In practice, it is often correct. If there is a configuration
 299 option that implements a given <SPAN
 300 CLASS="APPLICATION"
 301 >CDL</SPAN
 302 > interface, then usually this
 303 option will enable some code that provides a particular interface at
 304 the C or C++ level. For example an ethernet device driver implements
 305 the <SPAN
 306 CLASS="APPLICATION"
 307 >CDL</SPAN
 308 > interface <TT
 309 CLASS="VARNAME"
 310 >CYGHWR_NET_DRIVERS</TT
 311 >, and also
 312 implements a set of C functions that can be used by the TCP/IP stack.
 313 Similarly <TT
 314 CLASS="VARNAME"
 315 >CYGSEM_KERNEL_SCHED_MLQUEUE</TT
 316 > implements
 317 the <SPAN
 318 CLASS="APPLICATION"
 319 >CDL</SPAN
 320 > interface <TT
 321 CLASS="VARNAME"
 322 >CYGINT_KERNEL_SCHEDULER</TT
 323 > and
 324 also provides the appropriate scheduling functions.</P
 325 ></BLOCKQUOTE
 326 ></DIV
 327 ></DIV
 328 ><DIV
 329 CLASS="NAVFOOTER"
 330 ><HR
 331 ALIGN="LEFT"
 332 WIDTH="100%"><TABLE
 333 SUMMARY="Footer navigation table"
 334 WIDTH="100%"
 335 BORDER="0"
 336 CELLPADDING="0"
 337 CELLSPACING="0"
 338 ><TR
 339 ><TD
 340 WIDTH="33%"
 341 ALIGN="left"
 342 VALIGN="top"
 343 ><A
 344 HREF="language.values.html"
 345 ACCESSKEY="P"
 346 >Prev</A
 347 ></TD
 348 ><TD
 349 WIDTH="34%"
 350 ALIGN="center"
 351 VALIGN="top"
 352 ><A
 353 HREF="cdl-guide.html"
 354 ACCESSKEY="H"
 355 >Home</A
 356 ></TD
 357 ><TD
 358 WIDTH="33%"
 359 ALIGN="right"
 360 VALIGN="top"
 361 ><A
 362 HREF="language.database.html"
 363 ACCESSKEY="N"
 364 >Next</A
 365 ></TD
 366 ></TR
 367 ><TR
 368 ><TD
 369 WIDTH="33%"
 370 ALIGN="left"
 371 VALIGN="top"
 372 >Values and Expressions</TD
 373 ><TD
 374 WIDTH="34%"
 375 ALIGN="center"
 376 VALIGN="top"
 377 ><A
 378 HREF="language.html"
 379 ACCESSKEY="U"
 380 >Up</A
 381 ></TD
 382 ><TD
 383 WIDTH="33%"
 384 ALIGN="right"
 385 VALIGN="top"
 386 >Updating the <SPAN
 387 CLASS="DATABASE"
 388 >ecos.db</SPAN
 389 > database</TD
 390 ></TR
 391 ></TABLE
 392 ></DIV
 393 ></BODY
 394 ></HTML
 395 >