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

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [cdl-guide/] [language.commands.html] - Blame information for rev 593

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 Commands</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="The CDL Language"
26 
HREF="language.html"><LINK
27 
REL="NEXT"
28 
TITLE="CDL Properties"
29 
HREF="language.properties.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.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.properties.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.COMMANDS">CDL Commands</H1
89 
><P
90 
>There are four <SPAN
91 
CLASS="APPLICATION"
92 
>CDL</SPAN
93 
>-related commands which can occur at the top-level
94 
of a <SPAN
95 
CLASS="APPLICATION"
96 
>CDL</SPAN
97 
> script: <TT
98 
CLASS="LITERAL"
99 
>cdl_package</TT
100 
>, <TT
101 
CLASS="LITERAL"
102 
>cdl_component</TT
103 
>, <TT
104 
CLASS="LITERAL"
105 
>cdl_option</TT
106 
> and
107 
<TT
108 
CLASS="LITERAL"
109 
>cdl_interface</TT
110 
>. These correspond to the basic building blocks of the
111 
language (CDL interfaces are described in <A
112 
HREF="language.interface.html"
113 
>the Section called <I
114 
>Interfaces</I
115 
></A
116 
>). All of these take the same basic form:</P
117 
><TABLE
118 
BORDER="5"
119 
BGCOLOR="#E0E0F0"
120 
WIDTH="70%"
121 
><TR
122 
><TD
123 
><PRE
124 
CLASS="PROGRAMLISTING"
125 
>cdl_package &lt;name&gt; {
126 
    &#8230;
127 
}
128 
 
129 
cdl_component &lt;name&gt; {
130 
    &#8230;
131 
}
132 
 
133 
cdl_option &lt;name&gt; {
134 
    &#8230;
135 
}
136 
 
137 
cdl_interface &lt;name&gt; {
138 
    &#8230;
139 
}</PRE
140 
></TD
141 
></TR
142 
></TABLE
143 
><P
144 
>The command is followed by a name and by a body of properties, the
145 
latter enclosed in braces. Packages and components can contain other
146 
entities, so the <TT
147 
CLASS="LITERAL"
148 
>cdl_package</TT
149 
> and <TT
150 
CLASS="LITERAL"
151 
>cdl_component</TT
152 
> can also have
153 
nested commands in their bodies. All names must be unique within a
154 
given configuration. If say the C library package and a TCP/IP stack
155 
both defined an option with the same name then it would not be
156 
possible to load both of them into a single configuration. There is a
157 
<A
158 
HREF="language.naming.html"
159 
>naming convention</A
160 
> which should
161 
make accidental name clashes very unlikely.</P
162 
><P
163 
>It is possible for two packages to use the same name if there are no
164 
reasonable circumstances under which both packages could be loaded at
165 
the same time. One example would be architectural HAL packages: a
166 
given <SPAN
167 
CLASS="APPLICATION"
168 
>eCos</SPAN
169 
> configuration can be used on only one processor, so the
170 
architectural HAL packages <TT
171 
CLASS="VARNAME"
172 
>CYGPKG_HAL_ARM</TT
173 
> and
174 
<TT
175 
CLASS="VARNAME"
176 
>CYGPKG_HAL_I386</TT
177 
> can re-use option names; in fact
178 
in some cases they are expected to.</P
179 
><P
180 
>Each package has one top-level <SPAN
181 
CLASS="APPLICATION"
182 
>CDL</SPAN
183 
> script, which is specified in the
184 
packages <A
185 
HREF="language.database.html"
186 
><SPAN
187 
CLASS="DATABASE"
188 
>ecos.db</SPAN
189 
> database
190 
entry</A
191 
>. Typically the name of this top-level script is related to
192 
the package, so the kernel package uses
193 
<TT
194 
CLASS="FILENAME"
195 
>kernel.cdl</TT
196 
>, but this is just a convention. The
197 
first command in the top-level script should be <TT
198 
CLASS="LITERAL"
199 
>cdl_package</TT
200 
>, and the
201 
name used should be the same as in the <SPAN
202 
CLASS="DATABASE"
203 
>ecos.db</SPAN
204 
>
205 
database. There should be only one <TT
206 
CLASS="LITERAL"
207 
>cdl_package</TT
208 
> command per package.</P
209 
><P
210 
>The various <SPAN
211 
CLASS="APPLICATION"
212 
>CDL</SPAN
213 
> entities live in a hierarchy. For example the kernel
214 
package contains a scheduling component, a synchronization primitives
215 
component, and a number of others. The synchronization component
216 
contains various options such as whether or not mutex priority
217 
inheritance is enabled. There is no upper bound on how far components
218 
can be nested, but it is rarely necessary to go more than three or
219 
four levels deeper than the package level. Since the naming convention
220 
incorporates bits of the hierarchy, this has the added advantage of
221 
keeping the names down to a more manageable size.</P
222 
><P
223 
>The hierarchy serves two purposes. It allows options to be controlled
224 
en masse, so disabling a component automatically disables all the
225 
options below it in the hierarchy. It also permits a much simpler
226 
representation of the configuration in the graphical configuration
227 
tool, facilitating navigation and modification.</P
228 
><P
229 
>By default a package is placed at the top-level of the hierarchy, but
230 
it is possible to override this using a <SPAN
231 
CLASS="PROPERTY"
232 
>parent</SPAN
233 
> property. For example
234 
an architectural HAL package such as <TT
235 
CLASS="VARNAME"
236 
>CYGPKG_HAL_SH</TT
237 
>
238 
typically re-parents itself below <TT
239 
CLASS="VARNAME"
240 
>CYGPKG_HAL</TT
241 
>, and a
242 
platform HAL package would then re-parent itself below the
243 
architectural HAL. This makes it a little bit easier for users to
244 
navigate around the hierarchy. Components, options and interfaces can
245 
also be re-parented, but this is less common.</P
246 
><P
247 
>All components, options and interfaces that are defined directly in
248 
the top-level script will be placed below the package in the hierarchy.
249 
Alternatively they can be nested in the body of the <TT
250 
CLASS="LITERAL"
251 
>cdl_package</TT
252 
>
253 
command. The following two script fragments are equivalent:</P
254 
><TABLE
255 
BORDER="5"
256 
BGCOLOR="#E0E0F0"
257 
WIDTH="70%"
258 
><TR
259 
><TD
260 
><PRE
261 
CLASS="PROGRAMLISTING"
262 
>cdl_package CYGPKG_LIBC {
263 
    &#8230;
264 
}
265 
 
