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

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [cdl-guide/] [build.headers.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 
>Configuration Header File Generation</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 Build Process"
23 
HREF="build.html"><LINK
24 
REL="PREVIOUS"
25 
TITLE="The Build Process"
26 
HREF="build.html"><LINK
27 
REL="NEXT"
28 
TITLE="Building eCos"
29 
HREF="build.make.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="build.html"
61 
ACCESSKEY="P"
62 
>Prev</A
63 
></TD
64 
><TD
65 
WIDTH="80%"
66 
ALIGN="center"
67 
VALIGN="bottom"
68 
>Chapter 4. The Build Process</TD
69 
><TD
70 
WIDTH="10%"
71 
ALIGN="right"
72 
VALIGN="bottom"
73 
><A
74 
HREF="build.make.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="BUILD.HEADERS">Configuration Header File Generation</H1
89 
><P
90 
>Configuration options can affect a build in two main ways. First,
91 
enabling a configuration option or other <SPAN
92 
CLASS="APPLICATION"
93 
>CDL</SPAN
94 
> entity can result in
95 
various files being built and added to a library, thus providing
96 
functionality to the application code. However this mechanism can only
97 
operate at a rather coarse grain, at the level of entire source files.
98 
Hence the component framework also generates configuration header
99 
files containing mainly C preprocessor <TT
100 
CLASS="LITERAL"
101 
>#define</TT
102 
>
103 
directives. Package source code can then <TT
104 
CLASS="LITERAL"
105 
>#include</TT
106 
>
107 
the appropriate header files and use <TT
108 
CLASS="LITERAL"
109 
>#if</TT
110 
>,
111 
<TT
112 
CLASS="LITERAL"
113 
>#ifdef</TT
114 
> and <TT
115 
CLASS="LITERAL"
116 
>#ifndef</TT
117 
> directives to
118 
adapt accordingly. In this way configuration options can be used to
119 
enable or disable entire functions within a source file or just a
120 
single line, whichever is appropriate.</P
121 
><P
122 
>The configuration header files end up in the <TT
123 
CLASS="FILENAME"
124 
>include/pkgconf</TT
125 
> subdirectory of the
126 
install tree. There will be one header file for the system as a whole,
127 
<TT
128 
CLASS="FILENAME"
129 
>pkgconf/system.h</TT
130 
>, and there will
131 
be additional header files for each package, for example
132 
<TT
133 
CLASS="FILENAME"
134 
>pkgconf/kernel.h</TT
135 
>. The header files
136 
are generated when creating or updating the build and install trees,
137 
which needs to happen after every change to the configuration.</P
138 
><P
139 
>The component framework processes each package in the configuration
140 
one at a time. The exact order in which the packages are processed is
141 
not defined, so the order in which <TT
142 
CLASS="LITERAL"
143 
>#define's</TT
144 
> will
145 
end up in the global <TT
146 
CLASS="FILENAME"
147 
>pkgconf/system.h</TT
148 
> header may vary. However
149 
for any given configuration the order should remain consistent until
150 
packages are added to or removed from the system. This avoids
151 
unnecessary changes to the global header file and hence unnecessary
152 
rebuilds of the packages and of application code because of header
153 
file dependency handling.</P
154 
><P
155 
>Within a given package the various components, options and interfaces
156 
will be processed in the order in which they were defined in the
157 
corresponding <SPAN
158 
CLASS="APPLICATION"
159 
>CDL</SPAN
160 
> scripts. Typically the data in the configuration
161 
headers consists only of a sequence of <TT
162 
CLASS="LITERAL"
163 
>#define's</TT
164 
> so
165 
the order in which these are generated is irrelevant, but some
166 
properties such as <SPAN
167 
CLASS="PROPERTY"
168 
>define_proc</SPAN
169 
> can be used to add arbitrary data to
170 
a configuration header and hence there may be dependencies on the
171 
order. It should be noted that re-parenting an option below some other
172 
package has no effect on which header file will contain the
173 
corresponding <TT
174 
CLASS="LITERAL"
175 
>#define</TT
176 
>: the preprocessor directives
177 
will always end up in the header file for the package that defines the
178 
option, or in the global configuration header.</P
179 
><P
180 
>There are six properties which affect the process of generating header
181 
files:
182 
<A
183 
HREF="ref.define-header.html"
184 
><SPAN
185 
CLASS="PROPERTY"
186 
>define_header</SPAN
187 
></A
188 
>,
189 
<A
190 
HREF="ref.no-define.html"
191 
><SPAN
192 
CLASS="PROPERTY"
193 
>no_define</SPAN
194 
></A
195 
>,
196 
<A
197 
HREF="ref.define-format.html"
198 
><SPAN
199 
CLASS="PROPERTY"
200 
>define_format</SPAN
201 
></A
202 
>,
203 
<A
204 
HREF="ref.define.html"
205 
><SPAN
206 
CLASS="PROPERTY"
207 
>define</SPAN
208 
></A
209 
>,
210 
<A
211 
HREF="ref.if-define.html"
212 
><SPAN
213 
CLASS="PROPERTY"
214 
>if_define</SPAN
215 
></A
216 
>, and
217 
<A
218 
HREF="ref.define-proc.html"
219 
><SPAN
220 
CLASS="PROPERTY"
221 
>define_proc</SPAN
222 
></A
223 
>.</P
224 
><P
225 
>The <SPAN
226 
CLASS="PROPERTY"
227 
>define_header</SPAN
228 
> property can only occur in the body of a
229 
<TT
230 
CLASS="LITERAL"
231 
>cdl_package</TT
232 
> command and specifies the name of the header file which
233 
should contain the package's configuration data, for example:</P
234 
><TABLE
235 
BORDER="5"
236 
BGCOLOR="#E0E0F0"
237 
WIDTH="70%"
238 
><TR
239 
><TD
240 
><PRE
241 
CLASS="PROGRAMLISTING"
242 
>cdl_package &lt;some_package&gt; {
243 
    &#8230;
244 
    define_header xyzzy.h
245 
}</PRE
246 
></TD
247 
></TR
248 
></TABLE
249 
><P
250 
>Given such a <SPAN
251 
CLASS="PROPERTY"
252 
>define_header</SPAN
253 
> property the component framework will
254 
use the file <TT
255 
CLASS="FILENAME"
256 
>pkgconf/xyzzy.h</TT
257 
> for
258 
the package's configuration data. If a package does not have
259 
a <SPAN
260 
CLASS="PROPERTY"
261 
>define_header</SPAN
262 
> property then a suitable file name is constructed
263 
from the package's name. This involves:</P
264 
><P
265 
></P
266 
><OL
267 
TYPE="1"
268 
><LI
269 
><P
270 
>All characters in the package name up to and including the first
271 
underscore are removed. For example <TT
272 
CLASS="VARNAME"
273 
>CYGPKG_KERNEL</TT
274 
>
275 
is converted to <TT
276 
CLASS="LITERAL"
277 
>KERNEL</TT
278 
>, and
279 
<TT
280 
CLASS="VARNAME"
281 
>CYGPKG_HAL_ARM</TT
282 
> is converted to
283 
<TT
284 
CLASS="LITERAL"
285 
>HAL_ARM</TT
286 
>.</P
287 
></LI
288 
><LI
289 
><P
290 
>Any upper case letters in the resulting string will be converted to
291 
lower case, yielding e.g. <TT
292 
CLASS="LITERAL"
293 
>kernel</TT
294 
> and
295 
<TT
296 
CLASS="LITERAL"
297 
>hal_arm</TT
298 
>.</P
299 
></LI
300 
><LI
301 
><P
302 
>A <TT
303 
CLASS="LITERAL"
304 
>.h</TT
305 
> suffix is appended, yielding e.g.
306 
<TT
307 
CLASS="LITERAL"
308 
>kernel.h</TT
309 
> and <TT
310 
CLASS="LITERAL"
311 
>hal_arm.h</TT
312 
>.</P
313 
></LI
314 
></OL
315 
><P
316 
>Because of the naming restrictions on configuration options, this
317 
should result in a valid filename. There is a small possibility of a
318 
file name class, for example <TT
319 
CLASS="VARNAME"
320 
>CYGPKG_PLUGH</TT
321 
> and
322 
<TT
323 
CLASS="VARNAME"
324 
>CYGPKG_plugh</TT
325 
> would both end up trying to use the
326 
same header file <TT
327 
CLASS="FILENAME"
328 
>pkgconf/plugh.h</TT
329 
>,
330 
but the use of lower case letters for package names violates the
331 
naming conventions. It is not legal to use the <SPAN
332 
CLASS="PROPERTY"
333 
>define_header</SPAN
334 
>
335 
property to put the configuration data for several packages in a
336 
single header file. The resulting behaviour is undefined.</P
337 
><P
338 
>Once the name of the package's header file has been determined and the
339 
file has been opened, the various components, options and interfaces
340 
in the package will be processed starting with the package itself. The
341 
following steps are involved:</P
342 
><P
343 
></P
344 
><OL
345 
TYPE="1"
346 
><LI
347 
><P
348 
>If the current option or other <SPAN
349 
CLASS="APPLICATION"
350 
>CDL</SPAN
351 
> entity is inactive or disabled,
352 
the option is ignored for the purposes of header file generation.
353 
<TT
354 
CLASS="LITERAL"
355 
>#define's</TT
356 
> are only generated for options that are
357 
both active and enabled.</P
358 
></LI
359 
><LI
360 
><P
361 
>The next step is to generate a default <TT
362 
CLASS="LITERAL"
363 
>#define</TT
364 
> for
365 
the current option. If this option has a <SPAN
366 
CLASS="PROPERTY"
367 
>no_define</SPAN
368 
> property then the
369 
default <TT
370 
CLASS="LITERAL"
371 
>#define</TT
372 
> is suppressed, and processing
373 
continues for <SPAN
374 
CLASS="PROPERTY"
375 
>define</SPAN
376 
>, <SPAN
377 
CLASS="PROPERTY"
378 
>if_define</SPAN
379 
> and <SPAN
380 
CLASS="PROPERTY"
381 
>define_proc</SPAN
382 
> properties.</P
383 
><P
384 
></P
385 
><OL
386 
TYPE="a"
387 
><LI
388 
><P
389 
>The header file appropriate for the default <TT
390 
CLASS="LITERAL"
391 
>#define</TT
392 
>
393 
is determined. For a <TT
394 
CLASS="LITERAL"
395 
>cdl_package</TT
396 
> this will be <TT
397 
CLASS="FILENAME"
398 
>pkgconf/system.h</TT
399 
>, for any other option this
400 
will be the package's own header file. The intention here is that
401 
packages and application code can always determine which packages are
402 
in the configuration by <TT
403 
CLASS="LITERAL"
404 
>#include'ing</TT
405 
> <TT
406 
CLASS="FILENAME"
407 
>pkgconf/system.h</TT
408 
>. The C preprocessor lacks
409 
any facilities for including a header file only if it exists, and
410 
taking appropriate action otherwise.</P
411 
></LI
412 
><LI
413 
><P
414 
>For options with the flavors <TT
415 
CLASS="LITERAL"
416 
>bool</TT
417 
> or
418 
<TT
419 
CLASS="LITERAL"
420 
>none</TT
421 
>, a single <TT
422 
CLASS="LITERAL"
423 
>#define</TT
424 
> will be
425 
generated. This takes the form:</P
426 
><TABLE
427 
BORDER="5"
428 
BGCOLOR="#E0E0F0"
429 
WIDTH="70%"
430 
><TR
431 
><TD
432 
><PRE
433 
CLASS="PROGRAMLISTING"
434 
>#define &lt;option&gt; 1</PRE
435 
></TD
436 
></TR
437 
></TABLE
438 
><P
439 
>For example:</P
440 
><TABLE
441 
BORDER="5"
442 
BGCOLOR="#E0E0F0"
443 
WIDTH="70%"
444 
><TR
445 
><TD
446 
><PRE
447 
CLASS="PROGRAMLISTING"
448 
>#define CYGFUN_LIBC_TIME_POSIX 1</PRE
449 
></TD
450 
></TR
451 
></TABLE
452 
><P
453 
>Package source code can check whether or not an option is active and
454 
enabled by using the <TT
455 
CLASS="LITERAL"
456 
>#ifdef</TT
457 
>,
458 
<TT
459 
CLASS="LITERAL"
460 
>#ifndef</TT
461 
> or <TT
462 
CLASS="LITERAL"
463 
>#if
464 
defined(&#8230;)</TT
465 
>directives.</P
466 
></LI
467 
><LI
468 
><P
469 
>For options with the flavors <TT
470 
CLASS="LITERAL"
471 
>data</TT
472 
> or
473 
<TT
474 
CLASS="LITERAL"
475 
>booldata</TT
476 
>, either one or two
477 
<TT
478 
CLASS="LITERAL"
479 
>#define's</TT
480 
> will be generated. The first of these may
481 
be affected by a <SPAN
482 
CLASS="PROPERTY"
483 
>define_format</SPAN
484 
> property. If this property is not
485 
defined then the first <TT
486 
CLASS="LITERAL"
487 
>#define</TT
488 
> will take the form:</P
489 
><TABLE
490 
BORDER="5"
491 
BGCOLOR="#E0E0F0"
492 
WIDTH="70%"
493 
><TR
494 
><TD
495 
><PRE
496 
CLASS="PROGRAMLISTING"
497 
>#define &lt;option&gt; &lt;value&gt;</PRE
498 
></TD
499 
></TR
500 
></TABLE
501 
><P
502 
>For example:</P
503 
><TABLE
504 
BORDER="5"
505 
BGCOLOR="#E0E0F0"
506 
WIDTH="70%"
507 
><TR
508 
><TD
509 
><PRE
510 
CLASS="PROGRAMLISTING"
511 
>#define CYGNUM_LIBC_ATEXIT_HANDLERS 32</PRE
512 
></TD
513 
></TR
514 
></TABLE
515 
><P
516 
>Package source code can examine this value using the
517 
<TT
518 
CLASS="LITERAL"
519 
>#if</TT
520 
> directive, or by using the symbol in
521 
code such as:</P
522 
><TABLE
523 
BORDER="5"
524 
BGCOLOR="#E0E0F0"
525 
WIDTH="70%"
526 
><TR
527 
><TD
528 
><PRE
529 
CLASS="PROGRAMLISTING"
530 
>    for (i = 0; i &#60; CYGNUM_LIBC_ATEXIT_HANDLERS; i++) {
531 
        &#8230;
532 
    }</PRE
533 
></TD
534 
></TR
535 
></TABLE
536 
><P
537 
>It must be noted that the <TT
538 
CLASS="LITERAL"
539 
>#define</TT
540 
> will be generated
541 
only if the corresponding option is both active and enabled. Options
542 
with the <TT
543 
CLASS="LITERAL"
544 
>data</TT
545 
> flavor are always enabled but may not
546 
be active. Code like the above should be written only if it is known
547 
that the symbol will always be defined, for example if the
548 
corresponding source file will only get built if the containing
549 
component is active and enabled. Otherwise the use of additional
550 
<TT
551 
CLASS="LITERAL"
552 
>#ifdef</TT
553 
> or similar directives will be necessary.</P
554 
></LI
555 
><LI
556 
><P
557 
>If there is a <SPAN
558 
CLASS="PROPERTY"
559 
>define_format</SPAN
560 
> property then this controls how the
561 
option's value will appear in the header file. Given a format string
562 
such as <TT
563 
CLASS="LITERAL"
564 
>%08x</TT
565 
> and a value 42, the component
566 
framework will execute the <SPAN
567 
CLASS="APPLICATION"
568 
>Tcl</SPAN
569 
> command
570 
<TT
571 
CLASS="LITERAL"
572 
>format&nbsp;%08x&nbsp;42</TT
573 
> and the result will be
574 
used for the <TT
575 
CLASS="LITERAL"
576 
>#define's</TT
577 
> value. It is the
578 
responsibility of the component writer to make sure that this <SPAN
579 
CLASS="APPLICATION"
580 
>Tcl</SPAN
581 
>
582 
command will be valid given the format string and the legal values for
583 
the option.</P
584 
></LI
585 
><LI
586 
><P
587 
>In addition a second <TT
588 
CLASS="LITERAL"
589 
>#define</TT
590 
> may or may not be
591 
generated. This will take the form:</P
592 
><TABLE
593 
BORDER="5"
594 
BGCOLOR="#E0E0F0"
595 
WIDTH="70%"
596 
><TR
597 
><TD
598 
><PRE
599 
CLASS="PROGRAMLISTING"
600 
>#define &lt;option&gt;_&lt;value&gt;</PRE
601 
></TD
602 
></TR
603 
></TABLE
604 
><P
605 
>For example:</P
606 
><TABLE
607 
BORDER="5"
608 
BGCOLOR="#E0E0F0"
609 
WIDTH="70%"
610 
><TR
611 
><TD
612 
><PRE
613 
CLASS="PROGRAMLISTING"
614 
>#define CYGNUM_LIBC_ATEXIT_HANDLERS_32</PRE
615 
></TD
616 
></TR
617 
></TABLE
618 
><P
619 
>The <TT
620 
CLASS="LITERAL"
621 
>#define</TT
622 
> will be generated only if it would
623 
result in a valid C preprocessor symbol. If the value is a string such
624 
as <TT
625 
CLASS="LITERAL"
626 
>"/dev/ser0"</TT
627 
> then the <TT
628 
CLASS="LITERAL"
629 
>#define</TT
630 
>
631 
would be suppressed. This second <TT
632 
CLASS="LITERAL"
633 
>#define</TT
634 
> is not
635 
particularly useful for numerical data, but can be valuable in other
636 
circumstances. For example if the legal values for an option
637 
<TT
638 
CLASS="LITERAL"
639 
>XXX_COLOR</TT
640 
> are <TT
641 
CLASS="LITERAL"
642 
>red</TT
643 
>,
644 
<TT
645 
CLASS="LITERAL"
646 
>green</TT
647 
> and <TT
648 
CLASS="LITERAL"
649 
>blue</TT
650 
> then code like
651 
the following can be used:</P
652 
><TABLE
653 
BORDER="5"
654 
BGCOLOR="#E0E0F0"
655 
WIDTH="70%"
656 
><TR
657 
><TD
658 
><PRE
659 
CLASS="PROGRAMLISTING"
660 
>#ifdef XXX_COLOR_red
661 
    &#8230;
662 
#endif
663 
#ifdef XXX_COLOR_green
664 
    &#8230;
665 
#endif
666 
#ifdef XXX_COLOR_blue
667 
    &#8230;
668 
#endif</PRE
669 
></TD
670 
></TR
671 
></TABLE
672 
><P
673 
>The expression syntax provided by the C preprocessor is limited to
674 
numerical data and cannot perform string comparisons. By generating
675 
two <TT
676 
CLASS="LITERAL"
677 
>#define's</TT
678 
> in this way it is possible to work
679 
around this limitation of the C preprocessor. However some care has to
680 
be taken: if a component writer also defined a configuration option
681 
<TT
682 
CLASS="LITERAL"
683 
>XXX_COLOR_green</TT
684 
> then there will be confusion. Since
685 
such a configuration option violates the naming conventions, the
686 
problem is unlikely to arise in practice.</P
687 
></LI
688 
></OL
689 
></LI
690 
><LI
691 
><P
692 
>For some options it may be useful to generate one or more additional
693 
<TT
694 
CLASS="LITERAL"
695 
>#define's</TT
696 
> or, in conjunction with the <SPAN
697 
CLASS="PROPERTY"
698 
>no_define</SPAN
699 
>
700 
property, to define a symbol with a name different from the option's
701 
name. This can be achieved with the <SPAN
702 
CLASS="PROPERTY"
703 
>define</SPAN
704 
> property, which takes the
705 
following form:</P
706 
><TABLE
707 
BORDER="5"
708 
BGCOLOR="#E0E0F0"
709 
WIDTH="70%"
710 
><TR
711 
><TD
712 
><PRE
713 
CLASS="PROGRAMLISTING"
714 
>    define [-file=&lt;filename&gt;] [-format=&lt;format&gt;] &lt;symbol&gt;</PRE
715 
></TD
716 
></TR
717 
></TABLE
718 
><P
719 
>For example:</P
720 
><TABLE
721 
BORDER="5"
722 
BGCOLOR="#E0E0F0"
723 
WIDTH="70%"
724 
><TR
725 
><TD
726 
><PRE
727 
CLASS="PROGRAMLISTING"
728 
>    define FOPEN_MAX</PRE
729 
></TD
730 
></TR
731 
></TABLE
732 
><P
733 
>This will result in something like:</P
734 
><TABLE
735 
BORDER="5"
736 
BGCOLOR="#E0E0F0"
737 
WIDTH="70%"
738 
><TR
739 
><TD
740 
><PRE
741 
CLASS="PROGRAMLISTING"
742 
>#define FOPEN_MAX 8
743 
#define FOPEN_MAX_8</PRE
744 
></TD
745 
></TR
746 
></TABLE
747 
><P
748 
>The specified symbol must be a valid C preprocessor symbol. Normally
749 
the <TT
750 
CLASS="LITERAL"
751 
>#define</TT
752 
> will end up in the same header file as
753 
the default one, in other words <TT
754 
CLASS="FILENAME"
755 
>pkgconf/system.h</TT
756 
> in the case of a
757 
<TT
758 
CLASS="LITERAL"
759 
>cdl_package</TT
760 
>, or the package's own header file for any other option.
761 
The <TT
762 
CLASS="LITERAL"
763 
>-file</TT
764 
> option can be used to change this. At
765 
present the only legal value is <TT
766 
CLASS="LITERAL"
767 
>system.h</TT
768 
>, for
769 
example:</P
770 
><TABLE
771 
BORDER="5"
772 
BGCOLOR="#E0E0F0"
773 
WIDTH="70%"
774 
><TR
775 
><TD
776 
><PRE
777 
CLASS="PROGRAMLISTING"
778 
>    define -file=system.h &lt;symbol&gt;</PRE
779 
></TD
780 
></TR
781 
></TABLE
782 
><P
783 
>This will cause the <TT
784 
CLASS="LITERAL"
785 
>#define</TT
786 
> to end up in the global
787 
configuration header rather than in the package's own header. Use of
788 
this facility should be avoided since it is very rarely necessary to
789 
make options globally visible.</P
790 
><P
791 
>The <SPAN
792 
CLASS="PROPERTY"
793 
>define</SPAN
794 
> property takes another option,
795 
<TT
796 
CLASS="LITERAL"
797 
>-format</TT
798 
>, to provide a format string.</P
799 
><TABLE
800 
BORDER="5"
801 
BGCOLOR="#E0E0F0"
802 
WIDTH="70%"
803 
><TR
804 
><TD
805 
><PRE
806 
CLASS="PROGRAMLISTING"
807 
>    define -format=%08x &lt;symbol&gt;</PRE
808 
></TD
809 
></TR
810 
></TABLE
811 
><P
812 
>This should only be used for options with the <TT
813 
CLASS="LITERAL"
814 
>data</TT
815 
>
816 
or <TT
817 
CLASS="LITERAL"
818 
>booldata</TT
819 
> flavor, and has the same effect as the
820 
<SPAN
821 
CLASS="PROPERTY"
822 
>define_format</SPAN
823 
> property has on the default
824 
<TT
825 
CLASS="LITERAL"
826 
>#define</TT
827 
>.</P
828 
><P
829 
><SPAN
830 
CLASS="PROPERTY"
831 
>define</SPAN
832 
> properties are processed in the same way the default
833 
<TT
834 
CLASS="LITERAL"
835 
>#define</TT
836 
>. For options with the
837 
<TT
838 
CLASS="LITERAL"
839 
>bool</TT
840 
> or <TT
841 
CLASS="LITERAL"
842 
>none</TT
843 
> flavors a single
844 
<TT
845 
CLASS="LITERAL"
846 
>#define</TT
847 
> will be generated using the value
848 
<TT
849 
CLASS="LITERAL"
850 
>1</TT
851 
>. For options with the <TT
852 
CLASS="LITERAL"
853 
>data</TT
854 
> or
855 
<TT
856 
CLASS="LITERAL"
857 
>booldata</TT
858 
> flavors either one or two
859 
<TT
860 
CLASS="LITERAL"
861 
>#define's</TT
862 
> will be generated.</P
863 
></LI
864 
><LI
865 
><P
866 
>After processing all <SPAN
867 
CLASS="PROPERTY"
868 
>define</SPAN
869 
> properties, the component framework will
870 
look for any <SPAN
871 
CLASS="PROPERTY"
872 
>if_define</SPAN
873 
> properties. These take the following form:</P
874 
><TABLE
875 
BORDER="5"
876 
BGCOLOR="#E0E0F0"
877 
WIDTH="70%"
878 
><TR
879 
><TD
880 
><PRE
881 
CLASS="PROGRAMLISTING"
882 
>    if_define [-file=&lt;filename&gt;] &lt;symbol1&gt; &lt;symbol2&gt;</PRE
883 
></TD
884 
></TR
885 
></TABLE
886 
><P
887 
>For example:</P
888 
><TABLE
889 
BORDER="5"
890 
BGCOLOR="#E0E0F0"
891 
WIDTH="70%"
892 
><TR
893 
><TD
894 
><PRE
895 
CLASS="PROGRAMLISTING"
896 
>    if_define CYGSRC_KERNEL CYGDBG_USE_ASSERTS</PRE
897 
></TD
898 
></TR
899 
></TABLE
900 
><P
901 
>The following will be generated in the configuration header file:</P
902 
><TABLE
903 
BORDER="5"
904 
BGCOLOR="#E0E0F0"
905 
WIDTH="70%"
906 
><TR
907 
><TD
908 
><PRE
909 
CLASS="PROGRAMLISTING"
910 
>#ifdef CYGSRC_KERNEL
911 
# define CYGDBG_USE_ASSERTS
912 
#endif</PRE
913 
></TD
914 
></TR
915 
></TABLE
916 
><P
917 
>Typical kernel source code would begin with the following construct:</P
918 
><TABLE
919 
BORDER="5"
920 
BGCOLOR="#E0E0F0"
921 
WIDTH="70%"
922 
><TR
923 
><TD
924 
><PRE
925 
CLASS="PROGRAMLISTING"
926 
>#define CYGSRC_KERNEL 1
927 
#include &lt;pkgconf/kernel.h&gt;
928 
#include &lt;cyg/infra/cyg_ass.h&gt;</PRE
929 
></TD
930 
></TR
931 
></TABLE
932 
><P
933 
>The infrastructure header file <TT
934 
CLASS="FILENAME"
935 
>cyg/infra/cyg_ass.h</TT
936 
> only checks for symbols
937 
such as <TT
938 
CLASS="LITERAL"
939 
>CYGDBG_USE_ASSERTS</TT
940 
>, and has no special
941 
knowledge of the kernel or any other package. The <SPAN
942 
CLASS="PROPERTY"
943 
>if_define</SPAN
944 
> property
945 
will only affect code that defines the symbol
946 
<TT
947 
CLASS="LITERAL"
948 
>CYGSRC_KERNEL</TT
949 
>, so typically only kernel source
950 
code. If the option is enabled then assertion support will be enabled
951 
for the kernel source code only. If the option is inactive or disabled
952 
then kernel assertions will be disabled. Assertions in other packages
953 
are not affected. Thus the <SPAN
954 
CLASS="PROPERTY"
955 
>if_define</SPAN
956 
> property allows control over
957 
assertions, tracing, and similar facilities at the level of individual
958 
packages, or at finer levels such as components or even single source
959 
files if desired.</P
960 
><DIV
961 
CLASS="NOTE"
962 
><BLOCKQUOTE
963 
CLASS="NOTE"
964 
><P
965 
><B
966 
>Note: </B
967 
>Current <SPAN
968 
CLASS="APPLICATION"
969 
>eCos</SPAN
970 
> packages do not yet make use of this facility. Instead
971 
there is a single global configuration option
972 
<TT
973 
CLASS="VARNAME"
974 
>CYGDBG_USE_ASSERTS</TT
975 
> which is used to enable or
976 
disable assertions for all packages. This issue should be addressed in
977 
a future release of the system.</P
978 
></BLOCKQUOTE
979 
></DIV
980 
><P
981 
>As with the <SPAN
982 
CLASS="PROPERTY"
983 
>define</SPAN
984 
> property, the <SPAN
985 
CLASS="PROPERTY"
986 
>if_define</SPAN
987 
> property takes an
988 
option <TT
989 
CLASS="LITERAL"
990 
>-file</TT
991 
> with a single legal value
992 
<TT
993 
CLASS="LITERAL"
994 
>system.h</TT
995 
>. This allows the output to be redirected
996 
to <TT
997 
CLASS="FILENAME"
998 
>pkgconf/system.h</TT
999 
> if and when
1000 
necessary. </P
1001 
></LI
1002 
><LI
1003 
><P
1004 
>The final property that is relevant to configuration header file
1005 
generation is <SPAN
1006 
CLASS="PROPERTY"
1007 
>define_proc</SPAN
1008 
>. This takes a single argument, a <SPAN
1009 
CLASS="APPLICATION"
1010 
>Tcl</SPAN
1011 
>
1012 
fragment that can add arbitrary data to the global header <TT
1013 
CLASS="FILENAME"
1014 
>pkgconf/system.h</TT
1015 
> and to the package's own
1016 
header. When the <SPAN
1017 
CLASS="PROPERTY"
1018 
>define_proc</SPAN
1019 
> script is invoked two variables will be
1020 
set up to allow access to these headers: <TT
1021 
CLASS="LITERAL"
1022 
>cdl_header</TT
1023 
>
1024 
will be a channel to the package's own header file, for example
1025 
<TT
1026 
CLASS="FILENAME"
1027 
>pkgconf/kernel.h</TT
1028 
>;
1029 
<TT
1030 
CLASS="LITERAL"
1031 
>cdl_system_header</TT
1032 
> will be a channel to <TT
1033 
CLASS="FILENAME"
1034 
>pkgconf/system.h</TT
1035 
>. A typical <SPAN
1036 
CLASS="PROPERTY"
1037 
>define_proc</SPAN
1038 
>
1039 
script will use the <SPAN
1040 
CLASS="APPLICATION"
1041 
>Tcl</SPAN
1042 
> <TT
1043 
CLASS="LITERAL"
1044 
>puts</TT
1045 
> command to output
1046 
data to one of these channels, for example:</P
1047 
><TABLE
1048 
BORDER="5"
1049 
BGCOLOR="#E0E0F0"
1050 
WIDTH="70%"
1051 
><TR
1052 
><TD
1053 
><PRE
1054 
CLASS="PROGRAMLISTING"
1055 
>cdl_option &lt;name&gt; {
1056 
    &#8230;
1057 
    define_proc {
1058 
        puts $::cdl_header "#define XXX 1"
1059 
    }
1060 
}</PRE
1061 
></TD
1062 
></TR
1063 
></TABLE
1064 
><DIV
1065 
CLASS="NOTE"
1066 
><BLOCKQUOTE
1067 
CLASS="NOTE"
1068 
><P
1069 
><B
1070 
>Note: </B
1071 
>In the current implementation the use of <SPAN
1072 
CLASS="PROPERTY"
1073 
>define_proc</SPAN
1074 
> is limited
1075 
because the <SPAN
1076 
CLASS="APPLICATION"
1077 
>Tcl</SPAN
1078 
> script cannot access any of the configuration data.
1079 
Therefore the script is limited to writing constant data to the
1080 
configuration headers. This is a major limitation which will be
1081 
addressed in a future release of the component framework.</P
1082 
></BLOCKQUOTE
1083 
></DIV
1084 
></LI
1085 
></OL
1086 
><DIV
1087 
CLASS="NOTE"
1088 
><BLOCKQUOTE
1089 
CLASS="NOTE"
1090 
><P
1091 
><B
1092 
>Note: </B
1093 
>Generating C header files with <TT
1094 
CLASS="LITERAL"
1095 
>#define's</TT
1096 
> for the
1097 
configuration data suffices for existing packages written in some
1098 
combination of C, C++ and assembler. It can also be used in
1099 
conjunction with some other languages, for example by first passing
1100 
the source code through the C preprocessor and feeding the result into
1101 
the appropriate compiler. In future versions of the component
1102 
framework additional programming languages such as Java may be
1103 
supported, and the configuration data may also be written to files in
1104 
some format other than C preprocessor directives. </P
1105 
></BLOCKQUOTE
1106 
></DIV
1107 
><DIV
1108 
CLASS="NOTE"
1109 
><BLOCKQUOTE
1110 
CLASS="NOTE"
1111 
><P
1112 
><B
1113 
>Note: </B
1114 
>At present there is no way for application or package source code to
1115 
get hold of all the configuration details related to the current
1116 
hardware. Instead that information is spread over various different
1117 
configuration headers for the HAL and device driver packages, with
1118 
some of the information going into <TT
1119 
CLASS="FILENAME"
1120 
>pkgconf/system.h</TT
1121 
>. It is possible that in
1122 
some future release of the system there will be another global
1123 
configuration header file <TT
1124 
CLASS="FILENAME"
1125 
>pkgconf/hardware.h</TT
1126 
> which either contains the
1127 
configuration details for the various hardware-specific packages or
1128 
which <TT
1129 
CLASS="LITERAL"
1130 
>#include's</TT
1131 
> all the hardware-specific
1132 
configuration headers. The desirability and feasibility of such a
1133 
scheme are still to be determined. To avoid future incompatibility
1134 
problems as a result of any such changes, it is recommended that all
1135 
hardware packages (in other packages containing the <SPAN
1136 
CLASS="PROPERTY"
1137 
>hardware</SPAN
1138 
>
1139 
property) use the <SPAN
1140 
CLASS="PROPERTY"
1141 
>define_header</SPAN
1142 
> property to specify explicitly which
1143 
configuration header should be generated.</P
1144 
></BLOCKQUOTE
1145 
></DIV
1146 
><DIV
1147 
CLASS="SECT2"
1148 
><H2
1149 
CLASS="SECT2"
1150 
><A
1151 
NAME="BUILD.HEADERS.SYSTEM.H">The <TT
1152 
CLASS="FILENAME"
1153 
>system.h</TT
1154 
> Header</H2
1155 
><P
1156 
>Typically configuration header files are <TT
1157 
CLASS="LITERAL"
1158 
>#include'd</TT
1159 
>
1160 
only by the package's source code at build time, or by a package's
1161 
exported header files if the interface provided by the package may be
1162 
affected by a configuration option. There should be no need for
1163 
application code to know the details of individual configuration
1164 
options, instead the configuration should specifically meet the needs
1165 
of the application.</P
1166 
><P
1167 
>There are always exceptions. Application code may want to adapt to
1168 
configuration options, for example to do different things for ROM and
1169 
RAM booting systems, or when it is necessary to support several
1170 
different target boards. This is especially true if the code in question
1171 
is really re-usable library code which has not been converted to an
1172 
eCos package, and hence cannot use any CDL facilities.</P
1173 
><P
1174 
>A major problem here is determining which packages are in the
1175 
configuration: attempting to <TT
1176 
CLASS="LITERAL"
1177 
>#include</TT
1178 
> a header file
1179 
such as <TT
1180 
CLASS="FILENAME"
1181 
>pkgconf/net.h</TT
1182 
>
1183 
when it is not known for certain that that particular package is part
1184 
of the configuration will result in compilation errors. The global
1185 
header file <TT
1186 
CLASS="FILENAME"
1187 
>pkgconf/system.h</TT
1188 
>
1189 
serves to provide such information, so application code can use
1190 
techniques like the following:</P
1191 
><TABLE
1192 
BORDER="5"
1193 
BGCOLOR="#E0E0F0"
1194 
WIDTH="70%"
1195 
><TR
1196 
><TD
1197 
><PRE
1198 
CLASS="PROGRAMLISTING"
1199 
>#include &lt;pkgconf/system.h&gt;
1200 
#ifdef CYGPKG_NET
1201 
# include &lt;pkgconf/net.h&gt;
1202 
#endif</PRE
1203 
></TD
1204 
></TR
1205 
></TABLE
1206 
><P
1207 
>This will compile correctly irrespective of the eCos configuration,
1208 
and subsequent code can use <TT
1209 
CLASS="LITERAL"
1210 
>#ifdef</TT
1211 
> or similar
1212 
directives on <TT
1213 
CLASS="LITERAL"
1214 
>CYGPKG_NET</TT
1215 
> or any of the
1216 
configuration options in that package. </P
1217 
><P
1218 
>In addition to determining whether or not a package is present, the
1219 
global configuration header file can also be used to find out the
1220 
specific version of a package that is being used. This can be useful
1221 
if a more recent version exports additional functionality. It may also
1222 
be necessary to adapt to incompatible changes in the exported
1223 
interface or to changes in behaviour. For each package the
1224 
configuration system will typically <TT
1225 
CLASS="LITERAL"
1226 
>#define</TT
1227 
> three
1228 
symbols, for example for a V1.3.1 release:</P
1229 
><TABLE
1230 
BORDER="5"
1231 
BGCOLOR="#E0E0F0"
1232 
WIDTH="70%"
1233 
><TR
1234 
><TD
1235 
><PRE
1236 
CLASS="PROGRAMLISTING"
1237 
>#define CYGNUM_NET_VERSION_MAJOR 1
1238 
#define CYGNUM_NET_VERSION_MINOR 3
1239 
#define CYGNUM_NET_VERSION_RELEASE 1</PRE
1240 
></TD
1241 
></TR
1242 
></TABLE
1243 
><P
1244 
>There are a number of problems associated with such version
1245 
<TT
1246 
CLASS="LITERAL"
1247 
>#define's</TT
1248 
>. The first restriction is that the
1249 
package must follow the standard naming conventions, so the package
1250 
name must be of the form <TT
1251 
CLASS="LITERAL"
1252 
>xxxPKG_yyy</TT
1253 
>. The three
1254 
characters immediately preceding the first underscore must be
1255 
<TT
1256 
CLASS="LITERAL"
1257 
>PKG</TT
1258 
>, and will be replaced with
1259 
<TT
1260 
CLASS="LITERAL"
1261 
>NUM</TT
1262 
> when generating the version
1263 
<TT
1264 
CLASS="LITERAL"
1265 
>#define's</TT
1266 
>. If a package does not follow the naming
1267 
convention then no version <TT
1268 
CLASS="LITERAL"
1269 
>#define's</TT
1270 
> will be
1271 
generated. </P
1272 
><P
1273 
>Assuming the package does follow the naming conventions, the
1274 
configuration tools will always generate three version
1275 
<TT
1276 
CLASS="LITERAL"
1277 
>#define's</TT
1278 
> for the major, minor, and release
1279 
numbers. The symbol names are obtained from the package name by
1280 
replacing <TT
1281 
CLASS="LITERAL"
1282 
>PKG</TT
1283 
> with <TT
1284 
CLASS="LITERAL"
1285 
>NUM</TT
1286 
> and
1287 
appending <TT
1288 
CLASS="LITERAL"
1289 
>_VERSION_MAJOR</TT
1290 
>,
1291 
<TT
1292 
CLASS="LITERAL"
1293 
>_VERSION_MINOR</TT
1294 
> and
1295 
<TT
1296 
CLASS="LITERAL"
1297 
>_VERSION_RELEASE</TT
1298 
>. It is assumed that the resulting
1299 
symbols will not clash with any configuration option names. The values
1300 
for the <TT
1301 
CLASS="LITERAL"
1302 
>#define's</TT
1303 
> are determined by searching the
1304 
version string for sequences of digits, optionally preceded by a minus
1305 
sign. It is possible that some or all of the numbers are absent in any
1306 
given version string, in which case <TT
1307 
CLASS="LITERAL"
1308 
>-1</TT
1309 
> will be used
1310 
in the <TT
1311 
CLASS="LITERAL"
1312 
>#define</TT
1313 
>. For example, given a version string
1314 
of <TT
1315 
CLASS="LITERAL"
1316 
>V1.12beta</TT
1317 
>, the major version number is
1318 
<TT
1319 
CLASS="LITERAL"
1320 
>1</TT
1321 
>, the minor number is <TT
1322 
CLASS="LITERAL"
1323 
>12</TT
1324 
>, and
1325 
the release number is <TT
1326 
CLASS="LITERAL"
1327 
>-1</TT
1328 
>. Given a version string of
1329 
<TT
1330 
CLASS="LITERAL"
1331 
>beta</TT
1332 
> all three numbers would be set to
1333 
<TT
1334 
CLASS="LITERAL"
1335 
>-1</TT
1336 
>.</P
1337 
><P
1338 
>There is special case code for the version <TT
1339 
CLASS="LITERAL"
1340 
>current</TT
1341 
>,
1342 
which typically corresponds to a development version obtained via
1343 
anonymous CVS or similar means. The configuration system has special
1344 
built-in knowledge of this version, and will assume it is more recent
1345 
than any specific release number. The global configuration header
1346 
defines a special symbol <TT
1347 
CLASS="LITERAL"
1348 
>CYGNUM_VERSION_CURRENT</TT
1349 
>,
1350 
and this will be used as the major version number when version
1351 
<TT
1352 
CLASS="LITERAL"
1353 
>current</TT
1354 
> of a package is used:</P
1355 
><TABLE
1356 
BORDER="5"
1357 
BGCOLOR="#E0E0F0"
1358 
WIDTH="70%"
1359 
><TR
1360 
><TD
1361 
><PRE
1362 
CLASS="PROGRAMLISTING"
1363 
>#define CYGNUM_VERSION_CURRENT 0x7fffff00
1364 
...
1365 
#define CYGNUM_INFRA_VERSION_MAJOR CYGNUM_VERSION_CURRENT
1366 
#define CYGNUM_INFRA_VERSION_MINOR -1
1367 
#define CYGNUM_INFRA_VERSION_RELEASE -1</PRE
1368 
></TD
1369 
></TR
1370 
></TABLE
1371 
><P
1372 
>The large number used for <TT
1373 
CLASS="LITERAL"
1374 
>CYGNUM_VERSION_CURRENT</TT
1375 
>
1376 
should ensure that major version comparisons work as expected, while
1377 
still allowing for a small amount of arithmetic in case that proves
1378 
useful. </P
1379 
><P
1380 
>It should be noted that this implementation of version
1381 
<TT
1382 
CLASS="LITERAL"
1383 
>#define's</TT
1384 
> will not cope with all version number
1385 
schemes. However for many cases it should suffice.</P
1386 
></DIV
1387 
></DIV
1388 
><DIV
1389 
CLASS="NAVFOOTER"
1390 
><HR
1391 
ALIGN="LEFT"
1392 
WIDTH="100%"><TABLE
1393 
SUMMARY="Footer navigation table"
1394 
WIDTH="100%"
1395 
BORDER="0"
1396 
CELLPADDING="0"
1397 
CELLSPACING="0"
1398 
><TR
1399 
><TD
1400 
WIDTH="33%"
1401 
ALIGN="left"
1402 
VALIGN="top"
1403 
><A
1404 
HREF="build.html"
1405 
ACCESSKEY="P"
1406 
>Prev</A
1407 
></TD
1408 
><TD
1409 
WIDTH="34%"
1410 
ALIGN="center"
1411 
VALIGN="top"
1412 
><A
1413 
HREF="cdl-guide.html"
1414 
ACCESSKEY="H"
1415 
>Home</A
1416 
></TD
1417 
><TD
1418 
WIDTH="33%"
1419 
ALIGN="right"
1420 
VALIGN="top"
1421 
><A
1422 
HREF="build.make.html"
1423 
ACCESSKEY="N"
1424 
>Next</A
1425 
></TD
1426 
></TR
1427 
><TR
1428 
><TD
1429 
WIDTH="33%"
1430 
ALIGN="left"
1431 
VALIGN="top"
1432 
>The Build Process</TD
1433 
><TD
1434 
WIDTH="34%"
1435 
ALIGN="center"
1436 
VALIGN="top"
1437 
><A
1438 
HREF="build.html"
1439 
ACCESSKEY="U"
1440 
>Up</A
1441 
></TD
1442 
><TD
1443 
WIDTH="33%"
1444 
ALIGN="right"
1445 
VALIGN="top"
1446 
>Building eCos</TD
1447 
></TR
1448 
></TABLE
1449 
></DIV
1450 
></BODY
1451 
></HTML
1452 
>

powered by: WebSVN 2.1.0

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