OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [cdl-guide/] [ref.cdl-interface.html] - Blame information for rev 588

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 28 unneback
<!-- 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
>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.