1 /*
2 * Copyright (c) 2013, Texas Instruments Incorporated
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);
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 {@link #libType Build.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 {@link #libType Build.libType}.
185 */
186 config Bool logsEnabled = true;
188 /*!
189 * ======== libDir ========
190 */
191 config String libDir = null;
193 /*!
194 * ======== getDefaultCustomCCOpts ========
195 */
196 String getDefaultCustomCCOpts();
198 /*!
199 * ======== getDefs ========
200 * Get the compiler -D options necessary to build
201 */
202 String getDefs();
204 /*!
205 * ======== getCFiles ========
206 * Get the library C source files.
207 */
208 String getCFiles(String target);
210 /*!
211 * ======== getAsmFiles ========
212 * Get the library Asm source files.
213 */
214 Any getAsmFiles(String target);
216 /*
217 * ======== buildLibs ========
218 * This function generates the makefile goals for the libraries
219 * produced by a ti.sysbios package.
220 */
221 function buildLibs(objList, relList, filter, xdcArgs);
223 /*!
224 * ======== getLibs ========
225 * Common getLibs() for all ipc packages.
226 */
227 function getLibs(pkg);
228 }