SDOCM00115098 New MultiProc cdoc links for "See Also" are garbled
[ipc/ipcdev.git] / packages / ti / sdo / ipc / Build.xdc
1 /*
2  * Copyright (c) 2013-2015 Texas Instruments Incorporated - http://www.ti.com
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * *  Redistributions of source code must retain the above copyright
10  *    notice, this list of conditions and the following disclaimer.
11  *
12  * *  Redistributions in binary form must reproduce the above copyright
13  *    notice, this list of conditions and the following disclaimer in the
14  *    documentation and/or other materials provided with the distribution.
15  *
16  * *  Neither the name of Texas Instruments Incorporated nor the names of
17  *    its contributors may be used to endorse or promote products derived
18  *    from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
33 /*
34  *  ======== Build.xdc ========
35  *  metaonly module to support building various package/product libraries
36  *
37  */
39 /*!
40  *  ======== Build ========
41  */
43 @Template("./Build.xdt")
44 metaonly module Build
45 {
46     /*!
47      *  ======== LibType ========
48      *  IPC library selection options
49      *
50      *  This enumeration defines all the IPC library types provided
51      *  by the product. You can select the library type by setting
52      *  the {@link #libType Build.libType} configuration parameter.
53      *
54      *  @field(LibType_Instrumented) The library supplied is prebuilt
55      *  with logging and assertions enabled.
56      *
57      *  @field(LibType_NonInstrumented) The library supplied is prebuilt
58      *  with logging and assertions disabled.
59      *
60      *  @field(LibType_Custom) This option builds the IPC library from
61      *  sources using the options specified by {@link #customCCOpts}.
62      *  Only the modules and APIs that your application uses are
63      *  contained in the resulting executable. Program optimization is
64      *  performed to reduce the size of the executable and improve
65      *  performance. Enough debug information is retained to allow you
66      *  to step through the application code in CCS and locate global
67      *  variables.
68      *
69      *  @field(LibType_Debug) This option is similar to the LibType_Custom
70      *  option in that it builds the IPC library from sources and omits
71      *  modules and APIs that your code does not use. However, no program
72      *  optimization is performed. The resulting executable is fully
73      *  debuggable, and you can step into IPC code. The tradeoff is that
74      *  the executable is larger and runs slower than builds that use the
75      *  LibType_Custom option.
76      *
77      *  @field(LibType_PkgLib) This option uses the individual libraries
78      *  built by each package of the IPC product. These libraries are
79      *  not shipped. You must build the product to generate the package
80      *  libraries. See the IPC Install Guides (links in the Release
81      *  Note) for details on building the IPC product.
82      *
83      *  @see #libType
84      */
85     enum LibType {
86         LibType_Instrumented,           /*! Instrumented */
87         LibType_NonInstrumented,        /*! Non-instrumented */
88         LibType_Custom,                 /*! Custom (Optimized) */
89         LibType_Debug,                  /*! Custom (Debug) */
90         LibType_PkgLib                  /*! Use package library */
91     };
93     /*!
94      *  ======== libType ========
95      *  IPC library type
96      *
97      *  The IPC runtime is provided in the form of a library that is
98      *  linked with your application. Several forms of this library are
99      *  provided with the IPC product. In addition, there is an option
100      *  to build the library from source. This configuration parameter
101      *  allows you to select the form of the IPC library to use.
102      *
103      *  The default value of libType is taken from the BIOS.libType
104      *  configuration parameter. For a complete list of options and
105      *  what they offer see {@link #LibType}.
106      */
107     config LibType libType;
109     /*!
110      *  ======== customCCOpts ========
111      *  Compiler options used when building a custom IPC library
112      *
113      *  When {@link #libType Build.libType} is set to
114      *  {@link #LibType_Custom Build_LibType_Custom} or
115      *  {@link #LibType_Debug Build_LibType_Debug}, this string contains
116      *  the options passed to the compiler during any re-build of the
117      *  IPC sources.
118      *
119      *  In addition to the options specified by `Build.customCCOpts`,
120      *  several `-D` and `-I` options are also passed to the compiler.
121      *  The options specified by `Build.customCCOpts` preceed the `-D`
122      *  and `-I` options passed to the compiler on the command line.
123      *
124      *  To view the custom compiler options, add the following line
125      *  to your config script:
126      *
127      *  @p(code)
128      *  print("Build.customCCOpts="+Build.customCCOpts);
129      *  @p
130      *
131      *  When {@link #libType Build.libType} is set to
132      *  {@link #LibType_Custom Build_LibType_Custom}, `Build.customCCOpts`
133      *  is initialized to create a highly optimized library.
134      *
135      *  When {@link #libType Build.libType} is set to
136      *  {@link #LibType_Debug Build_LibType_Debug}, `Build.customCCOpts`
137      *  is initialized to create a non-optimized library that can be
138      *  used to single-step through the APIs with the CCS debugger.
139      *
140      *  @a(Warning)
141      *  The default value of `Build.customCCOpts`, which is derived from
142      *  the target specified by your configuration, includes runtime
143      *  model options (such as endianess) that must be the same for all
144      *  sources built and linked into your application. You must not
145      *  change or add any options that can alter the runtime model
146      *  specified by the default value of `Build.customCCOpts`.
147      */
148     config String customCCOpts;
150     /*!
151      *  ======== assertsEnabled ========
152      *  IPC assert checking in custom library enable flag
153      *
154      *  When set to true, assert checking code is compiled into
155      *  the custom library created when {@link #libType Build.libType}
156      *  is set to {@link #LibType_Custom Build_LibType_Custom} or
157      *  {@link #LibType_Debug Build_LibType_Debug}.
158      *
159      *  When set to false, assert checking code is removed from the
160      *  custom library created when Build.libType is set to
161      *  Build.LibType_Custom or Build.LibType_Debug. This option can
162      *  considerably improve runtime performance as well significantly
163      *  reduce the application's code size.
164      *
165      *  @see #libType
166      */
167     config Bool assertsEnabled = true;
169     /*!
170      *  ======== logsEnabled ========
171      *  IPC log support in custom library enable flag
172      *
173      *  When set to true, IPC execution log code is compiled into
174      *  the custom library created when {@link #libType Build.libType}
175      *  is set to {@link #LibType_Custom Build_LibType_Custom} or
176      *  {@link #LibType_Debug Build_LibType_Debug}.
177      *
178      *  When set to false, all log code is removed from the custom
179      *  library created when Build.libType = Build.LibType_Custom or
180      *  Build.LibType_Debug. This option can considerably improve runtime
181      *  performance as well signficantly reduce the application's code
182      *  size.
183      *
184      *  @see #libType
185      */
186     config Bool logsEnabled = true;
188     /*!
189      *  ======== libDir ========
190      */
191     config String libDir = null;
193     /*
194      *  ======== getCCOpts ========
195      *  Get the compiler options necessary to build
196      */
197     metaonly String getCCOpts(String target);
199     /*!
200      *  ======== getDefaultCustomCCOpts ========
201      */
202     String getDefaultCustomCCOpts();
204     /*!
205      *  ======== getDefs ========
206      *  Get the compiler -D options necessary to build
207      */
208     String getDefs();
210     /*!
211      *  ======== getCFiles ========
212      *  Get the library C source files.
213      */
214     String getCFiles(String target);
216     /*!
217      *  ======== getAsmFiles ========
218      *  Get the library Asm source files.
219      */
220     Any getAsmFiles(String target);
222     /*
223      *  ======== buildLibs ========
224      *  This function generates the makefile goals for the libraries
225      *  produced by a ti.sysbios package.
226      */
227     function buildLibs(objList, relList, filter, xdcArgs);
229     /*!
230      *  ======== getLibs ========
231      *  Common getLibs() for all ipc packages.
232      */
233     function getLibs(pkg);