266 
cdl_component CYGPKG_LIBC_STRING {
267 
    &#8230;
268 
}
269 
 
270 
cdl_option CYGPKG_LIBC_CTYPE_INLINES {
271 
    &#8230;
272 
}</PRE
273 
></TD
274 
></TR
275 
></TABLE
276 
><P
277 
>and:</P
278 
><TABLE
279 
BORDER="5"
280 
BGCOLOR="#E0E0F0"
281 
WIDTH="70%"
282 
><TR
283 
><TD
284 
><PRE
285 
CLASS="PROGRAMLISTING"
286 
>cdl_package CYGPKG_LIBC {
287 
    &#8230;
288 
 
289 
    cdl_component CYGPKG_LIBC_STRING {
290 
        &#8230;
291 
    }
292 
 
293 
    cdl_option CYGPKG_LIBC_CTYPE_INLINES {
294 
        &#8230;
295 
    }
296 
}</PRE
297 
></TD
298 
></TR
299 
></TABLE
300 
><P
301 
>If a script defines options both inside and outside the body of the
302 
<TT
303 
CLASS="LITERAL"
304 
>cdl_package</TT
305 
> then the ones inside will be processed first. Language
306 
purists may argue that it would have been better if all contained
307 
options and components had to go into the body, but in practice it is
308 
often convenient to be able to skip this level of nesting and the
309 
resulting behavior is still well-defined.</P
310 
><P
311 
>Components can also contain options and other <SPAN
312 
CLASS="APPLICATION"
313 
>CDL</SPAN
314 
> entities, in fact
315 
that is what distinguishes them from options. These can be defined in
316 
the body of the <TT
317 
CLASS="LITERAL"
318 
>cdl_component</TT
319 
> command:</P
320 
><TABLE
321 
BORDER="5"
322 
BGCOLOR="#E0E0F0"
323 
WIDTH="70%"
324 
><TR
325 
><TD
326 
><PRE
327 
CLASS="PROGRAMLISTING"
328 
>cdl_component CYGPKG_LIBC_STDIO {
329 
 
330 
    cdl_component CYGPKG_LIBC_STDIO_FLOATING_POINT {
331 
        &#8230;
332 
    }
333 
 
334 
    cdl_option CYGSEM_LIBC_STDIO_THREAD_SAFE_STREAMS {
335 
        &#8230;
336 
    }
337 
}</PRE
338 
></TD
339 
></TR
340 
></TABLE
341 
><P
342 
>Nesting options inside the bodies of components like this is fine for
343 
simple packages with only a limited number of configuration options,
344 
but it becomes unsatisfactory as the number of options increases.
345 
Instead it is possible to split the <SPAN
346 
CLASS="APPLICATION"
347 
>CDL</SPAN
348 
> data into multiple <SPAN
349 
CLASS="APPLICATION"
350 
>CDL</SPAN
351 
>
352 
scripts, on a per-component basis. The <SPAN
353 
CLASS="PROPERTY"
354 
>script</SPAN
355 
> property should be
356 
used for this. For example, in the case of the C library all
357 
stdio-related configuration options could be put into
358 
<TT
359 
CLASS="FILENAME"
360 
>stdio.cdl</TT
361 
>, and the top-level CDL script
362 
<TT
363 
CLASS="FILENAME"
364 
>libc.cdl</TT
365 
> would contain the following:</P
366 
><TABLE
367 
BORDER="5"
368 
BGCOLOR="#E0E0F0"
369 
WIDTH="70%"
370 
><TR
371 
><TD
372 
><PRE
373 
CLASS="PROGRAMLISTING"
374 
>cdl_package CYGPKG_LIBC {
375 
    &#8230;
376 
 
377 
    cdl_component CYGPKG_LIBC_STDIO {
378 
        &#8230;
379 
        script stdio.cdl
380 
    }
381 
}</PRE
382 
></TD
383 
></TR
384 
></TABLE
385 
><P
386 
>The <TT
387 
CLASS="VARNAME"
388 
>CYGPKG_LIBC_STDIO_FLOATING_POINT</TT
389 
> component and
390 
the <TT
391 
CLASS="VARNAME"
392 
>CYGSEM_LIBC_STDIO_THREAD_SAFE_STREAMS</TT
393 
> option
394 
can then be placed at the top-level of <TT
395 
CLASS="FILENAME"
396 
>stdio.cdl</TT
397 
>.
398 
It is possible to have some options nested in the body of a
399 
<TT
400 
CLASS="LITERAL"
401 
>cdl_component</TT
402 
> command and other options in a separate file accessed
403 
by the <SPAN
404 
CLASS="PROPERTY"
405 
>script</SPAN
406 
> property. In such a case the nested options would be
407 
processed first, and then the other script would be read in. A script
408 
specified by a <SPAN
409 
CLASS="PROPERTY"
410 
>script</SPAN
411 
> property should only define new options,
412 
components or interfaces: it should not contain any additional
413 
properties for the current component.</P
414 
><P
415 
>It is possible for a component's <SPAN
416 
CLASS="APPLICATION"
417 
>CDL</SPAN
418 
> script to have a sub-component
419 
which also has a <SPAN
420 
CLASS="PROPERTY"
421 
>script</SPAN
422 
> property, and so on. In practice excessive
423 
nesting like this is rarely useful. It is also possible to ignore the
424 
<SPAN
425 
CLASS="APPLICATION"
426 
>CDL</SPAN
427 
> language support for constructing hierarchies automatically and
428 
use the <SPAN
429 
CLASS="PROPERTY"
430 
>parent</SPAN
431 
> property explicitly for every single option and
432 
component. Again this is not generally useful.</P
433 
><DIV
434 
CLASS="NOTE"
435 
><BLOCKQUOTE
436 
CLASS="NOTE"
437 
><P
438 
><B
439 
>Note: </B
440 
>At the time of writing interfaces cannot act as containers. This may
441 
change in a future version of the component framework. If the change
442 
is made then interfaces would support the <SPAN
443 
CLASS="PROPERTY"
444 
>script</SPAN
445 
> property, just like
446 
components.</P
447 
></BLOCKQUOTE
448 
></DIV
449 
></DIV
450 
><DIV
451 
CLASS="NAVFOOTER"
452 
><HR
453 
ALIGN="LEFT"
454 
WIDTH="100%"><TABLE
455 
SUMMARY="Footer navigation table"
456 
WIDTH="100%"
457 
BORDER="0"
458 
CELLPADDING="0"
459 
CELLSPACING="0"
460 
><TR
461 
><TD
462 
WIDTH="33%"
463 
ALIGN="left"
464 
VALIGN="top"
465 
><A
466 
HREF="language.html"
467 
ACCESSKEY="P"
468 
>Prev</A
469 
></TD
470 
><TD
471 
WIDTH="34%"
472 
ALIGN="center"
473 
VALIGN="top"
474 
><A
475 
HREF="cdl-guide.html"
476 
ACCESSKEY="H"
477 
>Home</A
478 
></TD
479 
><TD
480 
WIDTH="33%"
481 
ALIGN="right"
482 
VALIGN="top"
483 
><A
484 
HREF="language.properties.html"
485 
ACCESSKEY="N"
486 
>Next</A
487 
></TD
488 
></TR
489 
><TR
490 
><TD
491 
WIDTH="33%"
492 
ALIGN="left"
493 
VALIGN="top"
494 
>The CDL Language</TD
495 
><TD
496 
WIDTH="34%"
497 
ALIGN="center"
498 
VALIGN="top"
499 
><A
500 
HREF="language.html"
501 
ACCESSKEY="U"
502 
>Up</A
503 
></TD
504 
><TD
505 
WIDTH="33%"
506 
ALIGN="right"
507 
VALIGN="top"
508 
>CDL Properties</TD
509 
></TR
510 
></TABLE
511 
></DIV
512 
></BODY
513 
></HTML
514 
>

powered by: WebSVN 2.1.0

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