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.