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

Subversion Repositories openrisc

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

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
>The CDL Language</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="PREVIOUS"
22
TITLE="Making a Package Distribution"
23
HREF="package.distrib.html"><LINK
24
REL="NEXT"
25
TITLE="CDL Commands"
26
HREF="language.commands.html"></HEAD
27
><BODY
28
CLASS="CHAPTER"
29
BGCOLOR="#FFFFFF"
30
TEXT="#000000"
31
LINK="#0000FF"
32
VLINK="#840084"
33
ALINK="#0000FF"
34
><DIV
35
CLASS="NAVHEADER"
36
><TABLE
37
SUMMARY="Header navigation table"
38
WIDTH="100%"
39
BORDER="0"
40
CELLPADDING="0"
41
CELLSPACING="0"
42
><TR
43
><TH
44
COLSPAN="3"
45
ALIGN="center"
46
>The <SPAN
47
CLASS="APPLICATION"
48
>eCos</SPAN
49
> Component Writer's Guide</TH
50
></TR
51
><TR
52
><TD
53
WIDTH="10%"
54
ALIGN="left"
55
VALIGN="bottom"
56
><A
57
HREF="package.distrib.html"
58
ACCESSKEY="P"
59
>Prev</A
60
></TD
61
><TD
62
WIDTH="80%"
63
ALIGN="center"
64
VALIGN="bottom"
65
></TD
66
><TD
67
WIDTH="10%"
68
ALIGN="right"
69
VALIGN="bottom"
70
><A
71
HREF="language.commands.html"
72
ACCESSKEY="N"
73
>Next</A
74
></TD
75
></TR
76
></TABLE
77
><HR
78
ALIGN="LEFT"
79
WIDTH="100%"></DIV
80
><DIV
81
CLASS="CHAPTER"
82
><H1
83
><A
84
NAME="LANGUAGE">Chapter 3. The CDL Language</H1
85
><DIV
86
CLASS="TOC"
87
><DL
88
><DT
89
><B
90
>Table of Contents</B
91
></DT
92
><DT
93
><A
94
HREF="language.html#LANGUAGE.OVERVIEW"
95
>Language Overview</A
96
></DT
97
><DT
98
><A
99
HREF="language.commands.html"
100
>CDL Commands</A
101
></DT
102
><DT
103
><A
104
HREF="language.properties.html"
105
>CDL Properties</A
106
></DT
107
><DT
108
><A
109
HREF="language.naming.html"
110
>Option Naming Convention</A
111
></DT
112
><DT
113
><A
114
HREF="language.tcl.html"
115
>An Introduction to Tcl</A
116
></DT
117
><DT
118
><A
119
HREF="language.values.html"
120
>Values and Expressions</A
121
></DT
122
><DT
123
><A
124
HREF="language.interface.html"
125
>Interfaces</A
126
></DT
127
><DT
128
><A
129
HREF="language.database.html"
130
>Updating the <SPAN
131
CLASS="DATABASE"
132
>ecos.db</SPAN
133
> database</A
134
></DT
135
></DL
136
></DIV
137
><P
138
>The <SPAN
139
CLASS="APPLICATION"
140
>CDL</SPAN
141
> language is a key part of the <SPAN
142
CLASS="APPLICATION"
143
>eCos</SPAN
144
> component framework.
145
All packages must come with at least one <SPAN
146
CLASS="APPLICATION"
147
>CDL</SPAN
148
> script, to describe
149
that package to the framework. The information in that script includes
150
details of all the configuration options and how to build the package.
151
Implementing a new component or turning some existing code into an
152
<SPAN
153
CLASS="APPLICATION"
154
>eCos</SPAN
155
> component always involves writing corresponding <SPAN
156
CLASS="APPLICATION"
157
>CDL</SPAN
158
>. This
159
chapter provides a description of the <SPAN
160
CLASS="APPLICATION"
161
>CDL</SPAN
162
> language. Detailed
163
information on specific parts of the language can be found in <A
164
HREF="reference.html"
165
>Chapter 5</A
166
>.</P
167
><DIV
168
CLASS="SECT1"
169
><H1
170
CLASS="SECT1"
171
><A
172
NAME="LANGUAGE.OVERVIEW">Language Overview</H1
173
><P
174
>A very simple <SPAN
175
CLASS="APPLICATION"
176
>CDL</SPAN
177
> script would look like this:</P
178
><TABLE
179
BORDER="5"
180
BGCOLOR="#E0E0F0"
181
WIDTH="70%"
182
><TR
183
><TD
184
><PRE
185
CLASS="PROGRAMLISTING"
186
>cdl_package CYGPKG_ERROR {
187
    display       "Common error code support"
188
    compile       strerror.cxx
189
    include_dir   cyg/error
190
    description   "
191
        This package contains the common list of error and
192
        status codes. It is held centrally to allow
193
        packages to interchange error codes and status
194
        codes in a common way, rather than each package
195
        having its own conventions for error/status
196
        reporting. The error codes are modelled on the
197
        POSIX style naming e.g. EINVAL etc. This package
198
        also provides the standard strerror() function to
199
        convert error codes to textual representation."
200
}</PRE
201
></TD
202
></TR
203
></TABLE
204
><P
205
>This describes a single package, the error code package, which does
206
not have any sub-components or configuration options. The package has
207
an internal name, <TT
208
CLASS="VARNAME"
209
>CYGPKG_ERROR</TT
210
>, which can be
211
referenced in other <SPAN
212
CLASS="APPLICATION"
213
>CDL</SPAN
214
> scripts using e.g.
215
<TT
216
CLASS="LITERAL"
217
>requires&nbsp;CYGPKG_ERROR</TT
218
>. There will also be a
219
<TT
220
CLASS="LITERAL"
221
>#define</TT
222
> for this symbol in a configuration header
223
file. In addition to the package name, this script provides a number
224
of properties for the package as a whole. The <SPAN
225
CLASS="PROPERTY"
226
>display</SPAN
227
> property
228
provides a short description. The <SPAN
229
CLASS="PROPERTY"
230
>description</SPAN
231
> property involves a
232
rather longer one, for when users need a bit more information. The
233
<SPAN
234
CLASS="PROPERTY"
235
>compile</SPAN
236
> and <SPAN
237
CLASS="PROPERTY"
238
>include_dir</SPAN
239
> properties list the consequences of this
240
package at build-time. The package appears to lack any on-line
241
documentation. </P
242
><P
243
>Packages could be even simpler than this. If the package only provides
244
an interface and there are no files to be compiled then there is no
245
need for a <SPAN
246
CLASS="PROPERTY"
247
>compile</SPAN
248
> property. Alternatively if there are no exported
249
header files, or if the exported header files should go to the
250
top-level of the <TT
251
CLASS="FILENAME"
252
>install/include</TT
253
> directory, then there is
254
no need for an <SPAN
255
CLASS="PROPERTY"
256
>include_dir</SPAN
257
> property. Strictly speaking the
258
<SPAN
259
CLASS="PROPERTY"
260
>description</SPAN
261
> and <SPAN
262
CLASS="PROPERTY"
263
>display</SPAN
264
> properties are optional as well, although
265
application developers would not appreciate the resulting lack of
266
information about what the package is supposed to do.</P
267
><P
268
>However many packages tend to be a bit more complicated than the error
269
package, containing various sub-components and configuration options.
270
These are also defined in the <SPAN
271
CLASS="APPLICATION"
272
>CDL</SPAN
273
> scripts and in much the same way
274
as the package. For example, the following excerpt comes from the
275
infrastructure package:</P
276
><TABLE
277
BORDER="5"
278
BGCOLOR="#E0E0F0"
279
WIDTH="70%"
280
><TR
281
><TD
282
><PRE
283
CLASS="PROGRAMLISTING"
284
>cdl_component CYGDBG_INFRA_DEBUG_TRACE_ASSERT_BUFFER {
285
    display       "Buffered tracing"
286
    default_value 1
287
    active_if     CYGDBG_USE_TRACING
288
    description   "
289
        An output module which buffers output from tracing and
290
        assertion events. The stored messages are output when an
291
        assert fires, or CYG_TRACE_PRINT() (defined in
292
        &lt;cyg/infra/cyg_trac.h&gt;) is called. Of course, there will
293
        only be stored messages if tracing per se (CYGDBG_USE_TRACING)
294
        is enabled above."
295
 
296
    cdl_option CYGDBG_INFRA_DEBUG_TRACE_BUFFER_SIZE {
297
        display       "Trace buffer size"
298
        flavor        data
299
        default_value 32
300
        legal_values  5 to 65535
301
        description   "
302
            The size of the trace buffer. This counts the number of
303
            trace records stored. When the buffer fills it either
304
            wraps, stops recording, or generates output."
305
    }
306
 
307
    &#8230;
308
}</PRE
309
></TD
310
></TR
311
></TABLE
312
><P
313
>Like a <TT
314
CLASS="LITERAL"
315
>cdl_package</TT
316
>, a <TT
317
CLASS="LITERAL"
318
>cdl_component</TT
319
> has a name and a body. The
320
body contains various properties for that component, and may also
321
contain sub-components or options. Similarly a <TT
322
CLASS="LITERAL"
323
>cdl_option</TT
324
> has a
325
name and a body of properties. This example lists a number of
326
new properties: <SPAN
327
CLASS="PROPERTY"
328
>default_value</SPAN
329
>, <SPAN
330
CLASS="PROPERTY"
331
>active_if</SPAN
332
>, <SPAN
333
CLASS="PROPERTY"
334
>flavor</SPAN
335
> and
336
<SPAN
337
CLASS="PROPERTY"
338
>legal_values</SPAN
339
>. The meaning of most of these should be fairly obvious.
340
The next sections describe the various <SPAN
341
CLASS="APPLICATION"
342
>CDL</SPAN
343
> commands and properties. </P
344
><P
345
>There is one additional and very important point: <SPAN
346
CLASS="APPLICATION"
347
>CDL</SPAN
348
> is not a
349
completely new language; instead it is implemented as an extension of
350
the existing <SPAN
351
CLASS="APPLICATION"
352
>Tcl</SPAN
353
> scripting language. The syntax of a <SPAN
354
CLASS="APPLICATION"
355
>CDL</SPAN
356
> script is
357
<SPAN
358
CLASS="APPLICATION"
359
>Tcl</SPAN
360
> syntax, which is described below. In addition some of the more
361
advanced facilities of <SPAN
362
CLASS="APPLICATION"
363
>CDL</SPAN
364
> involve embedded fragments of <SPAN
365
CLASS="APPLICATION"
366
>Tcl</SPAN
367
> code,
368
for example there is a <SPAN
369
CLASS="PROPERTY"
370
>define_proc</SPAN
371
> property which specifies some
372
code that needs to be executed when the component framework generates
373
the configuration header files.</P
374
></DIV
375
></DIV
376
><DIV
377
CLASS="NAVFOOTER"
378
><HR
379
ALIGN="LEFT"
380
WIDTH="100%"><TABLE
381
SUMMARY="Footer navigation table"
382
WIDTH="100%"
383
BORDER="0"
384
CELLPADDING="0"
385
CELLSPACING="0"
386
><TR
387
><TD
388
WIDTH="33%"
389
ALIGN="left"
390
VALIGN="top"
391
><A
392
HREF="package.distrib.html"
393
ACCESSKEY="P"
394
>Prev</A
395
></TD
396
><TD
397
WIDTH="34%"
398
ALIGN="center"
399
VALIGN="top"
400
><A
401
HREF="cdl-guide.html"
402
ACCESSKEY="H"
403
>Home</A
404
></TD
405
><TD
406
WIDTH="33%"
407
ALIGN="right"
408
VALIGN="top"
409
><A
410
HREF="language.commands.html"
411
ACCESSKEY="N"
412
>Next</A
413
></TD
414
></TR
415
><TR
416
><TD
417
WIDTH="33%"
418
ALIGN="left"
419
VALIGN="top"
420
>Making a Package Distribution</TD
421
><TD
422
WIDTH="34%"
423
ALIGN="center"
424
VALIGN="top"
425
>&nbsp;</TD
426
><TD
427
WIDTH="33%"
428
ALIGN="right"
429
VALIGN="top"
430
>CDL Commands</TD
431
></TR
432
></TABLE
433
></DIV
434
></BODY
435
></HTML
436
>

powered by: WebSVN 2.1.0

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